// library

Migrations & Backward Compatibility rules

11 rules

Severity

Bucket

ActiveBucketMigrations & Backward Compatibility Clear all

Critical
Block risky database migrations (locking ops, downtime risk)
Review SQL/database migrations for operations that can lock large tables or cause downtime. Examples: creating indexes without CONCURRENTLY (Postgres), ALTER COLUMN TYPE on big tables, adding NOT NULL without backfill, long-running updates without batching. Require an online migration strategy (CONCURRENTLY, backfill in batches, dual-write/expand-contract) and a rollback plan.
migrations-backward-compatdatabase-query-performance
Critical
Deletion requests: anonymize or hard-delete PII irreversibly
On LGPD deletion, remove or irreversibly anonymize PII and purge dependent caches. Keep minimal audit metadata (timestamp, request ID) not linkable back to the subject.
compliance-lgpdmigrations-backward-compat+1
High
Add foreign key constraints in migrations
Enforce referential integrity with add_foreign_key and matching indexes.
database-query-performancemigrations-backward-compat
High
Backups encrypted, tested, and monitored for RPO/RTO
Create daily encrypted backups (KMS keys) with retention and geo-redundancy; run quarterly restore tests and record results in the audit log.
compliance-soc2-essentialsmigrations-backward-compat+1
High
Declare rollout and migration plan
Include a 'Rollout Plan' section with phases, feature flags, backout plan, and data migration steps; reference migration scripts and flag names.
docs-adrsmigrations-backward-compat
High
Enforce retention with explicit TTL per data category
PII tables must include an expires_at (or retention_policy) column and a scheduled deletion/archival job aligned to data category. No indefinite retention. (GDPR Art. 5(1)(e))
compliance-gdprprivacy-pii+2
High
Make migrations reversible with up/down methods
Prefer reversible change or explicit up/down to support rollbacks.
migrations-backward-compat
High
PII-introducing PRs require DPIA & RoPA updates
If a PR adds new PII fields (e.g., email, phone, address, dob, national_id), include links to updated DPIA and RoPA, migration with retention, and masking rules. Add a checklist item confirming lawful_basis. (GDPR Art. 35, Art. 30)
compliance-gdprpr-hygiene+2
High
Use batch operations for large data migrations
Process large tables with find_in_batches and avoid loading entire datasets.
migrations-backward-compatperformance-efficiency
Low
Extract complex migration logic to separate methods
Keep migrations readable by extracting multi-step data fixes to helper methods within the migration.
migrations-backward-compatreadability-refactor
Low
Use change_table for safer migrations
Group column/index changes with change_table; use concurrent indexes when needed.
migrations-backward-compat

11 rules

Block risky database migrations (locking ops, downtime risk)

Deletion requests: anonymize or hard-delete PII irreversibly

Add foreign key constraints in migrations

Backups encrypted, tested, and monitored for RPO/RTO

Declare rollout and migration plan

Enforce retention with explicit TTL per data category

Make migrations reversible with up/down methods

PII-introducing PRs require DPIA & RoPA updates

Use batch operations for large data migrations

Extract complex migration logic to separate methods

Use change_table for safer migrations

Block risky database migrations (locking ops, downtime risk)

Deletion requests: anonymize or hard-delete PII irreversibly

Add foreign key constraints in migrations

Backups encrypted, tested, and monitored for RPO/RTO

Declare rollout and migration plan

Enforce retention with explicit TTL per data category

Make migrations reversible with up/down methods

PII-introducing PRs require DPIA & RoPA updates

Use batch operations for large data migrations

Extract complex migration logic to separate methods

Use change_table for safer migrations