Case Studies Best Practices

Annotate Postgres version and cloud provider; replay on new majors. Use this list when authoring or consuming internal Postgres case studies.

How to Use This List

Treat case studies as replayable runbooks, not marketing stories.
Update or archive when major Postgres or extension versions obsolete the details.
Redact customer names; keep numbers and topology honest.
Link each study to ADRs and migration tickets where possible.

A - Metadata

Postgres major.minor version pinned. Example: PostgreSQL 18.4, not "latest."
Cloud provider and topology noted. RDS, Cloud SQL, self-managed, K8s operator.
Extension versions listed. pgvector, PostGIS, pgaudit with semver.
Data scale included. Row counts, PGDATA size, QPS order of magnitude.
Date or quarter of event. Readers know currency of lessons.

B - Before/After Rigor

Metrics table before and after. Latency, cost, lag, incident count.
EXPLAIN snippets or plan summary. Not only "added index."
Decision alternatives documented. Why pg_upgrade vs logical replication.
Failed paths mentioned. What was tried and rejected builds trust.

C - Safety and Compliance

No production credentials or hostnames. Use primary.internal patterns.
PII redacted in sample SQL. Synthetic UUIDs and emails.
Regulated data called out. PCI, HIPAA boundaries in architecture diagram.

D - Maintenance

Replay on new major within 12 months of release. Validate steps still apply.
Owner assigned per case study file in git. Not orphaned wiki page.
Related links point to current section slugs. Fix broken links in same PR as edits.
Lessons distilled to actionable policy. Council rule or lint, not vibes.

FAQs

How long should a case study be?

2-4 screens: context, decision, metrics, lessons. Longer appendices in linked runbooks.

Real customer vs composite?

Composite is fine if labeled; never fabricate metrics.

Should we include dollar amounts?

Yes when finance approved sharing; ranges OK if exact is sensitive.

Who approves publication?

Tech lead + legal for customer mentions; security for architecture exposure.

How to version case studies?

Git history is source of truth; add "Last reviewed" date in intro paragraph.

Include failed upgrades?

Especially valuable; mark severity and rollback outcome clearly.

Diagrams required?

ASCII or linked diagram for topology; helps replay on new provider.

Translate to es later?

English canonical path; translate-es mirrors same slug one-to-one.

Link to video recordings?

Optional; transcript summary still required for search and lint.

What should I read next?

Browse reference architectures in this section for templates.

Reference: Multi-Tenant SaaS - SaaS template
Before/After: Major Version Upgrade - upgrade narrative
Before/After: Query Optimization Win - performance narrative
Governance Basics - doc standards

Stack versions: This page was written for PostgreSQL 18.4 (stable 18, maintenance 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, and PostGIS 3.5+.

Case Studies Best Practices

Annotate Postgres version and cloud provider; replay on new majors. Use this list when authoring or consuming internal Postgres case studies.

How to Use This List

Treat case studies as replayable runbooks, not marketing stories.
Update or archive when major Postgres or extension versions obsolete the details.
Redact customer names; keep numbers and topology honest.
Link each study to ADRs and migration tickets where possible.

A - Metadata

Postgres major.minor version pinned. Example: PostgreSQL 18.4, not "latest."
Cloud provider and topology noted. RDS, Cloud SQL, self-managed, K8s operator.
Extension versions listed. pgvector, PostGIS, pgaudit with semver.
Data scale included. Row counts, PGDATA size, QPS order of magnitude.
Date or quarter of event. Readers know currency of lessons.

B - Before/After Rigor

Metrics table before and after. Latency, cost, lag, incident count.
EXPLAIN snippets or plan summary. Not only "added index."
Decision alternatives documented. Why pg_upgrade vs logical replication.
Failed paths mentioned. What was tried and rejected builds trust.

C - Safety and Compliance

No production credentials or hostnames. Use primary.internal patterns.
PII redacted in sample SQL. Synthetic UUIDs and emails.
Regulated data called out. PCI, HIPAA boundaries in architecture diagram.

D - Maintenance

Replay on new major within 12 months of release. Validate steps still apply.
Owner assigned per case study file in git. Not orphaned wiki page.
Related links point to current section slugs. Fix broken links in same PR as edits.
Lessons distilled to actionable policy. Council rule or lint, not vibes.

FAQs

How long should a case study be?

2-4 screens: context, decision, metrics, lessons. Longer appendices in linked runbooks.

Real customer vs composite?

Composite is fine if labeled; never fabricate metrics.

Should we include dollar amounts?

Yes when finance approved sharing; ranges OK if exact is sensitive.

Who approves publication?

Tech lead + legal for customer mentions; security for architecture exposure.

How to version case studies?

Git history is source of truth; add "Last reviewed" date in intro paragraph.

Include failed upgrades?

Especially valuable; mark severity and rollback outcome clearly.

Diagrams required?

ASCII or linked diagram for topology; helps replay on new provider.

Translate to es later?

English canonical path; translate-es mirrors same slug one-to-one.

Link to video recordings?

Optional; transcript summary still required for search and lint.

What should I read next?

Browse reference architectures in this section for templates.

Reference: Multi-Tenant SaaS - SaaS template
Before/After: Major Version Upgrade - upgrade narrative
Before/After: Query Optimization Win - performance narrative
Governance Basics - doc standards

Stack versions: This page was written for PostgreSQL 18.4 (stable 18, maintenance 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, and PostGIS 3.5+.

Case Studies Best Practices

Search Documentation

Case Studies Best Practices