PostgreSQL 18 with auto-configuration, comprehensive extensions, and deployment stacks. Single Docker image adapts to 2-16GB RAM (scales to 128GB), 1-64 cores. Docker Compose only.
Open Source Notice: This is MIT licensed open source software provided AS IS with NO WARRANTY, NO SUPPORT, and NO LIABILITY. Docker images are published for convenience but come with NO GUARANTEES of functionality, security, or maintenance. Use at your own risk.
Features: Auto-config (RAM/CPU detection), SHA-pinned (reproducibility), PgBouncer pooling, replication, SCRAM-SHA-256, monitoring
- Docker Engine 24+ with Docker Compose v2
- GNU/Linux or macOS host (Windows via WSL2)
bunfor regenerating configs (curl -fsSL https://bun.sh/install | bash)
Limitations:
- PostgreSQL 18 only (no multi-version support)
- Docker Compose only (no Kubernetes)
- Auto-config requires cgroup v2 or
POSTGRES_MEMORYenv var - Connection limits: 60 (≤2GB), 84 (2-4GB), 102 (4-8GB), 120 (≥8GB) with
mixedworkload default - PgBouncer transaction mode: No prepared statements, advisory locks, or LISTEN/NOTIFY
Comprehensive extension catalog across AI/ML, time-series, search, security, and operations categories. Includes builtin contrib modules. Multiple extensions preloaded by default (see docs). See "Popular Use Cases" below for examples.
Complete list: docker run --rm <image> cat /etc/postgresql/version-info.txt
AI/ML & Vector Search
CREATE EXTENSION vector; -- pgvector: Embeddings & similarity search
CREATE EXTENSION vectorscale; -- pgvectorscale: DiskANN indexingTime-Series Analytics
CREATE EXTENSION timescaledb; -- Hypertables, continuous aggregates
CREATE EXTENSION timescaledb_toolkit; -- Analytical hyperfunctionsFull-Text Search
CREATE EXTENSION pgroonga; -- Multi-language full-text search
CREATE EXTENSION rum; -- Fast phrase search
CREATE EXTENSION pg_trgm; -- Trigram similarity (builtin)Security & Compliance
CREATE EXTENSION pgaudit; -- Audit logging (preloaded)
CREATE EXTENSION pgsodium; -- Encryption functions
CREATE EXTENSION supabase_vault; -- Supabase Vault secrets managementOperations & Automation
CREATE EXTENSION pg_cron; -- Job scheduler (preloaded)
CREATE EXTENSION pg_repack; -- Online table reorganization
CREATE EXTENSION pg_partman; -- Partition managementSee docs/EXTENSIONS.md for complete catalog.
~250MB compressed / ~900MB uncompressed (amd64 + arm64). Multi-stage build with parallel compilation. Runtime: ca-certificates, zstd, lz4.
Security: Default binding 127.0.0.1 (localhost). TLS disabled. Set POSTGRES_BIND_IP=0.0.0.0 for network access. See Production for hardening.
docker network create monitoring
bun run build # 2min with remote cache
docker run --rm aza-pg:pg18 psql --versioncd stacks/primary
cp .env.example .env
# Edit .env: Set POSTGRES_PASSWORD, PGBOUNCER_AUTH_PASS, PG_REPLICATION_PASSWORD
docker compose up -dPorts: Postgres 5432, PgBouncer 6432, Exporters 9187/9127
Variants: stacks/single (no PgBouncer), add -f compose.dev.yml for dev
| Stack | Use Case | Postgres | PgBouncer | Exporter(s) |
|---|---|---|---|---|
| Primary | Production | 5432 | 6432 | 9187, 9127 |
| Single | Dev/testing | 5432 | - | 9189 |
| Replica | Replication | 5433 | - | 9188 |
Configs in stacks/{primary,replica,single}.
Detects RAM (cgroup v2 → POSTGRES_MEMORY → /proc/meminfo) and CPU at startup:
| RAM | shared_buffers | effective_cache_size | work_mem | max_connections* |
|---|---|---|---|---|
| 512M | 128M (25%) | 384M (75%) | 1M | 60 |
| 2G | 512M (25%) | 1536M (75%) | 4M | 84 |
| 4G | 1G (25%) | 3G (75%) | 5M | 102 |
| 64G | 9830M (25%) | 49152M (75%) | 32M | 120 |
*Connection limits shown for mixed workload (default). Set POSTGRES_WORKLOAD_TYPE=web (200), oltp (300), or dw (100) to change base limit. RAM-tier scaling applies: 50%/70%/85%/100% for <2GB/2-4GB/4-8GB/≥8GB.
Caps: shared_buffers ≤32GB, work_mem ≤32MB. Preloaded: auto_explain (module), pg_cron, pg_stat_monitor, pg_stat_statements, pgaudit, timescaledb (add optional via POSTGRES_SHARED_PRELOAD_LIBRARIES).
PgBouncer: Set PGBOUNCER_AUTH_PASS in .env. Escape : and \ only.
Edit scripts/extensions/manifest-data.ts → bun run generate → bun run build. Cannot disable preloaded (auto_explain, pg_cron, pg_stat_monitor, pg_stat_statements, pgaudit). See docs/EXTENSIONS.md.
postgres_exporter (replication lag, memory, uptime). Prometheus config:
scrape_configs:
- job_name: "postgres"
static_configs:
- targets: ["localhost:9187", "localhost:9188"]
- job_name: "pgbouncer"
static_configs:
- targets: ["localhost:9127"]bun run build # 2min with remote cache
bun run test:all # Full suite
bun run validate # Validation only (fast)
bun scripts/docker/validate-published-image-artifacts.ts # Validate published imageRegression Testing:
# Run all regression tests (production mode)
bun test:regression:all
# Run specific tier
bun test:regression:core # Tier 1: PostgreSQL core (30 tests)
bun test:regression:extensions # Tier 2: Extension tests (13 extensions)
bun test:regression:interactions # Tier 3: Interaction tests (14 scenarios)
# Run in regression mode (all extensions including disabled ones)
TEST_MODE=regression bun test:regression:all
# Build regression image (includes pgTAP + all extensions)
bun scripts/build.ts --regressionTest Tiers:
- Tier 1: Core PostgreSQL regression (30 official tests, ~3-5 min)
- Tier 2: Extension-specific regression (13 extensions, ~5-8 min)
- Tier 3: Extension interactions (14 scenarios, ~2-4 min)
- Tier 4: pgTAP unit tests (82 SQL tests, ~5-10 min)
See docs/REGRESSION-TESTING.md for comprehensive regression testing documentation.
Release Validation: RELEASE-VALIDATION.md contains comprehensive validation results for the latest published release image (updated with each release).
See docs/BUILD.md and docs/TESTING.md.
Database Management:
# Backup database
bun scripts/tools/backup-postgres.ts mydb backup.sql.gz
# Restore from backup
bun scripts/tools/restore-postgres.ts mydb backup.sql.gz
# Promote replica to primary (failover)
bun scripts/tools/promote-replica.ts replica-container
# Generate SSL certificates (development)
bun scripts/tools/generate-ssl-certs.ts| Issue | Solution |
|---|---|
| COPY path errors | Build from repo root: docker build -f docker/... |
| Connection fails | Check POSTGRES_BIND_IP (default: 127.0.0.1) |
| PgBouncer auth fails | Verify PGBOUNCER_AUTH_PASS in .env |
| Extension fails | Check logs for preload errors |
| High memory usage | Set POSTGRES_MEMORY=<MB> |
| Slow queries | Review pg_stat_statements, auto_explain logs |
| Slow compilation | Use bun run build (remote cache) |
Defaults: SHA-pinned base + extensions, SCRAM-SHA-256 auth, 127.0.0.1 binding, TLS disabled.
Production: 1) Enable TLS (certs + sslmode=require), 2) Set POSTGRES_BIND_IP=0.0.0.0 with firewall, 3) chmod 600 .env, 4) Review pgAudit logs.
See docs/PRODUCTION.md.
aza-pg works with Coolify with one critical configuration change.
- Create PostgreSQL resource with image:
ghcr.io/fluxo-kt/aza-pg:18 - Change volume mount from
/var/lib/postgresql/datato/var/lib/postgresql - Set
POSTGRES_PASSWORDenvironment variable - (Optional) Set
POSTGRES_BIND_IP=0.0.0.0for network access - (Optional) Set
POSTGRES_MEMORYto match Coolify's memory limit
See docs/COOLIFY.md for complete setup guide, SSL configuration, and troubleshooting.
PostgreSQL 18+ uses a new data directory structure (/var/lib/postgresql/18/docker) to support pg_upgrade for major version migrations. Mount the parent directory to let PostgreSQL manage its subdirectory structure.
Kubernetes support? No. Use cloud-native operators.
Why PgBouncer transaction mode? Maximizes connection multiplexing. Use :5432 for prepared statements/advisory locks.
Override auto-config? Set POSTGRES_MEMORY=<MB> or modify entrypoint.
Docker Desktop? Yes, auto-detects limits.
MIT License - see LICENSE file.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. NO SUPPORT, NO GUARANTEES, NO LIABILITY. Use entirely at your own risk.
Fork → change → bun run generate (if manifest changed) → bun run test:all → PR
For GitHub repository setup: See docs/GITHUB_ENVIRONMENT_SETUP.md for configuring GitHub Environments, branch protection, and CI/CD workflows.