Database Design
Ownership, query boundaries, transaction scope, and the migrations a generator gets wrong.
Overview
This document covers who owns schema and migrations when part of the system is shared code, where queries are allowed to live, how transaction scope is decided, and the specific failure modes of generated migrations. Evolution and rollback are covered in Release Process; this is about the shape underneath.
Why This Exists
Two mistakes account for most of the pain, and neither is about modelling. The first is letting a shared library own tables. It looks like generosity and it removes the product's ability to add a column, index a query or scope by tenant, which are exactly the things products need to do. The second is trusting a schema diff. A migration generator emits what it inferred from a type declaration, which is not always what you meant, and in at least one recurring case is silently *less* than what you meant.
The product owns schema, migrations and tenancy
Queries live in one layer
One business operation is one transaction
What a schema generator will not tell you
Conventions worth being boring about
Related Principles· 2
Related Documents· 5
Referenced By· 7
Version History
- v0.1.0
Initial structure and metadata established.
- v0.2.0
Written from real experience. Establishes product ownership of schema and tenancy, the single query layer with the honest limit of a scoping helper, transaction scope as the business operation, the specific failure modes of generated migrations, and the conventions worth settling early.