Safe Database Migrations with ormDB's A-D Grading System
Learn how ormDB grades every migration from A (safe) to D (destructive), preventing accidental data loss and downtime in production deployments.
Why Migrations Need Grading
ormDB is a relational database engine written in Rust that replaces PostgreSQL, MySQL, and SQLite. One of its core safety features is automatic migration grading: every schema change is analyzed and assigned a grade from A (completely safe) to D (destructive, data loss possible) before it executes.
Traditional databases like PostgreSQL apply migrations blindly. A DROP COLUMN runs just as easily as an ADD COLUMN. The safety of a migration depends entirely on the developer writing it and the review process catching mistakes. In practice, destructive migrations slip through. Columns get dropped. Tables get deleted. Data is lost.
ormDB moves migration safety into the database engine itself.
The Grading Scale
Grade A: Safe
No risk of data loss or downtime. These migrations apply without caveats.
Migration: add_bio_to_users
Action: Add nullable column "bio" (text) to entity "User"
Grade: A
Reason: Adding a nullable column has no effect on existing data
Status: AppliedExamples: adding nullable columns, adding new entities, adding new relations with no constraints on existing data. See schema design patterns for guidance on designing entities that evolve safely.
Grade B: Safe with Caveats
No data loss, but may have operational impact on large datasets.
Migration: index_users_email
Action: Create index on "User.email"
Grade: B
Reason: Index creation on entity with >1M records may cause temporary write latency
Status: AppliedExamples: adding indexes on large entities, adding unique constraints to columns that already have unique values.
Grade C: Caution Required
No data loss if the migration succeeds, but the operation requires transformation or has locking implications.
Migration: change_age_to_integer
Action: Change column "User.age" from text to integer
Grade: C
Reason: Type conversion requires data transformation; rows with non-numeric values will fail
Status: Awaiting reviewExamples: column type changes, adding NOT NULL constraints with default values, renaming columns.
Grade D: Destructive
Data loss is possible or certain. Requires explicit confirmation.
Migration: drop_legacy_posts
Action: Drop entity "LegacyPost" (4,521 records)
Grade: D
Reason: Dropping entity permanently deletes all data; 4,521 records will be lost
Status: Blocked - requires --confirm-destructive flagExamples: dropping columns, dropping entities, removing relations that cascade deletes.
Using Migration Grading
Dry Run in CI/CD
Run migration analysis without applying changes:
ormdb migrate --dry-runOutput:
Pending migrations:
001_add_bio_to_users Grade A (safe)
002_index_users_email Grade B (safe with caveats)
003_drop_legacy_posts Grade D (destructive)
Pipeline recommendation: BLOCK - contains Grade D migrationApplying Migrations
Grade A and B migrations apply automatically:
ormdb migrate
# Applies 001_add_bio_to_users (A) and 002_index_users_email (B)
# Blocks on 003_drop_legacy_posts (D)Grade D migrations require explicit confirmation:
ormdb migrate --confirm-destructive
# Applies all pending migrations including Grade DIntegration with ORM Migration Tools
Your ORM’s migration commands route through the grading system automatically. When you run prisma migrate deploy (via the Prisma integration) or alembic upgrade head (via the SQLAlchemy integration), the ormDB adapter intercepts the operations and applies grading before execution.
Migration Grading as a Development Practice
Migration grading is not just a production safeguard. It provides immediate feedback during development, making it essential for SaaS applications and startups that iterate rapidly. When you see a Grade C or D, you can evaluate whether the change is intentional and plan accordingly, including data backups, maintenance windows, or alternative migration strategies, before the change reaches production. For more on designing schemas that evolve cleanly, see schema design patterns.
Frequently Asked Questions
What do the A-D grades mean?
Grade A: fully safe, no risk (adding a nullable column). Grade B: safe with minor caveats (adding an index on a large table). Grade C: requires caution, potential for brief locking or data transformation (changing a column type). Grade D: destructive, data loss possible (dropping a column or table).
Can I override a migration grade?
Yes. Grade D migrations require explicit acknowledgment. You must pass a confirmation flag to apply them. This prevents accidental destructive changes but does not block intentional ones.
Does grading work with my ORM's migration tool?
Yes. The ormDB adapters for Prisma, Drizzle, TypeORM, SQLAlchemy, and Django intercept migration commands and route them through ormDB's grading engine. You use your existing migration workflow.
What happens if I try to apply a Grade D migration without confirmation?
The migration is rejected with a detailed explanation of what data would be lost and which entities are affected. The database state does not change.
Are migrations transactional?
Yes. Each migration runs within an ACID transaction. If any step fails, the entire migration is rolled back and the database remains in its previous state.
Can I see the grade before applying a migration?
Yes. The ormDB CLI provides a dry-run mode that analyzes pending migrations and reports their grades without applying them. This is designed for CI/CD pipelines.