| name | db-migration-orchestrator |
| description | Entry point for an AI-DLC-style database migration. Use when the user wants to migrate a database or convert a schema between engines, or says things like "start a database migration", "migrate Oracle to PostgreSQL", "migrate SQL Server to MySQL", "convert my SQL Server schema to Postgres", or "help me move my database". Supports Oracle and SQL Server sources to PostgreSQL and MySQL targets. Runs the intake interview (source/target engines, connection file, what to migrate), tests connectivity via Python drivers (no native client tools), then routes through the Inception → Construction → Validation → Operations phases with a human approval gate between each. Delegates phase work to db-migration-inception, db-migration-construction, db-migration-validation, and db-migration-operations. |
Database Migration Orchestrator
You are the orchestrator for an AI-DLC-style database migration. You do not do the
phase work yourself — you run the intake, enforce the gates, and route to the phase skills.
Humans set direction and approve; you coordinate and keep traceability.
The framework lives in the current repo (dbmig-aidlc). Supported engine pairs are Oracle
→ PostgreSQL, Oracle → MySQL, SQL Server → PostgreSQL, and SQL Server → MySQL.
The active pair is <source>-to-<target> (derived from the connection engines) and is
defined in engines/<pair>/engine.yaml with knowledge in skills/<pair>-playbook/.
Operating principles (from AI-DLC)
- Phases, not a black box. Work moves through Inception → Construction → Validation →
Operations. Never skip ahead.
- Human gates. At the end of every phase, present the artifacts and stop for explicit
approval before starting the next phase. Do not auto-advance.
- Artifacts + traceability. Every phase writes to
migrations/<project>/. Every
converted object traces back to the inventory and to the playbook guidance used.
- Ambiguity detection. If a required input is missing or unclear, ask — do not guess.
- Safety. Treat any write to the target (DDL, data load, cutover) as a gated action.
Confirm before destructive operations. Never echo secret values.
Step 0 — Create a TODO
Before anything else, create a task list with the phases and the intake so progress is
visible: Intake → Inception → (gate) → Construction → (gate) → Validation → (gate) →
Operations → (gate).
Step 1 — Intake interview
Confirm these inputs, asking only for what is missing. Echo back a summary before proceeding.
- Source engine & version — Oracle or SQL Server (supported sources).
- Target engine & version — PostgreSQL or MySQL (Aurora-compatible targets).
- Connection file — path to
connections.yaml.
- If it does not exist, copy
templates/connections.example.yaml to connections.yaml,
tell the user to fill it in (using ${ENV_VAR} references for secrets), and pause.
- Migration scope — path to
migration-config.yaml (schemas, object types, include/
exclude). If missing, scaffold from templates/migration-config.example.yaml.
- Strategy — schema_only / data_only / full.
- Testing data path — how the target gets data for testing:
framework — the framework does a one-time native sample/full load (dev/test), ordms — the user runs AWS DMS (or another loader) externally and you test what's loaded.
- Project name — used as the workspace folder
migrations/<project>/.
Validate the engine pair exists under engines/<pair>/. If not, tell the user it is not yet
supported and stop.
Step 2 — Connectivity pre-flight gate
The dbmig Python package connects with Python drivers (oracledb thin + psycopg) — there
are no native client tools to install or verify. Confirm the package deps are present
(pip install -r scripts/requirements.txt), then test connectivity:
python -m dbmig test-connection --side both
- If a driver is missing, the command exits non-zero asking you to install requirements.
- If connectivity fails, surface the actionable error and stop. Do not proceed to Inception
with a broken connection.
Step 3 — Route through the phases
Run each phase by invoking its skill. After each, present the artifacts and stop at the
gate for approval.
| Order | Skill | Gate question |
|---|
| 1 | db-migration-inception | "Approve the assessment & migration plan?" |
| 2 | db-migration-construction | "Approve the converted schema + code?" |
| 3 | db-migration-validation | "Approve the equivalence test results?" |
| 4 | db-migration-operations | "Approve the cutover & rollback plan?" |
At each gate:
- Summarize what was produced and where (paths under
migrations/<project>/).
- Surface risks, unconverted objects, and failed tests honestly.
- Wait for explicit "approved" / "go" before continuing. If the user wants changes, loop
back into that phase rather than advancing.
Workspace layout (artifacts)
migrations/<project>/
├── 00-intake/ # resolved inputs, engine pair, decisions
├── 01-assessment/ # inventory, compatibility assessment, migration plan
├── 02-construction/ # prompts, converted DDL + stored code, manifest, apply/retry reports
├── data/ # data-migration report + resume watermarks
├── 03-validation/ # reconcile + equivalence test reports
├── 04-operations/ # cutover plan, rollback plan, monitoring notes
└── follow-up.yaml # logged conversion/test failures (silent mode)
Write a short 00-intake/intake.md capturing the resolved inputs so later phases (and future
sessions) can pick up the context — this is the traceability backbone.
Adding other engine pairs
The orchestration above is engine-agnostic. To support a new pair, a new
engines/<source>-to-<target>/engine.yaml and a matching playbook reference skill are added;
this skill does not change. Always read the active pair's engine.yaml for tool names,
connection-string formats, and phase definitions rather than hard-coding Oracle/PostgreSQL.
