# 機能設計書 7-PostgreSQL解析

## 概要

本ドキュメントは、Liamシステムにおける「PostgreSQL解析」機能の設計を記述したものである。PostgreSQLのDDL（pg_dump出力）をパースしてスキーマ情報を抽出する機能である。

### 本機能の処理概要

本機能は、pg-query-emscriptenライブラリを使用してPostgreSQL DDLを構文解析し、テーブル、カラム、制約、インデックス等のスキーマ情報をLiam内部形式（Schema型）に変換する。大規模DDLファイルに対応するため、チャンク分割処理を実装している。

**業務上の目的・背景**：PostgreSQLは最も広く使用されているオープンソースRDBMSの一つであり、pg_dumpによるスキーマエクスポートは一般的な運用である。本機能により、既存のPostgreSQLデータベースのスキーマを可視化し、ER図として表示できる。

**機能の利用シーン**：
- 既存PostgreSQLデータベースのスキーマ可視化
- pg_dump出力ファイルの解析
- マイグレーションファイルの検証
- スキーマレビュー

**主要な処理内容**：
1. DDL文字列のチャンク分割
2. pg-query-emscriptenによる構文解析
3. AST（抽象構文木）からスキーマ情報への変換
4. 部分的なパースエラーの処理と継続
5. スキーマバリデーション

**関連システム・外部連携**：pg-query-emscripten（PostgreSQL parserのemscriptenポート）を使用。

**権限による制御**：DDL解析自体に認証は不要。解析結果の表示は認証状態に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | スキーマ画面 | 主画面 | PostgreSQL DDLのパース処理 |
| 20 | 公開ERD画面 | 主画面 | PostgreSQL DDLのパース処理 |

## 機能種別

データ変換 / パース処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| sql | string | Yes | PostgreSQL DDL文字列 | - |
| chunkSize | number | No | チャンクサイズ（行数）、デフォルト500 | - |

### 入力データソース

- pg_dump出力ファイル
- マイグレーションファイル
- 手動入力DDL

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| value | Schema | パース結果のスキーマ |
| errors | ProcessError[] | パース中に発生したエラー/警告 |

### 出力先

スキーマストア / ER図表示機能

## 処理フロー

### 処理シーケンス

```
1. DDL受信
   └─ SQL文字列を受け取る
2. チャンク分割
   └─ processSQLInChunksで行数ベースで分割
3. チャンク毎パース
   └─ pg-query-emscriptenでパース
4. スキーマ変換
   └─ convertToSchemaでAST→Schema変換
5. スキーママージ
   └─ mergeSchemas で結果を統合
6. バリデーション
   └─ valibotでスキーマバリデーション
7. 結果返却
   └─ ProcessResult形式で返却
```

### フローチャート

```mermaid
flowchart TD
    A[SQL文字列入力] --> B[processSQLInChunks]
    B --> C{チャンク処理ループ}
    C --> D[parse チャンク]
    D --> E{パースエラー?}
    E -->|Yes| F[エラー記録・リトライ]
    E -->|No| G[convertToSchema]
    G --> H[mergeSchemas]
    H --> C
    F --> C
    C -->|完了| I[safeParse バリデーション]
    I --> J{バリデーション成功?}
    J -->|Yes| K[結果返却]
    J -->|No| L[バリデーションエラー追加]
    L --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | チャンクサイズ | デフォルト500行でチャンク分割 | 大規模DDL時のメモリ対策 |
| BR-002 | 部分エラー継続 | パースエラーが発生しても継続処理 | エラーをerrorsに蓄積 |
| BR-003 | 未完了文検出 | stmt_lenが未定義の場合は文が未完了と判定 | チャンク境界処理 |

### 計算ロジック

サポートするDDL文:
- CREATE TABLE
- ALTER TABLE (ADD COLUMN, ADD CONSTRAINT等)
- CREATE INDEX
- COMMENT ON TABLE/COLUMN

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベースを直接操作しない。パース処理のみ。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| PARSE_ERROR | 構文エラー | DDL構文が不正 | UnexpectedTokenWarningErrorとして記録 |
| VALIDATION_ERROR | バリデーションエラー | 変換結果がスキーマ型に適合しない | エラー追加後に結果返却 |

### リトライ仕様

チャンク境界でパースエラーが発生した場合、リトライオフセットを調整して再試行。

## トランザクション仕様

該当なし（メモリ内処理）

## パフォーマンス要件

- 大規模DDL（数万行）でも処理可能
- チャンク分割によるメモリ使用量最適化

## セキュリティ考慮事項

- DDL内のSQLインジェクションリスクはない（パースのみ）
- 機密情報を含むDDLは認証後のみ処理

## 備考

pg-query-emscriptenはPostgreSQLの公式parserをWebAssemblyにコンパイルしたもので、高い互換性を持つ。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `frontend/packages/schema/src/parser/sql/postgresql/index.ts` | processor関数、チャンク処理の流れ |

**主要処理フロー**:
1. **129行目**: CHUNK_SIZE = 500（デフォルト値）
2. **135-163行目**: processor関数、チャンク処理ループ
3. **143-154行目**: processChunk呼び出しとエラー処理

#### Step 2: チャンク処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | processSqlInChunks.ts | `frontend/packages/schema/src/parser/sql/postgresql/processSqlInChunks.ts` | チャンク分割ロジック |
| 2-2 | index.ts processChunk | `frontend/packages/schema/src/parser/sql/postgresql/index.ts` | 個別チャンクのパース |

#### Step 3: スキーマ変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | converter.ts | `frontend/packages/schema/src/parser/sql/postgresql/converter.ts` | AST→Schema変換 |
| 3-2 | mergeSchemas.ts | `frontend/packages/schema/src/parser/sql/postgresql/mergeSchemas.ts` | スキーマ統合 |

### プログラム呼び出し階層図

```
processor (index.ts)
    │
    ├─ processSQLInChunks
    │      └─ チャンク分割ループ
    │
    └─ processChunk
           │
           ├─ parse (pg-query-emscripten)
           │      └─ AST生成
           │
           ├─ convertToSchema
           │      └─ テーブル/カラム/制約抽出
           │
           └─ mergeSchemas
                  └─ 結果統合
```

### データフロー図

```
[入力]               [処理]                    [出力]

DDL文字列 ──────────▶ チャンク分割 ───────────▶ チャンク[]
                           │
                           ▼
チャンク ──────────▶ pg-query-emscripten ────▶ AST
                           │
                           ▼
AST ───────────────▶ convertToSchema ────────▶ 部分Schema
                           │
                           ▼
部分Schema[] ──────▶ mergeSchemas ───────────▶ 統合Schema
                           │
                           ▼
統合Schema ────────▶ safeParse ──────────────▶ バリデーション済みSchema
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `frontend/packages/schema/src/parser/sql/postgresql/index.ts` | ソース | メインprocessor |
| converter.ts | `frontend/packages/schema/src/parser/sql/postgresql/converter.ts` | ソース | AST変換 |
| parser.ts | `frontend/packages/schema/src/parser/sql/postgresql/parser.ts` | ソース | pg-query-emscriptenラッパー |
| mergeSchemas.ts | `frontend/packages/schema/src/parser/sql/postgresql/mergeSchemas.ts` | ソース | スキーマ統合 |
| processSqlInChunks.ts | `frontend/packages/schema/src/parser/sql/postgresql/processSqlInChunks.ts` | ソース | チャンク分割 |
