Next.js + PostgreSQL + Containerized App

Overview

Build and maintain production-grade Next.js applications backed by PostgreSQL, shipped as Docker images (and optionally via Docker Compose).

Priorities:

• Correctness for money/decimal math (no floats)
• Safe DB access (pooling, migrations, transactions)
• Reproducible container builds (multi-stage, minimal runtime image)

Version targets (verified 2026-01-16)

• Next.js: 16.1.x (latest stable observed: 16.1.2)
• PostgreSQL: 18.x (current minor observed: 18.1)

Guidance:

• Prefer staying on the latest minor for your chosen Postgres major.
• Treat Next.js security advisories as “upgrade now” events.

Workflow Decision Tree

1. Data access approach

   • Drizzle (preferred): SQL-first, TypeScript-friendly, good migration story.
   • Prisma: alternative when you want an ORM-first workflow and Prisma’s schema/migrations.
   • Kysely / Knex: alternatives when you want a query-builder-first approach.

2. Deployment shape

   • Single container (Next.js + external managed Postgres): typical production.
   • Compose stack (Next.js + Postgres): local dev / integration tests / simple hosting.
   • Kubernetes: production clusters with Ingress, autoscaling, and secret management.

3. Money representation (required: Postgres NUMERIC + Dinero.js)

   • Recommended: store minor units as NUMERIC(20,0) (integer semantics, no rounding).
   • If you must store decimals (e.g., NUMERIC(20,2)), treat values as strings in JS and convert explicitly (see references).

If you need detailed money/numeric rules and conversion patterns, read references/money-and-numeric.md.

If you need Kubernetes deployment patterns (Ingress, probes, HPA, migrations), read references/kubernetes.md.

Standard Build Workflow

1) Database schema (Postgres)

• Use NUMERIC for money/decimals.
• Prefer explicit constraints:
  • CHECK (amount_minor >= 0) if negatives aren’t allowed
  • currency_code CHAR(3) with ISO-4217 validation (or reference table)
• Index common query patterns (user_id + created_at, status, etc.).

2) Next.js (App Router) structure

• Keep side effects (DB writes, payments) in server actions or route handlers.
• Validate inputs at the boundary (zod/valibot) before hitting the DB.
• Never trust client values for money amounts; recompute on server.

3) DB connection management

• Prefer a pooled connection string (or pooler like PgBouncer in transaction pooling mode, depending on your ORM).
• In dev with hot reload, ensure you don’t create a new pool per reload.
• Keep transactions short; avoid holding locks across network calls.

4) Migrations

• Migrations must run before the app serves traffic.
• For container deploys:
  • Option A: run migrations as a one-off job/container.
  • Option B: app container runs migrations on startup (acceptable for small deployments; ensure idempotency and lock).

5) Containerization (Docker)

Best practices:

• Multi-stage build: deps → build → runtime.
• Non-root runtime user.
• Use Next.js standalone output when possible.
• Keep secrets out of images; pass via env/secret manager.

6) Local dev with Compose

• Use a Postgres service with a named volume.
• Provide healthchecks and wait-for-DB behavior.
• Keep a separate DATABASE_URL for local dev.

7) Kubernetes (K8s) deployment

Keep K8s guidance simple and production-oriented:

• Prefer managed Postgres (RDS/Cloud SQL/Azure) vs running Postgres inside the cluster.
• Use one-off migration jobs (or a controlled init step) instead of running migrations on every pod start.
• Wire health probes correctly (readiness gates traffic; liveness restarts unhealthy pods).
• Handle secrets via Kubernetes Secrets or an external secret manager (don’t commit .env).
• Plan scaling: Next.js pods scale horizontally, but DB connections must be pooled and bounded.

For concrete manifest patterns and checklists, read references/kubernetes.md.

Money Handling (Dinero.js / “deniro.js”) Rules

Hard rules:

• Never use JS number for money arithmetic.
• Treat DB NUMERIC as string (or a Decimal type) at the JS boundary.
• Prefer storing minor units in DB:
  • Example column: amount_minor NUMERIC(20,0) NOT NULL
  • Example usage: Dinero amount = BigInt(amount_minor)

Operational rules:

• Always store currency explicitly.
• Round only at well-defined boundaries (pricing, invoicing), not “whenever.”

Pitfalls Checklist (Fast)

• Rounding drift: happens if you convert NUMERIC(20,2) → float → back.
• Timezone bugs: store timestamps as timestamptz, always.
• Connection storms: serverless + naive pooling can exhaust Postgres.
• Leaky secrets: never bake .env into the Docker image.

References (Load On Demand)

• references/money-and-numeric.md: Postgres NUMERIC column choices + JS mapping + Dinero conversion recipes.
• references/kubernetes.md: K8s deployment patterns for Next.js + Postgres (Ingress, probes, autoscaling, migrations, secrets).