adr.zone

ADR Example: PostgreSQL database default for new services (Y-Statement 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

Y-Statement (structured decision record)

Sentence

In the context of new stateful services on the internal platform, facing split database defaults and duplicated operations, we have decided for standardizing on PostgreSQL 15+ for new services with explicit opt-out in order to one obvious default, fewer runbooks, clearer onboarding, honest exceptions in ADRs, accepting that we keep supporting MySQL for legacy; no forced big-bang migration.

Fields (same content, for reviews)

  • Context: new stateful services on the internal platform
  • Concern: split database defaults and duplicated operations
  • Stance / subject: for / standardizing on PostgreSQL 15+ for new services with explicit opt-out
  • Intended outcome: one obvious default, fewer runbooks, clearer onboarding, honest exceptions in ADRs
  • Deliberate tradeoff: we keep supporting MySQL for legacy; no forced big-bang migration