database-migration

Safe database migrations use additive-only, idempotent ALTER TABLE statements. Add nullable columns first, check for column existence to ensure idempotency, wrap changes in transactions, and test both fresh installs and migration paths from previous versions to prevent data loss and app crashes.

Foreign key constraint failures occur when migrations create or modify relationships without respecting existing data or transaction boundaries. Use transactional migrations, validate foreign key references exist before constraints are applied, and test migrations against real production data scenarios.

No. Once released, migrations must remain immutable. Create new additive migrations instead. Modifying shipped migrations breaks consistency across installed versions and causes unpredictable migration failures. Always add new migration files for subsequent schema changes.

These errors indicate unsafe schema changes. Add columns as nullable first, then backfill data in separate migrations if needed. Use idempotent checks (ALTER TABLE IF NOT EXISTS patterns) and test against both fresh databases and upgraded instances to catch these errors early.

SQLite requires raw ALTER TABLE statements; GRDB wraps these in type-safe Swift patterns; SwiftData uses declarative schema versioning. All three require additive, transactional, idempotent changes and comprehensive testing to prevent data loss, but implementation syntax and migration execution differ.

Fresh installs apply all migrations sequentially, while upgrades apply only new migrations to existing schemas. Testing both paths ensures migrations work idempotently, handle existing data correctly, and don't introduce version-specific state corruption that only appears during real user upgrades.