# Generate Database Schema and Migrations from Code Using Claude Skills

> Generate database schema and migrations automatically from code using Claude Skills Migration Architect. Get phased migration plans, risk assessments, and rollback strategies effortlessly.

- Repository: [Alireza Rezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/alirezarezvani/claude-skills/blob/main/migration_planner.py)** – The core engine that parses specifications, evaluates complexity, and generates phased plans
- **[`rollback_generator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/rollback_generator.py)** – Produces detailed rollback runbooks with communication templates and escalation matrices
- **[`compatibility_checker.py`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/references/migration_patterns_catalog.md) and [`references/zero_downtime_techniques.md`](https://github.com/alirezarezvani/claude-skills/blob/main/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.

```json
{
  "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`](https://github.com/alirezarezvani/claude-skills/blob/main/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:

```bash
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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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:

```bash
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`](https://github.com/alirezarezvani/claude-skills/blob/main/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:

```bash
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`](https://github.com/alirezarezvani/claude-skills/blob/main/migration_planner.py)** engine calculates complexity, selects patterns, and generates phased plans with risk assessments
- **[`rollback_generator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/rollback_generator.py)** produces detailed reversal runbooks with communication templates and escalation procedures
- **[`compatibility_checker.py`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/zero_downtime_techniques.md) catalogs specific patterns for maintaining availability during schema changes, and the complexity calculator factors these constraints into phase planning.