Pglayers – Stackable Docker Layers for PostgreSQL Extensions

Pglayers – Stackable Docker Layers for PostgreSQL Extensions

Pglayers turns PostgreSQL extensions into stackable Docker layers

Takeaway: Pglayers packages each PostgreSQL extension as an independent Docker layer, enabling developers to build custom PostgreSQL images by simply stacking the layers they need, which reduces build complexity and improves reproducibility.

What Pglayers does

Pglayers is an open‑source tool that creates a Docker image for every PostgreSQL extension and publishes it to a public container registry. Each image contains only the files required for that extension and declares a FROM relationship to the base PostgreSQL image. By pulling multiple extension images and letting Docker’s layer caching handle the composition, users obtain a final PostgreSQL image that includes all desired extensions without writing a custom Dockerfile.

Why stackable layers matter

  • Modular builds: Adding or removing an extension no longer requires editing a monolithic Dockerfile; you just add or drop a layer reference.
  • Cache efficiency: Docker reuses unchanged layers across builds, so rebuilding after adding a new extension is fast and cheap.
  • Version isolation: Each extension layer is version‑tagged, allowing precise control over which version of an extension is included.
  • Team collaboration: Teams can share a common base image and let individual developers compose their own stacks without affecting the shared base.

QuickStart for Docker Desktop users

The original repository focuses on command‑line usage, but Docker Desktop users can achieve the same result through the GUI:

  1. Open Docker Desktop and go to Images → Pull Image.
  2. Pull the base PostgreSQL image, e.g., postgres:15.
  3. Pull the desired extension layers, for example pglayers/postgis:3.4.0 and pglayers/pg_partman:4.7.0.
  4. In Containers / Apps, create a new container based on the base image.
  5. Under Advanced Settings → Volumes, add the extension layers as additional images (Docker Desktop shows them as additional images you can attach).
  6. Start the container; the extensions are available inside the running PostgreSQL instance.

Providing a visual QuickStart lowers the barrier for less‑technical users who prefer Docker Desktop’s GUI over the CLI.

Community feedback and roadmap hints

  • A commenter suggested adding a domain name for the project to improve branding, indicating interest in a more polished public presence.
  • Another user expressed immediate need for the tool, confirming that the problem it solves is real and timely.
  • A question about supporting pgvectorscale—a vector‑search extension—shows that the community is already thinking about future extensions. Adding support for emerging extensions like pgvectorscale would broaden Pglayers’ appeal in AI‑driven workloads.

How to get started

# Pull the base PostgreSQL image
docker pull postgres:15

# Pull an extension layer, e.g., PostGIS 3.4.0
docker pull ghcr.io/pglayers/postgis:3.4.0

# Run a container that stacks the layers
docker run -d \
  --name mydb \
  -e POSTGRES_PASSWORD=secret \
  ghcr.io/pglayers/postgis:3.4.0

The command above pulls the PostGIS layer, which itself FROM the postgres:15 base, and starts a PostgreSQL instance with PostGIS pre‑installed. To add more extensions, simply pull additional layers and include them in the docker run command using the --layer flag (future versions of Pglayers will expose a convenient CLI for multi‑layer composition).

When to use Pglayers vs. a custom Dockerfile

Situation Recommended approach
You need a handful of well‑maintained extensions and want fast iteration Use Pglayers layers; Docker will cache each extension separately.
You require heavy customisation of the PostgreSQL configuration or need to compile extensions from source Write a custom Dockerfile that builds from source; Pglayers may not cover niche build steps.
Your CI/CD pipeline builds images on every commit Pglayers reduces build time because unchanged extension layers are pulled from the registry instead of rebuilt.

Future directions

The repository currently hosts a modest set of popular extensions (PostGIS, pg_partman, etc.). Community contributions can expand the catalog to include:

  • pgvectorscale for vector similarity search.
  • TimescaleDB for time‑series workloads.
  • Citus for distributed PostgreSQL.

Adding a web UI for browsing available layers, version tags, and compatibility matrices would further lower the entry barrier.

Conclusion

Pglayers demonstrates a pragmatic use of Docker’s layered filesystem to solve a common DevOps pain point: managing PostgreSQL extensions in containerized environments. By treating each extension as a reusable Docker image, developers gain modularity, faster builds, and clearer version control. The project’s early community interest and suggestions—such as GUI QuickStart guides and support for newer extensions—indicate strong potential for broader adoption.

Sources