db-legacy-migration-agent

CLI и MCP-сервер, который разбирает схемы устаревших реляционных БД (DB2, Oracle PL/SQL, MySQL, MSSQL) и автоматически транспилирует их в PostgreSQL с генерацией Prisma ORM-схемы и TypeScript-хелперов для запросов.

Оглавление

• Обзор

• Архитектура

• Начало работы

• Команды CLI

• MCP-сервер

• Справочник по сопоставлению типов

• Правила валидации

• Структура проекта

• Запуск тестов

Related MCP server: db-mcp

Обзор

Устаревшие корпоративные системы часто полагаются на вендор-специфичные диалекты SQL (Oracle PL/SQL, IBM DB2, Microsoft T-SQL), которые невозможно перенести напрямую в современные стеки без значительных ручных усилий. Этот инструмент автоматизирует этап структурной транспиляции:

Архитектура

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)

Основные модули

src/parser/sql-transpiler.ts

Отвечает за полный конвейер транспиляции:

1. Токенизация — удаление комментариев, нормализация пробелов, обработка идентификаторов в кавычках

2. Разбор DDL — CREATE TABLE с колонками, ограничениями, внешними ключами, индексами

3. Разбор PL/SQL — CREATE [OR REPLACE] PROCEDURE/FUNCTION с направлениями параметров

4. Сопоставление типов — более 40 сопоставлений устаревших типов в { prismaType, postgresType }

5. Генерация схемы Prisma — аннотации @@map, @db.*, составные первичные ключи, FK-связи

6. Генерация TypeScript-запросов — CRUD-хелперы с использованием PrismaClient

7. Структурная трансляция PL/SQL — BEGIN/END, IF/THEN/ELSIF, циклы FOR/WHILE, :=, DBMS_OUTPUT

src/engine/schema-validator.ts

Запускает правиловой движок по транспилированным определениям таблиц и формирует структурированные записи ValidationIssue:

• Критическая ошибка — гарантированная потеря данных (например, BIGINT_OVERFLOW, NULLABLE_PK)

• Предупреждение — семантическое несоответствие, требующее проверки (например, ORACLE_DATE_HAS_TIME, XMLTYPE_NO_NATIVE)

• Информация — информационные уведомления (например, LOB_TO_TEXT, DB2_GRAPHIC_TYPE)

src/mcp/server.ts

MCP-сервер, предоставляющий три инструмента через stdio-транспорт:

Начало работы

Требования

• Node.js ≥ 18

• npm ≥ 9

Установка

npm install

Сборка

npm run build

Глобальная установка CLI (необязательно)

npm link
db-migrate --help

Команды CLI

transpile <файл>

Разбирает DDL-файл и генерирует schema.prisma, queries.ts и ast.json в выходной директории.

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

Опции:

validate <файл>

Проверяет сопоставление типов и выводит структурированный отчёт.

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

Опции:

Коды выхода:

parse-inline <файл DDL>>`

Быстрый тест — разбор DDL-строки прямо из командной строки.

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

Запускает MCP-сервер в режиме stdio (для интеграции с AI-ассистентами).

npx ts-node src/cli.ts mcp

MCP Server

MCP-сервер можно зарегистрировать в любом MCP-совместимом AI-ассистенте (например, Claude Desktop, IBM Bob).

Инструмент: parse_legacy_ddl

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

Возвращает: полный AST, схему Prisma, TypeScript-запросы, предупреждения.

Инструмент: generate_prisma_schema

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

Возвращает: содержимое schema.prisma как обычную строку.

Инструмент: validate_type_mapping

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

Возвращает: структурированный JSON-отчёт ValidationReport или читаемый текст.

Справочник по сопоставлению типов

Oops, I sent a wrong table row above - correct it: The BIGINT row: Prisma Type = BigInt, PostgreSQL = BIGINT. And the last row: JSON / JSONB | Json | JSON / JSONB. And the TIMESTAMP row is fine. The first "TIMESTAMP WITH") line.

I'll write the correct final table version later.

Правила валидации

Структура проекта

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

Запуск тестов

# Run all tests
npm test

# With coverage
npm test -- --coverage

# Watch mode
npm test -- --watch

Ожидаемый результат: более 40 проверок по раздработке механизма, сопоставлению типов, трансляции PL/SQL и правилам валидатора.

Внесение вклада

1. Сделайте fork и клонируйте репозиторий

2. Выполните npm install для установки зависимостей

3. Добавьте свою новую функцию/исправление в src/

4. Добавьте или обновите тесты в tests/

5. Запустите npm test и npm run typecheck перед подачей PR

Лицензия

MIT