Generate Database Schema and Migrations from Code Using Claude Skills

The Claude Skills repository provides a complete code-to-migration pipeline through its Migration-Architect skill, enabling automated generation of phased database migration plans, risk assessments, and rollback strategies directly from JSON specifications.

The ability to generate database schema and migrations from code eliminates manual planning errors and standardizes infrastructure changes. The Migration-Architect skill in the alirezarezvani/claude-skills repository offers a modular, pure-Python solution that transforms code-level specifications into executable migration plans. This tool parses structured inputs, evaluates complexity heuristics, and produces comprehensive runbooks that integrate seamlessly into CI/CD pipelines.

Architecture of the Migration-Architect Skill

The Migration-Architect skill follows the standard Claude-Skills design pattern: references → SKILL.md → scripts → assets. Located in engineering/migration-architect/, the skill comprises three core Python modules and comprehensive documentation that together handle the full migration lifecycle.

The primary components include:

• migration_planner.py – The core engine that parses specifications, evaluates complexity, and generates phased plans
• rollback_generator.py – Produces detailed rollback runbooks with communication templates and escalation matrices
• compatibility_checker.py – Analyzes schema and API compatibility between source and target systems
• Reference documentation – Catalogs migration patterns and zero-downtime techniques in references/migration_patterns_catalog.md and references/zero_downtime_techniques.md

The Specification-to-Plan Pipeline

The pipeline converts a JSON specification into a complete MigrationPlan dataclass containing every artifact needed for execution, reporting, and audit.

Input Specification Format

The system accepts a structured JSON file defining migration parameters. The specification includes the migration type (database, service, etc.), source and target system identifiers, constraints such as data volume and downtime limits, and optional custom risk items.

{
  "type": "database",
  "source": "legacy_sales_db",
  "target": "cloud_sales_db",
  "pattern": "schema_change",
  "constraints": {
    "data_volume_gb": 3500,
    "dependencies": ["auth_service", "billing_service"],
    "max_downtime_minutes": 30,
    "special_requirements": ["zero_downtime", "encryption_at_rest"]
  }
}

The MigrationPlanner Engine

In engineering/migration-architect/scripts/migration_planner.py, the MigrationPlanner class orchestrates the transformation from specification to executable plan through several deterministic methods:

• _calculate_complexity (lines 88-124) – Computes complexity scores based on data volume, dependencies, downtime constraints, and special requirements
• _load_migration_patterns (lines 10-48) – Selects appropriate strategies (e.g., schema_change, data_migration, strangler_fig) from an internal catalog
• _estimate_duration (lines 29-35) – Calculates timeline estimates using base duration multiplied by complexity factors
• _generate_phases (lines 58-90) – Creates sequential phases with descriptions, task lists, validation criteria, and resource requirements
• _assess_risks (lines 92-119) – Merges predefined risk templates with specification-specific concerns
• _generate_rollback_plan (lines 22-65) – Constructs reversal strategies with triggers and decision matrices

The final output is a MigrationPlan dataclass (lines 85-99) that encapsulates phases, risk assessments, rollback strategies, and resource allocations.

Generating Migration Artifacts

The skill produces three distinct deliverables that operationalize the migration specification.

Creating the Migration Plan

Invoke the planner from the command line to generate both JSON and human-readable outputs:

python engineering/migration-architect/scripts/migration_planner.py \
  --input sample_database_migration.json \
  --output db_migration_plan.json \
  --format both

The resulting db_migration_plan.json contains the serialized MigrationPlan dataclass, while the TXT format provides operationally-focused documentation for engineering teams.

Building Rollback Runbooks

The rollback_generator.py module consumes the migration plan JSON and emits comprehensive reversal procedures. Located at lines 340-395, the generation logic reverses phase order, creates specific rollback actions, and defines validation checkpoints. The module also supplies communication templates and escalation matrices (lines 724-756) for stakeholder management during incidents.

Execute the rollback generator:

python engineering/migration-architect/scripts/rollback_generator.py \
  --plan db_migration_plan.json \
  --output rollback_runbook.json

Validating Compatibility

Before executing migrations, compatibility_checker.py validates system changes through two primary analyses:

• Database schema diffs (lines 241-255) – Detects table, column, and constraint changes with validation queries
• API contract changes (lines 258-598) – Identifies breaking changes in OpenAPI specifications through path and response analysis

The compatibility report can be fed back into the migration specification as additional risk items:

python engineering/migration-architect/scripts/compatibility_checker.py \
  --before database_schema_before.json \
  --after database_schema_after.json \
  --output schema_compat_report.json

Extensibility and Integration

All scripts depend only on the Python standard library and expose CLI interfaces through argparse. This design allows importation as libraries for programmatic integration or direct invocation from shell scripts.

Adding new migration patterns requires extending the _load_migration_patterns dictionary with new entries following the existing structure for patterns like cloud_migration. Similarly, new risk templates can be added to _load_risk_templates without modifying core logic.

Summary

• Migration-Architect in alirezarezvani/claude-skills provides a complete solution to generate database schema and migrations from code using JSON specifications
• The migration_planner.py engine calculates complexity, selects patterns, and generates phased plans with risk assessments
• rollback_generator.py produces detailed reversal runbooks with communication templates and escalation procedures
• compatibility_checker.py validates schema and API changes before migration execution
• All components are pure-Python, CLI-accessible, and designed for CI/CD pipeline integration

Frequently Asked Questions

What input format does the Migration-Architect skill require?

The skill requires a JSON specification defining the migration type, source and target systems, constraints (including data_volume_gb, max_downtime_minutes, and dependencies), and optional custom risk items. The assets/sample_database_migration.json file in the repository provides a complete reference implementation.

How does the tool calculate migration complexity?

The _calculate_complexity method in migration_planner.py (lines 88-124) evaluates multiple factors: data volume, system dependencies, downtime limitations, and special requirements like encryption or zero-downtime constraints. These factors combine to determine phase sequencing and duration estimates.

Can I extend the migration patterns or risk templates?

Yes. The architecture supports extension by adding new dictionary entries to _load_migration_patterns (lines 10-48) for additional migration strategies, or by modifying _load_risk_templates (lines 92-119) to include domain-specific risks. This requires no changes to the core planning engine.

Is this tool suitable for zero-downtime database migrations?

Yes. The skill explicitly supports zero-downtime requirements through the special_requirements field in the specification. The reference documentation in zero_downtime_techniques.md catalogs specific patterns for maintaining availability during schema changes, and the complexity calculator factors these constraints into phase planning.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}