db-legacy-migration-agent

CLI y servidor MCP que analiza esquemas heredados de bases de datos relacionales (DB2, Oracle PL/SQL, MySQL, MSSQL) y los transpila automáticamente a PostgreSQL con un esquema de Prisma ORM generado y utilidades de consulta en TypeScript.

Tabla de contenidos

• Visión general

• Arquitectura

• Primeros pasos

• Comandos CLI

• Servidor MCP

• Referencia de mapeo de tipos

• Reglas de validación

• Estructura del proyecto

• Ejecutar las pruebas

Related MCP server: db-mcp

Visión general

Los sistemas empresariales heredados suelen depender de dialectos SQL específicos del proveedor (Oracle PL/SQL, IBM DB2, Microsoft T-SQL) que no pueden migrarse directamente a pilas tecnológicas modernas sin un esfuerzo manual significativo. Esta herramienta automatiza la fase de traducción estructural:

Arquitectura

src/
├── parser/
│   └── sql-transpiler.ts     # DDL lexer/parser + Prisma/TS code generator
├── engine/
│   └── schema-validator.ts   # Precision-loss & semantic mismatch validator
├── mcp/
│   └── server.ts             # MCP server (stdio transport)
└── cli.ts                    # Commander.js interactive CLI
tests/
└── transpiler.test.ts        # Jest unit tests (40+ assertions)

Módulos principales

src/parser/sql-transpiler.ts

Responsable de todo el proceso de transpilación:

1. Tokenización — elimina comentarios, normaliza los espacios en blanco y gestiona los identificadores entre comillas.

2. Análisis de DDL — CREATE TABLE con columnas, restricciones, claves externas (FK) e índices.

3. Análisis de PL/SQL — CREATE [OR REPLACE] PROCEDURE/FUNCTION con direcciones de parámetros.

4. Mapeo de tipos — más de 40 mapeos de tipos heredados a { prismaType, postgresType }.

5. Generación del esquema Prisma — anotaciones @@map, @db.*, claves primarias compuestas y relaciones FK.

6. Generación de consultas TypeScript — funciones auxiliares CRUD que usan PrismaClient.

7. Traducción estructural de PL/SQL — BEGIN/END, IF/THEN/ELSIF, FOR/WHILE LOOP, :=, DBMS_OUTPUT.

src/engine/schema-validator.ts

Ejecuta un motor de reglas sobre las definiciones de tablas transpiladas y emite registros estructurados ValidationIssue:

• Crítico — pérdida de datos garantizada (p. ej., BIGINT_OVERFLOW, NULLABLE_PK)

• Advertencia — discrepancia semántica que requiere revisión (p. ej., ORACLE_DATE_HAS_TIME, XMLTYPE_NO_NATIVE)

• Información — notas informativas (p. ej., LOB_TO_TEXT, DB2_GRAPHIC_TYPE)

src/mcp/server.ts

Servidor MCP que expone tres herramientas mediante transporte stdio:

Primeros pasos

Requisitos previos

• Node.js ≥ 18

• npm ≥ 9

Instalación

npm install

Compilación

npm run build

Enlazar la CLI globalmente (opcional)

npm link
db-migrate --help

Comandos CLI

transpile <file>

Analiza un archivo DDL y genera schema.prisma, queries.ts y ast.json en el directorio de salida.

npx ts-node src/cli.ts transpile ./examples/oracle_hr.sql \
  --dialect oracle \
  --out ./output

Opciones:

validate <file>

Valida los mapeos de tipos y genera un informe estructurado.

npx ts-node src/cli.ts validate ./examples/oracle_hr.sql \
  --dialect oracle \
  --format text

Opciones:

Códigos de salida:

parse-inline <ddl>

Prueba rápida — analiza una cadena DDL directamente desde la línea de comandos.

npx ts-node src/cli.ts parse-inline \
  "CREATE TABLE T (ID NUMBER(10) NOT NULL, NAME VARCHAR2(100), CONSTRAINT PK_T PRIMARY KEY (ID));"

mcp

Inicia el servidor MCP mediante stdio (para la integración con asistentes de IA).

npx ts-node src/cli.ts mcp

Servidor MCP

El servidor MCP puede registrarse con cualquier asistente de IA compatible con MCP (p. ej., Claude Desktop, IBM Bob).

Herramienta: parse_legacy_ddl

{
  "tool": "parse_legacy_ddl",
  "input": {
    "ddl": "CREATE TABLE EMPLOYEES (...);",
    "dialect": "oracle",
    "include_typescript": true
  }
}

Devuelve: AST completo, esquema Prisma, consultas TypeScript y advertencias.

Herramienta: generate_prisma_schema

{
  "tool": "generate_prisma_schema",
  "input": {
    "ddl": "CREATE TABLE EMPLOYEES (...);",
    "dialect": "oracle"
  }
}

Devuelve: el contenido de schema.prisma como una cadena de texto simple.

Herramienta: validate_type_mapping

{
  "tool": "validate_type_mapping",
  "input": {
    "ddl": "CREATE TABLE EMPLOYEES (...);",
    "dialect": "oracle",
    "format": "json"
  }
}

Devuelve: un JSON estructurado ValidationReport o texto legible por humanos.

Referencia de mapeo de tipos

Reglas de validación

Estructura del proyecto

db-legacy-migration-agent/
├── src/
│   ├── parser/
│   │   └── sql-transpiler.ts    # Type mappings, DDL parser, Prisma & TS generators
│   ├── engine/
│   │   └── schema-validator.ts  # Rule engine, ValidationReport, formatter
│   ├── mcp/
│   │   └── server.ts            # MCP server with 3 tools
│   └── cli.ts                   # Commander.js CLI entrypoint
├── tests/
│   └── transpiler.test.ts       # Jest unit tests
├── dist/                        # Compiled output (after `npm run build`)
├── output/                      # Generated files (schema.prisma, queries.ts, ast.json)
├── package.json
├── tsconfig.json
└── README.md

Ejecutar las pruebas

# Run all tests
npm test

# With coverage
npm test -- --coverage

# Watch mode
npm test -- --watch

Resultado esperado: más de 40 aserciones en el análisis del transpilador, el mapeo de tipos, la traducción de PL/SQL y las reglas del validador.

Contribuciones

1. Haz un fork del repositorio y clónalo

2. Ejecuta npm install para instalar las dependencias

3. Añade tu funcionalidad o corrección en src/

4. Añade o actualiza las pruebas en tests/

5. Ejecuta npm test y npm run typecheck antes de enviar un PR

Licencia

MIT