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 leaves infrastructure undocumented and hopes for the best. It’s a shared concern - it spans services, it has its own change cadence, it deserves deliberate review before anything is applied. So it gets version-controlled and reviewed. When a service needs more infrastructure or a configuration change, the engineer opens a PR. The team reviews it. It gets merged. It gets applied.

This isn’t bureaucracy. It’s separation of concerns applied to the engineering stack.

Your database schema deserves the same treatment. The only thing that ever stopped it was tooling that wouldn’t bend to the way your repos are already laid out.

Workspaces you import from anywhere

Schemity stores every connection as plain JSON files - ERD tool JSON storage at its simplest, no proprietary format, no binary blob, no cloud dependency. A workspace is just a folder of those files.

Older versions kept everything under ~/schemity/. That’s still the default home, but it’s no longer a constraint: Schemity can import any folder, anywhere on your machine, as a workspace. That one capability is what makes the tool fit how software engineers actually organize their work, instead of forcing a single layout on every team.

Because the folder can live anywhere, you get to choose the model that matches how your team thinks about schema ownership. Two patterns cover almost everyone.

Option 1: the ERD lives inside each service repo

Point Schemity at a folder that already lives inside your project repo - say docs/erd - and import it as a workspace. Now the diagram is versioned right alongside the code it describes.

payment-service/              # your existing service repository
  src/
  migrations/
  docs/
    erd/                      # import this folder as a Schemity workspace
      meta.json
      production.json

The schema change ships in the same pull request as the migration that caused it. Reviewers see the code change and the diagram change side by side. The ERD travels with every clone of the repo automatically - no second remote to keep in sync, no ~/schemity-bound copy that drifts.

This is what makes Schemity a genuinely Git-native ERD tool: the diagram is not exported to Git, it lives in Git, inside the repo it documents.

Option 2: one central ERD repo for the whole org

Some teams want every service’s schema in a single place - the same instinct that puts shared infrastructure in its own repo. That still works, and now it’s a deliberate choice rather than the only option:

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

Each folder is a workspace carrying the full ERD for that service. Clone the repo wherever you like - it no longer has to be ~/schemity/ - import it, and Schemity opens it as a central hub: pick a workspace, start working.

The point is that the layout is now yours to decide. Per-repo for teams that want schema review baked into feature PRs. Central repo for architects who want one clone to see every data boundary. Mix the two if that’s what your org actually looks like. Consultants take the same idea further with one workspace per client.

What this unlocks

For the engineer making the change: 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 - to the service repo or the ERD repo, wherever that workspace lives - and open the PR.

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: Keep a central ERD repo and every service’s schema is one clone away. 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 one workspace hub and it’s all there.

For the new engineer onboarding: If the ERD lives inside each service repo, the diagram is already on disk after a normal git clone - import the folder once and open it read-only, no database or credentials needed. If your team runs a central repo, one clone gives them every service at once:

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

Either way: 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 where the folder sits - 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, 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 separation of concerns applied to the full engineering stack. Source code in service repos. Infrastructure version-controlled and reviewed. Schema right where your team wants it - because Schemity imports from anywhere instead of dictating one location. Your ERD becomes the single source of truth for every database, version controlled in Git where it belongs.