Data And Migration Rules
Definition
Define how persistent data changes safely while preserving information hiding. Schemas are interfaces: they create dependencies for code, reports, migrations, and operations.
Process
- Assign each table, collection, or model to an owner module.
- Put invariants in the strongest practical place: domain rule, database constraint, or transaction.
- Keep raw persistence shapes behind repositories or data access modules.
- Write migrations as ordered, reviewable, reversible where practical, and safe for existing data.
- Separate expand and contract steps for risky production changes.
- Verify migrations with tests, local migration runs, and rollback notes when relevant.
Rules
- Do not let UI or route code depend directly on database schema details.
- Do not duplicate validation that belongs in a schema constraint or owner module.
- Treat nullability, defaults, indexes, uniqueness, and foreign keys as design decisions.
- Avoid data migrations that require hidden manual steps.
- Keep transactions inside the module that understands the invariant.
Examples
- Good: add nullable column, backfill, deploy reads, deploy writes, then make non-null.
- Bad: rename a column and update all callers in one risky deploy.
- Good:
appointments owns appointment_slots and exposes repository methods.
- Bad: analytics code mutates production domain tables directly.
Vocabulary
- Schema interface: database structure other code depends on.
- Constraint: a rule enforced by the database or domain.
- Migration: an ordered change to persistent structure or data.
- Expand-contract: safe multi-step migration from old shape to new shape.
- Transaction boundary: the smallest unit that must succeed or fail together.
- Data leakage: persistence detail exposed where it does not belong.
Expected Outcome
Produce data rules covering schema ownership, access boundaries, constraints, migration order, transaction policy, backfill safety, and verification steps.
1---2name: data-and-migration-rules3description: Define or audit schema ownership, constraints, transactions, data access boundaries, and safe migration practices. Use when adding tables, changing fields, writing migrations, or preventing persistence details from leaking through the system.4---56# Data And Migration Rules78## Definition910Define how persistent data changes safely while preserving information hiding. Schemas are interfaces: they create dependencies for code, reports, migrations, and operations.1112## Process13141. Assign each table, collection, or model to an owner module.152. Put invariants in the strongest practical place: domain rule, database constraint, or transaction.163. Keep raw persistence shapes behind repositories or data access modules.174. Write migrations as ordered, reviewable, reversible where practical, and safe for existing data.185. Separate expand and contract steps for risky production changes.196. Verify migrations with tests, local migration runs, and rollback notes when relevant.2021## Rules2223- Do not let UI or route code depend directly on database schema details.24- Do not duplicate validation that belongs in a schema constraint or owner module.25- Treat nullability, defaults, indexes, uniqueness, and foreign keys as design decisions.26- Avoid data migrations that require hidden manual steps.27- Keep transactions inside the module that understands the invariant.2829## Examples3031- Good: add nullable column, backfill, deploy reads, deploy writes, then make non-null.32- Bad: rename a column and update all callers in one risky deploy.33- Good: `appointments` owns `appointment_slots` and exposes repository methods.34- Bad: analytics code mutates production domain tables directly.3536## Vocabulary3738- Schema interface: database structure other code depends on.39- Constraint: a rule enforced by the database or domain.40- Migration: an ordered change to persistent structure or data.41- Expand-contract: safe multi-step migration from old shape to new shape.42- Transaction boundary: the smallest unit that must succeed or fail together.43- Data leakage: persistence detail exposed where it does not belong.4445## Expected Outcome4647Produce data rules covering schema ownership, access boundaries, constraints, migration order, transaction policy, backfill safety, and verification steps.
harsh817