DB2TOON MCP

db2toon

一款可将数据库架构转换为 Toon 架构定义格式的命令行工具。

概述

db2toon 可连接数据库并提取架构信息（表、列、类型、约束、索引、例程、触发器和示例），然后将其转换为便于阅读的 Toon 格式，用于数据库设计文档和可视化。支持 PostgreSQL、SQLite、DuckDB、MySQL/MariaDB、CockroachDB、Microsoft SQL Server 和 Oracle。pg2toon 仍作为 PostgreSQL 兼容命令保留。

功能

• 架构提取：自动从 PostgreSQL、SQLite、DuckDB、MySQL/MariaDB、CockroachDB、Microsoft SQL Server 和 Oracle 提取表、列和元数据
• 类型规范化：简化 PostgreSQL 类型（例如，character varying → varchar）
• 关系映射：将外键约束转换为内联引用或多列引用
• 保留注释：在数据库提供注释的情况下将其纳入结果；SQLite 没有目录注释
• 索引文档：提取并记录数据库索引
• 数据库对象：在明确的 TOON 分区中保留受支持的枚举、类型、序列、同义词、触发器、例程、扩展、物化视图、程序包及其他特定于供应商的对象
• 跨平台：无需 CGO 即可为 Linux、macOS 和 Windows（amd64 和 arm64）构建
• DBML 适配器：将 DBML 文件（或标准输入）转换为相同的 TOON 格式
• 本地 MCP：为 MCP 客户端从只读 SQL 数据库和纯文本 SQL 转储中提取架构，并转换为精简的 TOON。

安装

从源代码安装

git clone https://github.com/kamil5b/db2toon.git
cd db2toon
CGO_ENABLED=0 go build -o output/db2toon ./cmd/db2toon
CGO_ENABLED=0 go build -o output/pg2toon ./cmd/pg2toon
CGO_ENABLED=0 go build -o output/dbml2toon ./cmd/dbml2toon

从发行版安装

从 releases page 下载适用于你平台的预编译二进制文件。

Go 包

此模块还提供公开的 Go API，供希望获取规范架构模型而非调用命令的调用方使用：

import (
    "context"
    "os"

    "github.com/kamil5b/db2toon"
)

func extract() error {
    db, err := db2toon.Extract(context.Background(), db2toon.Request{
        Dialect: "postgres",
        Dump:    "./schema.sql",
        Options: db2toon.Options{ExampleSample: 2},
    })
    if err != nil {
        return err
    }
    return db2toon.Encode(os.Stdout, db)
}

请在 Request.DB 和 Request.Dump 中恰好设置一个。转储内容会离线解析，绝不会执行。公开 API 会返回 *schema.Database，因此调用方可以先检查或转换模型，再进行编码。

用法

LLM 工具集成

构建并运行兼容 MCP 的 stdio 服务：

CGO_ENABLED=0 go build -o output/db2toon-mcp ./cmd/db2toon-mcp
./output/db2toon-mcp

该服务提供 db2toon.extract_schema。必填参数为 dialect（postgres、sqlite、duckdb、mysql、mariadb、cockroachdb、mssql、sqlserver 或 oracle）。 请在 db 和 dump 中恰好提供一个；可选的提取设置通过 options 对象传入。转储文件会离线解析，绝不会执行。该工具为只读工具，默认超时时间为 30 秒，响应大小限制为 4 MiB。需要更低的限制时，请设置 options.timeout 和 options.max_output_bytes。工具错误和结果中绝不会包含连接字符串。

基本用法

./db2toon postgres -db "postgresql://user:password@localhost/dbname"

# SQLite database file
./db2toon sqlite -db ./schema.db

# Plain-text SQL dump
./db2toon postgres -dump ./schema.sql
./db2toon sqlite -dump ./schema.sql
./db2toon mysql -dump ./schema.sql
./db2toon mssql -dump ./schema.sql
./db2toon oracle -dump ./schema.sql

# DuckDB database file (requires libduckdb at runtime)
./db2toon duckdb -db ./analytics.duckdb

# Microsoft SQL Server (defaults to dbo)
./db2toon mssql -db 'sqlserver://sa:password@localhost:1433?database=app&encrypt=disable'

# Oracle Database; the current schema is used unless -schema/-schemas is set.
# go-ora accepts an EZConnect-style URL.
./db2toon oracle -db 'oracle://app:password@localhost:1521/FREEPDB1'

# Compatibility command; PostgreSQL is selected automatically.
./pg2toon -db "postgresql://user:password@localhost/dbname"

# Convert DBML, either from a file or standard input.
./dbml2toon schema.dbml
cat schema.dbml | ./dbml2toon -out schema.toon

保存到文件

./db2toon postgres -db "postgresql://user:password@localhost/dbname" -out schema.toon

在 TOON 输出中为每个 PostgreSQL 表最多包含两行样例数据，并使用稳定的排序和可复现的样例种子：

./db2toon postgres -db "postgresql://user:password@localhost/dbname" \
  -example-sample=2 -example-sample-ordered=true -seed=42

默认值 -example-sample=0 会省略 @example 分区。

SQLite 和 DuckDB 也支持 -example-sample，但目前使用简单的 LIMIT 查询。-example-sample-ordered 和 -seed 目前仅对 PostgreSQL 生效。

使用以下设置可选择多个架构、包含分区表，并更改默认的 30 秒操作超时时间：

./db2toon postgres -db "$DATABASE_URL" -schema audit
./db2toon postgres -db "$DATABASE_URL" -schemas public,audit -include-partitioned -timeout 1m

# SQLite and DuckDB default to the `main` schema. SQL Server defaults to `dbo`.
# Oracle defaults to the session's CURRENT_SCHEMA.
./db2toon sqlite -db ./schema.db -schema main
./db2toon duckdb -db ./analytics.duckdb -schema analytics
./db2toon oracle -db 'oracle://app:password@localhost:1521/FREEPDB1' -schema APP

标志

• -db string：数据库连接 URL 或本地数据库路径；不能与 -dump 同时使用
• -dump string：纯文本 SQL 转储文件路径；不能与 -db 同时使用
• dialect：db2toon 支持 postgres、sqlite、duckdb、mysql、mariadb、cockroachdb、mssql、sqlserver 或 oracle；pg2toon 始终使用 PostgreSQL
• -out string：输出文件路径（可选，默认输出到标准输出）
• -schema string：要提取的单个模式（PostgreSQL 默认为 public，SQLite/DuckDB 默认为 main，SQL Server 默认为 dbo，Oracle 默认为会话的 CURRENT_SCHEMA）
• -schemas string：要提取的模式，以逗号分隔；不能与 -schema 同时使用
• -include-partitioned：包含 PostgreSQL 分区表
• -include-views：包含受支持的视图
• -exclude-tables string：要完全排除的表，以逗号分隔；接受 table 或 schema.table
• -exclude-example-tables string：要从 @example 采样中排除的表，以逗号分隔
• -exclude-example-fields string：要从示例中排除的限定字段，以逗号分隔，例如 public.users.password_hash
• -example-sample int：每张表包含的示例行数（默认为 0）
• -example-sample-ordered：通过确定性排序选择示例行（PostgreSQL；默认为 false）
• -seed int：用于可复现 PostgreSQL 示例选择的种子（默认为 0；目前 SQLite/DuckDB 会忽略此项）
• -timeout duration：连接和提取超时（默认为 30s）

转储模式支持 PostgreSQL、SQLite、DuckDB、MySQL/MariaDB、CockroachDB、SQL Server 和 Oracle 的纯文本 SQL 导出。解析常见的表、列、约束、索引、注释和数量受限的 INSERT 示例，但不会执行转储内容。PostgreSQL 会保留原生枚举、序列、视图、函数、存储过程和触发器，包括美元引用的例程主体。MySQL/MariaDB 支持基于 DELIMITER 的例程和触发器声明。SQL Server 和 Oracle 会保留受支持的视图、函数、存储过程、触发器、序列、类型、同义词和选定的厂商对象。复杂的厂商专属 PL/SQL/T-SQL 主体会尽可能保留为语句文本；不受支持的声明会被忽略，而不会执行。

输出格式

Toon 格式提供清晰易读的模式定义：

@database app {dialect=postgres}

[users]
# User accounts table

  id int {pk}
  email varchar {req}
  name varchar
  created_at timestamptz {req}

@indices
  idx_email: ON users USING btree (email)

@example[2]{id,email,name,created_at}:
  1,[email protected],Alice,2026-01-10T09:00:00Z
  2,[email protected],Bob,2026-01-11T10:30:00Z

[posts]
# Blog posts

  id int {pk}
  user_id int {req} -> users(id)
  title varchar {req}
  content text
  published_at timestamptz

[comments]
# Post comments

  id int {pk}
  post_id int {req} -> posts(id)
  user_id int {req} -> users(id)
  content text {req}
  created_at timestamptz {req}

格式元素

• @database name {dialect=dialect}：源数据库元数据。实时连接会从连接字符串中提取名称；转储模式使用不带扩展名的转储文件名。
• [TableName]：表定义
• # comment：表或列注释
• name type {tags}：带可选标签的列定义
  • {pk}：主键
  • {req}：必需（NOT NULL）
  • 多个标签：{pk,req}
• -> table(column)：外键引用（单列时内联显示）
• @indices：数据库索引部分
• @enum：枚举类型值
• @type：用户定义类型元数据
• @sequence：序列配置
• @synonym：对象别名
• @routine：函数或存储过程元数据，以及可用时的定义
• @triggers：表触发器元数据
• @objects：厂商专属模式对象，包括 Oracle 物化视图、程序包、分区表、调度程序作业和数据库链接
• @example[n]{columns}:：该表最多 n 条采样行
• // comment：内联列注释

Oracle 覆盖范围

Oracle 提取使用用户可见的 ALL_* 目录视图，因此输出仅限已连接账户可查看的对象。支持表、视图、列和注释、主键／唯一键／外键／检查约束、独立索引、触发器、独立函数和过程、用户序列、对象类型、同义词、物化视图、程序包／程序包主体、分区表标记、调度程序作业和数据库链接。Oracle 生成的标识序列和系统生成的 NOT NULL 检查约束会被忽略，因为列模型已包含相关信息。

程序包／类型源代码主体、物化视图刷新设置、详细分区定义、授权／角色、VPD 策略、表空间／存储详情、专用空间／域索引选项以及 Oracle SQL 转储解析尚未纳入规范模型。

Microsoft SQL Server 覆盖范围

Microsoft SQL Server 提取使用 sys.* 目录视图；除非提供 -schema 或 -schemas，否则默认使用 dbo 架构。支持表和视图、列和 MS_Description 注释、默认值、标识列／计算列、主键／唯一键／外键／检查约束、独立索引、触发器、函数／过程、别名类型／表类型、序列、同义词和示例行。视图定义和供应商特定的架构对象会在适用时输出到 TOON 对象区段中。

不支持解析 SQL Server 转储。当前模型也尚未纳入分区函数／方案、文件组、时态表或内存优化表设置、图表、全文／空间／XML 索引内部信息、权限、说明以外的扩展属性、Agent 作业或服务器级对象。

要求

• Go 1.26.0 或更高版本
• PostgreSQL 9.4+（用于 JSON 聚合函数）、SQLite、DuckDB、MySQL/MariaDB、CockroachDB、Microsoft SQL Server 2022+ 或 Oracle Database
• 有效的数据库连接字符串或本地数据库路径
• DuckDB 还要求运行时提供兼容的 libduckdb 共享库
• Oracle 使用纯 Go go-ora 驱动程序，无需 Oracle Instant Client 或 CGO

许可证

MIT