06 — Database: PostgreSQL Only
PostgreSQL is the only permitted database. Do not use MySQL, MongoDB, SQLite, Redis-as-a-database, DynamoDB, or any other engine. Our hosting stack is built and optimised around PostgreSQL.
Connection
Connect using environment variables only:
| Variable | Meaning |
|---|---|
DB_HOST |
PostgreSQL server hostname |
DB_PORT |
Port (usually 5432) |
DB_NAME |
Database name |
DB_USER |
Login username |
DB_PASSWORD |
Login password — never hardcoded |
Use a connection pool (e.g. pg.Pool in Node, SQLAlchemy pool in Python, HikariCP in Java) — each of your 2+ replicas opens its own connections, so keep pool sizes modest (5–10 per pod) and document your pool size in source/README.md.
Migrations — read this carefully
Migrations must run automatically, using a standard tool: Alembic (Python), Flyway (Java), Prisma / Sequelize / node-pg-migrate (Node.js).
⚠️ Concurrency warning: your app always runs as 2+ replicas, and during a rolling update old and new pods run simultaneously. If every pod blindly runs migrations on startup, two pods can run them at the same time. Protect against this in one of these ways (in order of preference):
- Use a tool with built-in locking — Flyway, Alembic (with a lock), Prisma
migrate deploy, and node-pg-migrate all take a PostgreSQL advisory lock or equivalent so concurrent runs are safe. Verify your tool does this; most do by default. - Run migrations in an initContainer or Kubernetes Job instead of in the app process (ask DevOps if you want this pattern).
- Ensure all migrations are backwards-compatible with the previous app version (old pods keep running against the migrated schema during the rollout). Avoid destructive changes (dropping/renaming columns) in the same release that deploys the code change.
Extensions
Document any required PostgreSQL extensions (e.g. pgcrypto, uuid-ossp) in source/README.md — the DevOps team will enable them. Your app should not attempt CREATE EXTENSION itself (it won't have the privileges).
Prompt tip
"Use PostgreSQL as the only database. Connect via a connection pool using env vars
DB_HOST,DB_PORT,DB_NAME,DB_USER,DB_PASSWORD. Run migrations automatically on startup with a migration tool that takes an advisory lock, and keep every migration backwards-compatible with the previous release. List any required PostgreSQL extensions insource/README.md."