pglayers: PostgreSQL extensions as stackable Docker layers

# 🚀 Announcing **pglayers**
**Pre‑built PostgreSQL extensions as composable Docker image layers**

**Project:** [https://github.com/pglayers/pglayers](https://github.com/pglayers/pglayers)

---

## 📌 What It Does

**pglayers** publishes **53 PostgreSQL extensions** as **minimal Docker images** (`FROM scratch`).
Each image contains only:

- Shared libraries
- Control files
- SQL scripts
- Correct filesystem paths

You compose them onto the official `postgres` Docker image using `COPY --from`:

```dockerfile
FROM postgres:17
COPY --from=ghcr.io/pglayers/pgx-pgvector:17 / /
COPY --from=ghcr.io/pglayers/pgx-postgis:17 / /
COPY --from=ghcr.io/pglayers/pgx-pg_cron:17 / /
```

No compilation.
No `apt-get`.
No build tools in the final image.
Just `CREATE EXTENSION` as usual.

---

## 🟢 Ready-to-Use Images

For a fully preconfigured setup:

```bash
docker run -d -e POSTGRES_PASSWORD=s ghcr.io/pglayers/pglayers-full:17
```

Includes:

- All **53 extensions**
- `shared_preload_libraries` already set

Also available:

- **Azure profile** (28 extensions) matching *Azure Database for PostgreSQL Flexible Server*
Useful for local dev/test against managed services.

---

## 📦 Extensions Included

53 extensions across major categories:

- **AI/ML:** pgvector
- **Geospatial:** PostGIS, pgRouting, h3-pg
- **Time-series:** TimescaleDB
- **Analytics:** pg_duckdb
- **Observability:** pgaudit, pg_stat_monitor, pg_qualstats, pg_wait_sampling
- **Scheduling:** pg_cron
- **Partitioning:** pg_partman
- **Replication:** pglogical, pg_failover_slots, wal2json
- **Full text search:** pg_textsearch, pg_bigm, rum
- **And 36 more**

**Full list:** [https://github.com/pglayers/pglayers#available-extensions](https://github.com/pglayers/pglayers#available-extensions)

---

## 🐘 Supported PostgreSQL Versions

- **PostgreSQL 17** (stable)
- **PostgreSQL 18** (stable)
- **PostgreSQL 19** (experimental, beta)

All images support **linux/amd64** and **linux/arm64**.

---

## 🧱 PG 18+ Isolated Layout

PostgreSQL 18 introduces `extension_control_path` and `dynamic_library_path`.
pglayers uses these to place each extension in its own namespace:

```
/extensions/<name>/
```

Benefits:

- No file collisions
- Multiple versions of the same library can coexist
- Extensions can be mounted at deploy time (no rebuild)

Example:

```dockerfile
COPY --from=ghcr.io/pglayers/pgx-pgvector:18 / /extensions/pgvector/
COPY --from=ghcr.io/pglayers/pgx-pg_cron:18 / /extensions/pg_cron/
```

PostgreSQL locates them via:

```
extension_control_path = '/extensions/pgvector/share:/extensions/pg_cron/share:$system'
dynamic_library_path = '/extensions/pgvector/lib:/extensions/pg_cron/lib:$libdir'
```

Fully compatible with **CloudNativePG ≥ 1.27**, which auto‑manages these GUCs.

---

## 🧪 Testing

The test suite validates:

- No file collisions between layers
- No overwrites of base image files
- All shared library dependencies resolve (`ldd`)
- `CREATE EXTENSION` succeeds for every extension
- Functional smoke tests + integration tests

---

## 📄 Licensing

Only permissive open-source licenses:

- PostgreSQL
- MIT
- BSD
- Apache 2.0
- ISC
- MPL‑2.0

**PostGIS** and **pgRouting** (GPL‑2.0) included under the standard *mere aggregation* interpretation used in the PostgreSQL ecosystem.

No BSL, SSPL, or proprietary-dependency extensions.

---

## 🤝 Contributing

Contributions welcome!

Adding a new extension requires:

- `Dockerfile`
- `extension.conf`
- `test.sql`

See **CONTRIBUTING.md** for details.

Feedback, bug reports, and extension requests via **GitHub Issues**.

---

## 🙏 Acknowledgements

This project stands on the shoulders of the PostgreSQL community:

- PostgreSQL Global Development Group
- PGDG APT Repository maintainers
- Official PostgreSQL Docker image maintainers
- Debian PostgreSQL team
- Every extension author who publishes under permissive licenses

*pglayers is a thin layer of automation on top of their work. Without the quality and consistency of the upstream ecosystem, this project would not exist.*

**Thanks!
Ismael Mejia**