adr.zone

ADR Example: PostgreSQL database default for new services (Nygard ADR format)

This is an example Architecture Decision Record (ADR) for standardizing on PostgreSQL as the primary relational database for new stateful work. The sections below (context, decision, consequences) show how a real team records tradeoffs, exceptions, and follow-up. Switch the format to compare the same decision as Nygard, MADR, Y-Statement, or an ISO-42010–inspired record.

When this type of decision shows up

  • You are picking a default relational engine for new services when more than one option exists in the org.
  • You need one obvious golden path in templates while keeping a documented path to opt out (legacy, certification, team constraint).
  • You are balancing SRE toil, onboarding clarity, and honest carve-outs for existing clusters.

Format

Preview

ADR-0014: Default to PostgreSQL for new stateful services

Status

Accepted

Context

We run MySQL 8 and PostgreSQL 15 on our internal Kubernetes platform. New teams keep asking which database to use; SRE maintains double runbooks, backups, and incident playbooks for the same job: a durable relational store with strong consistency within a service.

MySQL remains correct for legacy and vendor-locked services. Nothing here forces a migration if there is no owner.

PostgreSQL is already in production for analytics and billing. The gap is social: new work still “defaults to what the last repo used,” so defaults stay split.

Decision

For new stateful services after 2026-05-01, standardize on PostgreSQL 15+ as the default. Provisioning, CI, and sample repos target PostgreSQL first.

Teams may opt out with a short ADR naming the alternative and a concrete constraint. Opt-out is not the default in templates.

Existing MySQL stays until its owner proposes a migration with cutover and replay testing. This ADR does not require a fleet-wide move.

Consequences

Positive: one primary engine for greenfield work shrinks on-call load; backups and lag triage converge. New hires see one obvious default.

Negative: MySQL-heavy teams may hit migration friction for cross-DB patterns already discouraged at boundaries; this makes that visible.

Operational: SRE can retire one golden-path starter after six months if adoption holds; MySQL remains a second path.

Follow-up: publish a supported extension matrix (e.g. pgvector, pg_cron) and a single managed minor-version policy.