home / skills / shotaiuchi / dotclaude / migration-data

migration-data skill

safe

This skill guides safe database migrations and schema changes, ensuring data integrity and backward compatibility across formats, configurations, and records.

npx playbooks add skill shotaiuchi/dotclaude --skill migration-data

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.6 KB

---
name: migration-data
description: >-
  Data migration and schema changes. Apply when handling database schema
  migrations, data format conversions, serialization updates, configuration
  migration, and data integrity verification.
user-invocable: false
---

# Data Migration

Handle data and schema migrations safely.

## Migration Checklist

### Schema Migration
- Define forward and reverse schema migration scripts
- Verify schema changes are backward compatible where needed
- Check for data type changes that may cause truncation or loss
- Ensure index and constraint updates are included

### Data Format Conversion
- Identify all serialization format changes
- Implement data transformation for existing records
- Verify date, time, and locale format compatibility
- Check for encoding changes affecting stored data

### Configuration Migration
- Map old configuration keys to new equivalents
- Provide default values for newly required settings
- Validate migrated configuration against new schema
- Ensure environment-specific overrides are preserved

### Data Integrity
- Verify referential integrity after migration
- Run checksums or row counts to confirm completeness
- Check for orphaned records or dangling references
- Validate business logic constraints on migrated data

## Output Format

Report findings with risk ratings:

| Risk | Description |
|------|-------------|
| Critical | Data loss or corruption possible, blocks migration |
| High | Data integrity at risk, requires careful validation |
| Medium | Format change may affect downstream consumers |
| Low | Minor configuration update, low risk of issues |

Overview

This skill helps plan and execute data and schema migrations safely. It groups checks for schema changes, data format conversions, configuration migration, and integrity verification into actionable steps and risk-rated findings. Use it to reduce data loss, preserve compatibility, and validate results before cutover.

How this skill works

The skill inspects proposed schema changes and generates forward and reverse migration scripts, highlighting type changes, index updates, and compatibility concerns. It analyzes data format shifts and configuration mappings, recommending transformations and default values. After migration, it runs integrity checks such as referential verification, checksums, and row-count comparisons and produces a risk-rated report.

When to use it

Before deploying database schema updates in production
When converting stored data to a new serialization or encoding
When upgrading application configuration formats or keys
When validating migration results after a data transformation
When preparing rollbacks or reversible migration paths

Best practices

Define both forward and reverse migration scripts for every change
Test migrations on representative snapshots and staging data
Preserve environment-specific overrides and provide sensible defaults
Validate types, encodings, and locale-sensitive formats explicitly
Include integrity checks (checksums, row counts, FK validation) in automation

Example use cases

Add a new indexed column with a backfill that avoids locking production tables
Convert legacy JSON blobs to typed columns and validate deserialization
Migrate application config keys while keeping per-environment overrides intact
Change datetime storage format and verify timezone and locale compatibility
Run a dry-run migration that produces a risk-rated report for stakeholders

FAQ

What risk levels mean for migration decisions?

Critical indicates potential data loss that should block the migration. High means integrity risks that need remediation. Medium signals downstream compatibility impacts. Low denotes minor, low-risk changes.

How do I verify a rollback will work?

Maintain reverse scripts, test reversions on staging snapshots, and validate post-rollback integrity with the same checks used after forward migration.