JSON Seed Data Converter

將 JSONC 格式的種子資料轉換為 SQL INSERT 語句，專為 Cloudflare D1 和 SQLite 資料庫設計。

特點

• ✅ 支援 JSONC (JSON with Comments)
• ✅ 自動從 schema.sql 讀取欄位順序
• ✅ 資料型別驗證
• ✅ 可跨專案重複使用
• ✅ 支援依賴順序管理 (Import Order)
• ✅ 分組匯入 (Group-based Import)
• ✅ 支援 Deno 和 Node.js

安裝

全域安裝 (推薦)

npm install -g json-seed-converter

專案內安裝

npm install json-seed-converter

使用方法

CLI 使用

# 基本使用
json-seed-convert

# 指定路徑
json-seed-convert \
  --seed-dir /path/to/seed-data \
  --schema /path/to/schema.sql \
  --output /path/to/seed.sql

# 只匯入特定群組
json-seed-convert -g base_data

# 詳細輸出
json-seed-convert -v

選項

| 選項 | 簡寫 | 說明 | 預設值 | |------|------|------|--------| | --seed-dir | -s | 種子資料目錄 | ./src/db/seed-data | | --schema | -c | Schema SQL 檔案 | ./src/db/schema.sql | | --output | -o | 輸出 SQL 檔案 | ./src/db/seed-generated.sql | | --import-order | -i | 匯入順序配置 | ./src/db/seed-data/import-order.jsonc | | --group | -g | 匯入群組名稱 | - | | --verbose | -v | 詳細輸出 | false | | --help | -h | 顯示說明 | - |

專案整合

NPM Scripts

在 package.json 中定義：

{
  "scripts": {
    "db:convert-seed": "json-seed-convert",
    "db:convert-seed:base": "json-seed-convert -g base_data -o src/db/seed-base.sql",
    "db:convert-seed:member": "json-seed-convert -g member_dependent -o src/db/seed-member-dependent.sql"
  }
}

Shell Script 整合

#!/bin/bash
CONVERTER_DIR="$HOME/workspace/tools/json-seed-converter"
SEED_DATA_DIR="$PROJECT_ROOT/src/db/seed-data"
SCHEMA_FILE="$PROJECT_ROOT/src/db/schema.sql"
OUTPUT_FILE="$PROJECT_ROOT/src/db/seed-generated.sql"

deno run --allow-read --allow-write \
  "$CONVERTER_DIR/src/cli.ts" \
  --seed-dir "$SEED_DATA_DIR" \
  --schema "$SCHEMA_FILE" \
  --output "$OUTPUT_FILE"

資料格式

JSONC 種子資料

// 這是註解
{
  "_comment": "資料說明",
  "table": "table_name",
  "data": [
    {
      "id": "row_001",
      "name": "Example",
      "count": 42,
      "active": true,
      "nullable_field": null,
      "array_field": [1, 2, 3]
    }
  ]
}

Import Order 配置

{
  "_comment": "Seed data import order configuration",
  "tables": [
    {
      "name": "members",
      "file": "members.jsonc",
      "skip_import": true,
      "reason": "Created via API registration"
    },
    {
      "name": "ads",
      "file": "ads.jsonc",
      "depends_on": ["members"]
    }
  ],
  "import_groups": [
    {
      "name": "base_data",
      "tables": ["wishes"]
    },
    {
      "name": "member_dependent",
      "tables": ["ads", "notifications"]
    }
  ]
}

程式庫使用

import { convertAllJsonToSql, saveSql } from "json-seed-converter";

const sql = await convertAllJsonToSql({
  seedDataDir: "./src/db/seed-data",
  schemaPath: "./src/db/schema.sql",
  outputPath: "./src/db/seed-generated.sql",
  verbose: true,
});

await saveSql(sql, "./src/db/seed-generated.sql");

開發

建置

npm run build

測試

npm test

發布

npm publish

授權

MIT License

作者

Lex Yang