db-legacy-migration-agent

CLI および MCP Server。レガシーなリレーショナル DB スキーマ（DB2、Oracle PL/SQL、MySQL、MSSQL）を解析し、生成された Prisma ORM スキーマ と TypeScript クエリヘルパー によって PostgreSQL に自動的にトランスパイル します。

目次

• 概要

• アーキテクチャ

• はじめに

• 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パース — 列、制約、 FK、インデックスを含む CREATE TABLE

3. PL/SQLパース — パラメータ方向を含む CREATE [OR REPLACE] PROCEDURE/FUNCTION

4. 型マッピング — 40以上のレガシー型マッピングを { prismaType, postgresType } に変換

5. Prisma スキーマ生成 — @@map、 @db.* 注釈、複合主キー、FKリレーション

6. TypeScript クエリ生成 — PrismaClient を使用した CRUD ヘルパー

7. PL/SQL 構造変換 — BEGIN/END, IF/THEN/ ELSIF, FOR/WHILE LOOP, :=, DBMS_OUTPUT

src/engine/schema-validator.ts

トランスパイルされたテーブル定義に対してルールエンジンを実行し、構造化された ValidationIssue レコードを出力します。

• 致命的（Critical) — データ喪失が保証されるもの（例: BIGINT_OVERFLOW、 NULLABLE_PK）

• 警告（Warning) — チェックが必要な意味的不整合（例: ORACLE_DATE_HAS_TIME、XMLTYPE_NO_NATIVE）

• 情報（Info) — 情報提供用（例: LOB_TO_TEXT, DB2_GRAPHIC_TYPE）

src/mcp/server.ts

stdio トランスポート 上で3つのツールを提供するMCPサーバ。

はじめに

前提条件

• Node.js ≥ 18

• npm ≥ 9

インストール

npm install

ビルド

npm run build

CLI をグローバルにリンク（オプション）

npm link
db-migrate --help

CLI コマンド

transpile <file>

DDLファイルを解析し、出力ディレクトリに schema.prisma、 queries.ts、 ast.json を生成します。

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

オプション:

validate <file>

型マッピングを検証し、構造化されたレポートを出力します。

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

stdio 経由でMCPサーバーを起動します（AIアシスタント統合用）。

npx ts-node src/cli.ts mcp

MCP サーバー

この 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"
  }
}

戻り値: 構造化された ValidationReport JSON または人に対する可読テキスト。

型マッピング概要

検証ルール

| コード | 重大度 | トリガー | 推奨 | | ------------------------------- ----------- | --------------------------------------------------------- | --------------------------------------- | | ORACLE_NUMBER_NO_SCALE | 警告 | スケールな型なしのNUMBER(p) → 整数または浮動小数の可能性 | 明示的なスケール化を指定する | | BIGINT_OVERFLOW | 重大 | NUMBER(p) p>18 を BigInt にマッピング | Decimal / NUMERIC を使用する | | FLOAT_SINGLE_PRECISION | 警告 | BINARY_FLOAT または FLOAT(≤24) → REAL | DOUBLE PRECISION を使用する | | LOB_TO_TEXT | 情報 | CLOB/NCLOB/LONG → TEXT | LOB ストリーミング API を更新する | | BLOB_TO_BYTEA | 情報 | BLOB/RAW → BYTEA | 1GB超の値には lo API を使用する | | ORACLE_DATE_HAS_TIME | 警告 | Oracle DATE → PostgreSQL DATE | 時刻が必要な場合は TIMESTAMP を使用する | | LOCAL_TZ_SEMANTICS | 警告 | TIMESTAMP WITH LOCAL TIME ZONE | タイムゾーン変換ロジックを確認する | | CHAR_LARGE_LENGTH | 警告 | CHAR(n) n>255 | VARCHAR(n) に置き換える | | VARCHAR2_EXCEEDS_ORACLE_LIMIT | 情報 | VARCHAR2(n) n>4000 | 未定義長には TEXT を使用する | | XMLTYPE_NO_NATIVE | 警告 | XMLTYPE | XML 操作には $queryRaw を使用する | | DB2_GRAPHIC_TYPE | 情報 | DB2 GRAPHIC / VARGRAPHIC | UTF-8 変換を検証する | | NO_PRIMARY_KEY | 警告 | テーブルに主キーがない | id または @@id を追加する | | NULLABLE_PK | 重大 | 主キー列が nullable としてパースされた | Flyway ソース DDL を修正する |

プロジェクト構成

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

期待される出力: トランスパイラーのパース、型マッピング、PL/SQL 変換、バリデーションルールにおいて、40 個以上の宣言堅実に成功します。

コントリビュート

1. リポジトリをフォークしてクローンします。

2. npm install を実行して依存関係をインストールします。

3. src/ に機能・修正を追加します。

4. tests/ にテストを追加または更新します。

5. PR を送る前に npm test と npm run typecheck を実行します。

ライセンス

MIT