If you’ve worked on a team with more than two services, you’ve felt this pain.

A feature needs a new table. You write the migration, apply it, ship the code. The ERD - if one ever existed - is now wrong. It lives in a Notion page somebody created two years ago, or a Lucidchart diagram the original architect exported before leaving, or nowhere at all. The next engineer who needs to understand the schema opens the database directly and reads it cold.

This is the normal state of database documentation in most engineering teams. Not because engineers don’t care - but because the tooling never made it easy enough to care.

The pattern you already know

Mature engineering teams long ago solved a similar problem with infrastructure.

Nobody commits Terraform configuration inside their application service repo. Infrastructure is a shared concern - it spans services, it has its own change cadence, it deserves deliberate review before anything is applied. So it lives in its own repo. When a service needs more infrastructure or a configuration change, the engineer opens a PR against the infra repo. The team reviews it. It gets merged. It gets applied.

This separation isn’t bureaucracy. It’s separation of concerns at the repository level.

Your database schema deserves the same treatment.

The ERD repo

The pattern is simple:

company-erd-repo/
  ├── payment-service/
  ├── user-service/
  ├── notification-service/
  ├── legacy-crm/
  └── ...

Each folder is a Schemity workspace containing plain JSON files that carry the full ERD for that service. The entire repo lives as ~/schemity/ on every engineer’s machine. Schemity opens it as a central hub: pick a workspace, start working.

The workflow mirrors what your team already does with Terraform:

  • Source code change that needs new infrastructure? Open a PR against the infra repo.
  • Source code change that needs a database migration? Open a PR against the ERD repo.

The schema change gets its own PR, its own review, its own merge. Not buried inside a feature PR where three changed tables hide behind fifty lines of application code. Not applied directly to the database and documented later - or never.

What this unlocks

For the engineer making the change: Clone company-erd-repo once into ~/schemity/. Your schema changes still flow through your team’s normal migration workflow - Django, Rails, Flyway, Atlas, whatever your stack uses. Once the migration is applied to your local database, open Schemity, connect to it, and let it reflect the current state. Arrange the entities, update the relationships, add or update legends to give the diagram business meaning. Then commit the updated JSON and open the PR against the ERD repo.

For the engineer reviewing the change: Pull the branch. Open Schemity. The diff is right there - a JSON file change that maps directly to a visual diagram. No migration file archaeology. No mental reconstruction of what the schema looked like before.

For the architect or tech lead reviewing multiple services: One repo. One clone. Every service’s schema in one place. When you need to understand data boundaries across the payment service, the user service, and the notification service - you don’t hop between three repos hoping someone committed a diagram. You open company-erd-repo and it’s all there.

For the new engineer onboarding:

git clone [email protected]:company/erd-repo.git ~/schemity

One command. Every service. Every relationship. Every constraint. The full picture of the company’s data model, version-controlled and up to date.

Schema as a first-class engineering artifact

The deeper shift here isn’t about tooling - it’s about treating the schema as something that deserves the same discipline as infrastructure and source code.

When a schema change requires a PR against the ERD repo, a few things happen naturally:

  • Schema changes get reviewed before they’re applied, not after
  • The ERD stays in sync with reality because updating it is part of the workflow, not an afterthought
  • Legacy services that have no active development still have a maintained, readable schema
  • The history of every schema decision lives in Git - who changed it, when, and why

This is the spirit of separation of concerns applied to the full engineering stack. Source code in service repos. Infrastructure in the infra repo. Schema in the ERD repo.