Schema Diff Checker

Compare two schemas to identify differences and plan migrations

Understanding Schema Evolution

Database schemas evolve as applications grow and requirements change. Understanding schema differences is crucial for safe migrations, API versioning, and maintaining backward compatibility.

Types of Schema Changes

Added Fields (Backward Compatible)

New fields added to the schema. These are generally safe changes:

Impact: Existing code continues to work
Considerations: New fields should have default values or be nullable
Example: Adding "email_verified" boolean to users table

Removed Fields (Breaking Change)

Fields deleted from the schema. These are breaking changes:

Impact: Code referencing removed fields will fail
Migration strategy: Deprecate first, then remove after transition period
Example: Removing "legacy_id" that old code still references

Modified Fields (Breaking Change)

Field type or constraints changed. These are breaking changes:

Impact: Data validation and serialization may fail
Migration strategy: Convert existing data or use dual-write pattern
Example: Changing "age" from INTEGER to VARCHAR

Backward Compatibility

A schema is backward compatible if old code can work with the new schema. This requires:

Safe Changes (Backward Compatible)

Adding optional fields (nullable or with defaults)
Making required fields optional
Widening field constraints (e.g., VARCHAR(50) to VARCHAR(100))
Adding new enum values to the end of the list

Breaking Changes (Not Backward Compatible)

Removing fields
Renaming fields
Changing field types
Making optional fields required
Narrowing constraints (e.g., reducing string length)

Migration Strategies

Blue-Green Deployment

Run old and new versions side-by-side, switch traffic when ready. Requires schema to be compatible with both versions during transition.

Expand-Contract Pattern

Expand: Add new fields while keeping old ones
Migrate: Update code to use new fields
Contract: Remove old fields after all code is updated

Dual-Write Pattern

Write to both old and new fields during transition. Gradually migrate reads, then stop writing to old fields.

Version Your API

Use API versioning (v1, v2) to support multiple schema versions simultaneously. Each version can have different schemas.

Best Practices

Before Making Changes

Compare schemas to understand the impact
Identify all code that depends on affected fields
Plan migration strategy for breaking changes
Test schema changes in staging environment
Document all schema changes and reasons

During Migration

Use transactions where possible
Back up data before schema changes
Monitor application errors during rollout
Have a rollback plan ready
Communicate changes to team members

After Migration

Validate data integrity
Remove deprecated fields after grace period
Update documentation
Clean up migration code

Sample Schema Format

{
  "id": "INTEGER",
  "name": "VARCHAR(100)",
  "email": "VARCHAR(255)",
  "age": "INTEGER",
  "created_at": "TIMESTAMP"
}

Common Use Cases

Database migrations
API versioning
Data warehouse changes
Microservice integration
ETL pipeline updates
System upgrades