adr.zone

ADR Example: PostgreSQL database default for new services (ISO 42010–inspired 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

Default to PostgreSQL for new stateful services

Architecture description record (ISO/IEC/IEEE 42010–inspired). Lightweight, Git-friendly fields. Not a full conformance report to the standard—use the vocabulary of stakeholders, concerns, and views to align the decision with the architecture description.

Record ID (cross-ref): ADR-42010-0014

System / subject scope

All new stateful services provisioned on the internal Kubernetes platform and adjacent CI templates.

Stakeholders and roles

Product engineering teams, SRE, data platform, service owners of shared clusters.

Stakeholder concerns (to be addressed in the architecture description)

Operational consistency, onboarding clarity, safe coexistence of MySQL and PostgreSQL during transition, avoid forced migrations without owners.

View and viewpoint (what is shown, and from which perspective)

Viewpoint: platform / data storage. View: default engine in provisioning templates, golden-path sample services, and backup playbooks for new work.

Decision

Default new stateful work to PostgreSQL 15+ after the cutover date. Opt-out requires a documented ADR. Existing MySQL remains valid until a team-owned migration plan exists.

Rationale (with respect to the concerns and alternatives)

The architecture description for “how we run data” should be inspectable: one default path for new services reduces entropy; exceptions stay explicit and reviewable. MySQL is retained as a first-class non-default when constraints demand it.

Architectural impact (elements, relationships, and operational follow-through)

Templates, CI scaffolds, and internal docs change default connection strings and examples. SRE can narrow golden-path focus and measure adoption before retiring duplicate starters.

Traceability (requirements, policy, SLOs, other ADRs)

Platform roadmap item PG-DEFAULT-2026; ties to SRE runbook index v4.