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.internalpatterns. - 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.
Related
- 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+.