https://github.com/fluxo-kt/aza-pg
Opinionated PostgreSQL 18 container, setup and harness
https://github.com/fluxo-kt/aza-pg
pgflow pgmq postgres postgressql timescaledb
Last synced: 26 days ago
JSON representation
Opinionated PostgreSQL 18 container, setup and harness
- Host: GitHub
- URL: https://github.com/fluxo-kt/aza-pg
- Owner: fluxo-kt
- License: mit
- Created: 2025-11-01T12:04:15.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-05-17T15:43:51.000Z (27 days ago)
- Last Synced: 2026-05-17T16:41:34.771Z (26 days ago)
- Topics: pgflow, pgmq, postgres, postgressql, timescaledb
- Language: TypeScript
- Homepage: https://wordian.ai
- Size: 4.2 MB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# aza-pg
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
## Requirements
- Docker Engine 24+ with Docker Compose v2
- GNU/Linux or macOS host (Windows via WSL2)
- `bun` for 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_MEMORY` env var
- Connection limits: 60 (≤2GB), 84 (2-4GB), 102 (4-8GB), 120 (≥8GB) with `mixed` workload default
- PgBouncer transaction mode: No prepared statements, advisory locks, or LISTEN/NOTIFY
## Extensions
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 cat /etc/postgresql/version-info.txt`
### Popular Use Cases
**AI/ML & Vector Search**
```sql
CREATE EXTENSION vector; -- pgvector: Embeddings & similarity search
CREATE EXTENSION vectorscale; -- pgvectorscale: DiskANN indexing
```
**Time-Series Analytics**
```sql
CREATE EXTENSION timescaledb; -- Hypertables, continuous aggregates
CREATE EXTENSION timescaledb_toolkit; -- Analytical hyperfunctions
```
**Full-Text Search**
```sql
CREATE EXTENSION pgroonga; -- Multi-language full-text search
CREATE EXTENSION rum; -- Fast phrase search
CREATE EXTENSION pg_trgm; -- Trigram similarity (builtin)
```
**Security & Compliance**
```sql
CREATE EXTENSION pgaudit; -- Audit logging (preloaded)
CREATE EXTENSION pgsodium; -- Encryption functions
CREATE EXTENSION supabase_vault; -- Supabase Vault secrets management
```
**Operations & Automation**
```sql
CREATE EXTENSION pg_cron; -- Job scheduler (preloaded)
CREATE EXTENSION pg_repack; -- Online table reorganization
CREATE EXTENSION pg_partman; -- Partition management
```
See [docs/EXTENSIONS.md](docs/EXTENSIONS.md) for complete catalog.
## Image Details
~250MB compressed / ~900MB uncompressed (amd64 + arm64). Multi-stage build with parallel compilation. Runtime: ca-certificates, zstd, lz4.
## Quick Start
**Security:** Default binding 127.0.0.1 (localhost). TLS disabled. Set `POSTGRES_BIND_IP=0.0.0.0` for network access. See [Production](#security) for hardening.
### Setup
```bash
docker network create monitoring
bun run build # 2min with remote cache
docker run --rm aza-pg:pg18 psql --version
```
### Deploy
```bash
cd stacks/primary
cp .env.example .env
# Edit .env: Set POSTGRES_PASSWORD, PGBOUNCER_AUTH_PASS, PG_REPLICATION_PASSWORD
docker compose up -d
```
**Ports:** Postgres 5432, PgBouncer 6432, Exporters 9187/9127
**Variants:** `stacks/single` (no PgBouncer), add `-f compose.dev.yml` for dev
## Stacks
| 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}`.
## Configuration
### Auto-Config
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_net, pg_stat_monitor, pg_stat_statements, pgaudit, pgsodium, safeupdate, timescaledb (add optional via `POSTGRES_SHARED_PRELOAD_LIBRARIES`).
**PgBouncer:** Set `PGBOUNCER_AUTH_PASS` in .env. Escape `:` and `\` only.
### Extension Customization
Edit `scripts/extensions/manifest-data.ts` → `bun run generate` → `bun run build`. Cannot disable preloaded (auto_explain, pg_cron, pg_net, pg_stat_monitor, pg_stat_statements, pgaudit, pgsodium, safeupdate, timescaledb). See [docs/EXTENSIONS.md](docs/EXTENSIONS.md).
## Monitoring
postgres_exporter (replication lag, memory, uptime). Prometheus config:
```yaml
scrape_configs:
- job_name: "postgres"
static_configs:
- targets: ["localhost:9187", "localhost:9188"]
- job_name: "pgbouncer"
static_configs:
- targets: ["localhost:9127"]
```
## Build & Test
```bash
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 image
```
**Regression Testing:**
```bash
# 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 --regression
```
**Test 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](docs/REGRESSION-TESTING.md) for comprehensive regression testing documentation.
**Release Validation:** [RELEASE-VALIDATION.md](RELEASE-VALIDATION.md) contains comprehensive validation results for the latest published release image (updated with each release).
See [docs/BUILD.md](docs/BUILD.md) and [docs/TESTING.md](docs/TESTING.md).
## Operations
**Database Management:**
```bash
# 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
```
⚠️ **CRITICAL:** Replica promotion is a one-way operation. See [docs/OPERATIONS.md](docs/OPERATIONS.md) for safety warnings, detailed usage, troubleshooting, and best practices.
## Troubleshooting
| 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=` |
| Slow queries | Review `pg_stat_statements`, `auto_explain` logs |
| Slow compilation | Use `bun run build` (remote cache) |
## Security
**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](docs/PRODUCTION.md).
## Coolify Deployment
aza-pg works with [Coolify](https://coolify.io) with one critical configuration change.
### Quick Setup
1. Create PostgreSQL resource with image: `ghcr.io/fluxo-kt/aza-pg:18`
2. **Change volume mount** from `/var/lib/postgresql/data` to `/var/lib/postgresql`
3. Set `POSTGRES_PASSWORD` environment variable
4. (Optional) Set `POSTGRES_BIND_IP=0.0.0.0` for network access
5. (Optional) Set `POSTGRES_MEMORY` to match Coolify's memory limit
See [docs/COOLIFY.md](docs/COOLIFY.md) for complete setup guide, SSL configuration, and troubleshooting.
### Why the Different Mount Path?
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.
## FAQ
**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=` or modify entrypoint.
**Docker Desktop?** Yes, auto-detects limits.
## License
MIT License - see [LICENSE](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.
## Contributing
Fork → change → `bun run generate` (if manifest changed) → `bun run test:all` → PR
**For GitHub repository setup:** See [docs/GITHUB_ENVIRONMENT_SETUP.md](docs/GITHUB_ENVIRONMENT_SETUP.md) for configuring GitHub Environments, branch protection, and CI/CD workflows.