{"id":34666769,"url":"https://github.com/fluxo-kt/aza-pg","last_synced_at":"2026-05-17T20:08:02.760Z","repository":{"id":323906741,"uuid":"1087673046","full_name":"fluxo-kt/aza-pg","owner":"fluxo-kt","description":"Opinionated PostgreSQL 18 container, setup and harness","archived":false,"fork":false,"pushed_at":"2026-05-17T15:43:51.000Z","size":4407,"stargazers_count":6,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-17T16:41:34.771Z","etag":null,"topics":["pgflow","pgmq","postgres","postgressql","timescaledb"],"latest_commit_sha":null,"homepage":"https://wordian.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluxo-kt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-01T12:04:15.000Z","updated_at":"2026-05-17T15:43:55.000Z","dependencies_parsed_at":"2025-12-19T03:02:02.104Z","dependency_job_id":"53f04a54-5db0-4737-a67d-729169d6d717","html_url":"https://github.com/fluxo-kt/aza-pg","commit_stats":null,"previous_names":["fluxo-kt/aza-pg"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/fluxo-kt/aza-pg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxo-kt%2Faza-pg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxo-kt%2Faza-pg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxo-kt%2Faza-pg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxo-kt%2Faza-pg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluxo-kt","download_url":"https://codeload.github.com/fluxo-kt/aza-pg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxo-kt%2Faza-pg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33153665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T09:28:26.183Z","status":"ssl_error","status_checked_at":"2026-05-17T09:27:52.702Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pgflow","pgmq","postgres","postgressql","timescaledb"],"created_at":"2025-12-24T19:11:56.188Z","updated_at":"2026-05-17T20:08:02.708Z","avatar_url":"https://github.com/fluxo-kt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aza-pg\n\nPostgreSQL 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.\n\n\u003e **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.\n\n**Features:** Auto-config (RAM/CPU detection), SHA-pinned (reproducibility), PgBouncer pooling, replication, SCRAM-SHA-256, monitoring\n\n## Requirements\n\n- Docker Engine 24+ with Docker Compose v2\n- GNU/Linux or macOS host (Windows via WSL2)\n- `bun` for regenerating configs (`curl -fsSL https://bun.sh/install | bash`)\n\n**Limitations:**\n\n- PostgreSQL 18 only (no multi-version support)\n- Docker Compose only (no Kubernetes)\n- Auto-config requires cgroup v2 or `POSTGRES_MEMORY` env var\n- Connection limits: 60 (≤2GB), 84 (2-4GB), 102 (4-8GB), 120 (≥8GB) with `mixed` workload default\n- PgBouncer transaction mode: No prepared statements, advisory locks, or LISTEN/NOTIFY\n\n## Extensions\n\nComprehensive 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.\n\nComplete list: `docker run --rm \u003cimage\u003e cat /etc/postgresql/version-info.txt`\n\n### Popular Use Cases\n\n**AI/ML \u0026 Vector Search**\n\n```sql\nCREATE EXTENSION vector;           -- pgvector: Embeddings \u0026 similarity search\nCREATE EXTENSION vectorscale;      -- pgvectorscale: DiskANN indexing\n```\n\n**Time-Series Analytics**\n\n```sql\nCREATE EXTENSION timescaledb;            -- Hypertables, continuous aggregates\nCREATE EXTENSION timescaledb_toolkit;    -- Analytical hyperfunctions\n```\n\n**Full-Text Search**\n\n```sql\nCREATE EXTENSION pgroonga;         -- Multi-language full-text search\nCREATE EXTENSION rum;              -- Fast phrase search\nCREATE EXTENSION pg_trgm;          -- Trigram similarity (builtin)\n```\n\n**Security \u0026 Compliance**\n\n```sql\nCREATE EXTENSION pgaudit;          -- Audit logging (preloaded)\nCREATE EXTENSION pgsodium;         -- Encryption functions\nCREATE EXTENSION supabase_vault;   -- Supabase Vault secrets management\n```\n\n**Operations \u0026 Automation**\n\n```sql\nCREATE EXTENSION pg_cron;          -- Job scheduler (preloaded)\nCREATE EXTENSION pg_repack;        -- Online table reorganization\nCREATE EXTENSION pg_partman;       -- Partition management\n```\n\nSee [docs/EXTENSIONS.md](docs/EXTENSIONS.md) for complete catalog.\n\n## Image Details\n\n~250MB compressed / ~900MB uncompressed (amd64 + arm64). Multi-stage build with parallel compilation. Runtime: ca-certificates, zstd, lz4.\n\n## Quick Start\n\n**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.\n\n### Setup\n\n```bash\ndocker network create monitoring\nbun run build  # 2min with remote cache\ndocker run --rm aza-pg:pg18 psql --version\n```\n\n### Deploy\n\n```bash\ncd stacks/primary\ncp .env.example .env\n# Edit .env: Set POSTGRES_PASSWORD, PGBOUNCER_AUTH_PASS, PG_REPLICATION_PASSWORD\ndocker compose up -d\n```\n\n**Ports:** Postgres 5432, PgBouncer 6432, Exporters 9187/9127\n**Variants:** `stacks/single` (no PgBouncer), add `-f compose.dev.yml` for dev\n\n## Stacks\n\n| Stack   | Use Case    | Postgres | PgBouncer | Exporter(s) |\n| ------- | ----------- | -------- | --------- | ----------- |\n| Primary | Production  | 5432     | 6432      | 9187, 9127  |\n| Single  | Dev/testing | 5432     | -         | 9189        |\n| Replica | Replication | 5433     | -         | 9188        |\n\nConfigs in `stacks/{primary,replica,single}`.\n\n## Configuration\n\n### Auto-Config\n\nDetects RAM (cgroup v2 → `POSTGRES_MEMORY` → /proc/meminfo) and CPU at startup:\n\n| RAM  | shared_buffers | effective_cache_size | work_mem | max_connections\\* |\n| ---- | -------------- | -------------------- | -------- | ----------------- |\n| 512M | 128M (25%)     | 384M (75%)           | 1M       | 60                |\n| 2G   | 512M (25%)     | 1536M (75%)          | 4M       | 84                |\n| 4G   | 1G (25%)       | 3G (75%)             | 5M       | 102               |\n| 64G  | 9830M (25%)    | 49152M (75%)         | 32M      | 120               |\n\n\\*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 \u003c2GB/2-4GB/4-8GB/≥8GB.\n\nCaps: `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`).\n\n**PgBouncer:** Set `PGBOUNCER_AUTH_PASS` in .env. Escape `:` and `\\` only.\n\n### Extension Customization\n\nEdit `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).\n\n## Monitoring\n\npostgres_exporter (replication lag, memory, uptime). Prometheus config:\n\n```yaml\nscrape_configs:\n  - job_name: \"postgres\"\n    static_configs:\n      - targets: [\"localhost:9187\", \"localhost:9188\"]\n  - job_name: \"pgbouncer\"\n    static_configs:\n      - targets: [\"localhost:9127\"]\n```\n\n## Build \u0026 Test\n\n```bash\nbun run build                # 2min with remote cache\nbun run test:all                                    # Full suite\nbun run validate                                    # Validation only (fast)\nbun scripts/docker/validate-published-image-artifacts.ts  # Validate published image\n```\n\n**Regression Testing:**\n\n```bash\n# Run all regression tests (production mode)\nbun test:regression:all\n\n# Run specific tier\nbun test:regression:core        # Tier 1: PostgreSQL core (30 tests)\nbun test:regression:extensions  # Tier 2: Extension tests (13 extensions)\nbun test:regression:interactions # Tier 3: Interaction tests (14 scenarios)\n\n# Run in regression mode (all extensions including disabled ones)\nTEST_MODE=regression bun test:regression:all\n\n# Build regression image (includes pgTAP + all extensions)\nbun scripts/build.ts --regression\n```\n\n**Test Tiers:**\n\n- **Tier 1**: Core PostgreSQL regression (30 official tests, ~3-5 min)\n- **Tier 2**: Extension-specific regression (13 extensions, ~5-8 min)\n- **Tier 3**: Extension interactions (14 scenarios, ~2-4 min)\n- **Tier 4**: pgTAP unit tests (82 SQL tests, ~5-10 min)\n\nSee [docs/REGRESSION-TESTING.md](docs/REGRESSION-TESTING.md) for comprehensive regression testing documentation.\n\n**Release Validation:** [RELEASE-VALIDATION.md](RELEASE-VALIDATION.md) contains comprehensive validation results for the latest published release image (updated with each release).\n\nSee [docs/BUILD.md](docs/BUILD.md) and [docs/TESTING.md](docs/TESTING.md).\n\n## Operations\n\n**Database Management:**\n\n```bash\n# Backup database\nbun scripts/tools/backup-postgres.ts mydb backup.sql.gz\n\n# Restore from backup\nbun scripts/tools/restore-postgres.ts mydb backup.sql.gz\n\n# Promote replica to primary (failover)\nbun scripts/tools/promote-replica.ts replica-container\n\n# Generate SSL certificates (development)\nbun scripts/tools/generate-ssl-certs.ts\n```\n\n⚠️ **CRITICAL:** Replica promotion is a one-way operation. See [docs/OPERATIONS.md](docs/OPERATIONS.md) for safety warnings, detailed usage, troubleshooting, and best practices.\n\n## Troubleshooting\n\n| Issue                | Solution                                           |\n| -------------------- | -------------------------------------------------- |\n| COPY path errors     | Build from repo root: `docker build -f docker/...` |\n| Connection fails     | Check `POSTGRES_BIND_IP` (default: 127.0.0.1)      |\n| PgBouncer auth fails | Verify `PGBOUNCER_AUTH_PASS` in .env               |\n| Extension fails      | Check logs for preload errors                      |\n| High memory usage    | Set `POSTGRES_MEMORY=\u003cMB\u003e`                         |\n| Slow queries         | Review `pg_stat_statements`, `auto_explain` logs   |\n| Slow compilation     | Use `bun run build` (remote cache)                 |\n\n## Security\n\n**Defaults:** SHA-pinned base + extensions, SCRAM-SHA-256 auth, 127.0.0.1 binding, TLS disabled.\n\n**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.\n\nSee [docs/PRODUCTION.md](docs/PRODUCTION.md).\n\n## Coolify Deployment\n\naza-pg works with [Coolify](https://coolify.io) with one critical configuration change.\n\n### Quick Setup\n\n1. Create PostgreSQL resource with image: `ghcr.io/fluxo-kt/aza-pg:18`\n2. **Change volume mount** from `/var/lib/postgresql/data` to `/var/lib/postgresql`\n3. Set `POSTGRES_PASSWORD` environment variable\n4. (Optional) Set `POSTGRES_BIND_IP=0.0.0.0` for network access\n5. (Optional) Set `POSTGRES_MEMORY` to match Coolify's memory limit\n\nSee [docs/COOLIFY.md](docs/COOLIFY.md) for complete setup guide, SSL configuration, and troubleshooting.\n\n### Why the Different Mount Path?\n\nPostgreSQL 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.\n\n## FAQ\n\n**Kubernetes support?** No. Use cloud-native operators.\n\n**Why PgBouncer transaction mode?** Maximizes connection multiplexing. Use :5432 for prepared statements/advisory locks.\n\n**Override auto-config?** Set `POSTGRES_MEMORY=\u003cMB\u003e` or modify entrypoint.\n\n**Docker Desktop?** Yes, auto-detects limits.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND. NO SUPPORT, NO GUARANTEES, NO LIABILITY. Use entirely at your own risk.\n\n## Contributing\n\nFork → change → `bun run generate` (if manifest changed) → `bun run test:all` → PR\n\n**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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluxo-kt%2Faza-pg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluxo-kt%2Faza-pg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluxo-kt%2Faza-pg/lists"}