# okf-bundler

**Repository Path**: gooree/okf-bundler

## Basic Information

- **Project Name**: okf-bundler
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OKF Bundler

从数据库 **DDL** 或 **SQL 脚本** 生成 [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundle 的 CLI 工具。输出格式与 `knowledge-catalog/okf` 及 `knowledge-catalog/toolbox/mdcode/demo/okf` 中的 markdown bundle 一致，可直接用于 Knowledge Catalog 的 Documents Layout 发布。

## 功能

- **DDL脚本预处理**：自动清理与表结构无关的内容
  - 清理注释（`--`、`/* */`）
  - 清理数据操作语句（`INSERT`、`UPDATE`、`DELETE`）
  - 清理对象定义（`DROP`、`TRUNCATE`、`CREATE INDEX`）
  - 清理数据库对象（`CREATE FUNCTION/PROCEDURE/TRIGGER/VIEW`）
  - 清理存储引擎和字符集定义（`ENGINE`、`CHARSET`、`COLLATE`）
  - **保留** `COMMENT ON` 语句（表注释、字段注释、schema注释）
  - **保留** `CREATE TABLE`、`CREATE SCHEMA/DATABASE` 表结构定义
- 解析 `CREATE SCHEMA` / `CREATE DATABASE` / `CREATE TABLE` / `USE` 语句
- **多数据库方言支持**（基于 [sqlglot](https://github.com/tobymao/sqlglot)）：
  - **MySQL / MariaDB** — `COMMENT`、`` ` `` 标识符、`USE database`、InnoDB 外键
  - **PostgreSQL / Redshift** — `COMMENT ON`、`SERIAL`、列级 `REFERENCES`
  - **SQL Server** — `GO` 批处理、`IDENTITY`、`[]` 标识符
  - **SQLite** — 内联 `FOREIGN KEY`、`AUTOINCREMENT`
  - **BigQuery、Oracle、Snowflake、DuckDB、ClickHouse、Hive、Spark、Trino** 等
- 按方言自动生成 OKF 类型名（如 `MySQL Table`、`PostgreSQL Schema`）与 resource URI（`mysql://`、`postgres://` 等）
- 从外键生成 `references/joins/` 关联文档（含 DDL 显式定义 + **命名规则自动推断**）
- **外键自动推断**（默认开启，可用 `--no-infer-fks` 关闭）：
  - 字段名规则：A、B 表存在同名字段，且该字段为 A 表主键 → 推断 B 表该字段引用 A
  - 表名规则：B 表名以 A 表全名 + `_` 为前缀（如 `t_product` / `t_product_sku`），且 B 表存在与 A 表同名的字段 → 推断子表外键
- **临时表检测**（默认开启）：表名以 `tmp`、`temp`、`copy`、数字等结尾的表跳过 bundle 生成，结果写入 `temp_tables.md`；可用 `--include-table` 强制处理
- 自动生成目录 `index.md` 索引页
- 同步生成 `viz.html` 交互式可视化

## 安装

```bash
# 方式1: pip 安装（推荐，已安装后直接使用 okf-bundler 命令）
pip install -e /path/to/okf-bundler

# 方式2: 虚拟环境安装
cd /path/to/okf-bundler
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

# 方式3: 直接运行（无需安装）
python -m okf_bundler generate --input schema.sql --out ./bundle
```

## 用法

```bash
# 查看支持的数据库方言及默认配置
okf-bundler dialects

# PostgreSQL（默认）
okf-bundler generate --input examples/sample.sql --out ./output/bundle

# MySQL
okf-bundler generate --input examples/mysql.sql --out ./output/mysql-bundle --dialect mysql

# SQL Server（支持 GO 批处理）
okf-bundler generate --input examples/mssql.sql --out ./output/mssql-bundle --dialect tsql

# SQLite
okf-bundler generate --input examples/sqlite.sql --out ./output/sqlite-bundle --dialect sqlite

# 方言别名：pg、mariadb、mssql、bq 等
okf-bundler generate --input schema.sql --out ./bundle --dialect pg

# 扫描目录下所有 .sql / .ddl 文件
okf-bundler generate --input-dir ./migrations --out ./output/bundle --dialect postgres

# 排除指定目录（适用于有 node_modules、test、backup 等子目录的场景）
okf-bundler generate --input-dir ./ddl --exclude-dir test --exclude-dir backup --out ./bundle

# 只扫描顶层目录，不递归子目录
okf-bundler generate --input-dir ./ddl --no-recursive --out ./bundle

# 指定文件扩展名（默认 .sql、.ddl）
okf-bundler generate --input-dir ./ddl --extension .sql --extension .ddl --out ./bundle

# BigQuery 风格（也可显式覆盖类型名）
okf-bundler generate --input schema.sql --out ./bundle --dialect bigquery

# 自定义 resource URI 前缀与标签
okf-bundler generate --input schema.sql --out ./bundle \
  --resource-prefix "https://example.com/schemas" --tag ecommerce

# 为已有 bundle 单独重新生成可视化
okf-bundler visualize --bundle ./output/bundle

# 临时表会被自动跳过；强制处理某个“临时表”
okf-bundler generate --input examples/temp_tables.sql --out ./output/bundle \
  --include-table demo.users_tmp
```

### 方言默认值

| 方言 | 默认 schema/database | OKF 类型 |
|------|---------------------|----------|
| `postgres` | `public` | PostgreSQL Schema / Table |
| `mysql` | 从 `USE` 或 `CREATE DATABASE` 推断 | MySQL Database / Table |
| `tsql` | `dbo` | SQL Server Schema / Table |
| `sqlite` | `main` | SQLite Database / Table |
| `bigquery` | 从 DDL 推断 | BigQuery Dataset / Table |

运行 `okf-bundler dialects` 查看完整列表。

### 输出目录结构

```
output/bundle/
├── index.md
├── viz.html                     # 交互式概念关系图（浏览器打开）
├── datasets/
│   ├── index.md
│   └── ecommerce.md
├── tables/
│   ├── index.md
│   ├── users.md
│   ├── orders.md
│   └── ...
└── references/
    └── joins/
        ├── index.md
        └── orders___users.md
```

每个 `.md` 文件包含 YAML frontmatter（`type`、`title`、`description`、`resource`、`tags`、`timestamp`）和 markdown 正文（Overview、Schema、Relationships 等），与 knowledge-catalog 中的 OKF bundle 格式兼容。

## 开发与测试

```bash
pytest
python -m okf_bundler generate --input examples/sample.sql --out /tmp/okf-demo
```