adr.zone

ADR Example: PostgreSQL database default for new services (Outcome-First 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, Outcome-First, or ISO 42010 Companion.

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

Outcome

One obvious default relational store for greenfield work, reducing split runbooks and onboarding confusion.

Decision

Adopt PostgreSQL 15+ as the default for new stateful services after 2026-05-01. Teams may opt out with a short ADR naming the alternative and a concrete constraint.

Primary tradeoff

We accept dual-engine operations during a long tail until MySQL services migrate or retire under their own ADRs.

Why

  • PostgreSQL is already in production for billing and analytics
  • SRE can converge backup and HA playbooks on fewer engines
  • New hires see one obvious default in templates and sample repos

Decision boundaries

Impacted:

  • Provisioning templates and CI scaffolds
  • Default connection strings in sample repos
  • SRE backup and HA playbook scope

Not impacted:

  • Existing MySQL services (no forced migration)
  • Vendor-certified workloads locked to MySQL
  • Non-relational stores (Redis, S3, etc.)

Assumptions:

  • Internal cloud supports PostgreSQL 15+ with managed HA
  • Opt-out path remains first-class, not a hack

Guardrails:

  • Opt-out requires a documented ADR with named constraint
  • SRE reviews new provisioning within 48 h
  • Extension matrix published before first production deploy