{
  "markdown": "# db2toon\n\nA CLI tool that converts database schemas into the Toon schema definition format.\n\n## Overview\n\n`db2toon` connects to a database and extracts schema information (tables, columns, types, constraints, indexes, routines, triggers, and examples), then converts it into the human-readable Toon format for database design documentation and visualization. PostgreSQL, SQLite, DuckDB, MySQL/MariaDB, CockroachDB, Microsoft SQL Server, and Oracle are supported. `pg2toon` remains a PostgreSQL compatibility command.\n\n## Features\n\n- **Schema Extraction**: Automatically extracts tables, columns, and metadata from PostgreSQL, SQLite, DuckDB, MySQL/MariaDB, CockroachDB, Microsoft SQL Server, and Oracle\n- **Type Normalization**: Simplifies PostgreSQL types (e.g., `character varying` → `varchar`)\n- **Relationship Mapping**: Converts foreign key constraints to inline references or multi-column references\n- **Comment Preservation**: Includes comments where the database exposes them; SQLite does not have catalog comments\n- **Index Documentation**: Extracts and documents database indexes\n- **Database Objects**: Preserves supported enums, types, sequences, synonyms,\n  triggers, routines, extensions, materialized views, packages, and other\n  vendor-specific objects in explicit TOON sections\n- **Cross-Platform**: Builds without CGO for Linux, macOS, and Windows (amd64 and arm64)\n- **DBML Adapter**: Converts DBML files (or standard input) into the same TOON format\n\n## Installation\n\n### From Source\n\n```bash\ngit clone https://github.com/kamil5b/db2toon.git\ncd db2toon\nCGO_ENABLED=0 go build -o output/db2toon ./cmd/db2toon\nCGO_ENABLED=0 go build -o output/pg2toon ./cmd/pg2toon\nCGO_ENABLED=0 go build -o output/dbml2toon ./cmd/dbml2toon\n```\n\n### From Releases\n\nDownload pre-built binaries from the [releases page](https://github.com/kamil5b/db2toon/releases) for your platform.\n\n### Go package\n\nThe module also exposes a public Go API for callers that want the canonical\nschema model instead of invoking a command:\n\n```go\nimport (\n    \"context\"\n    \"os\"\n\n    \"github.com/kamil5b/db2toon\"\n)\n\nfunc extract() error {\n    db, err := db2toon.Extract(context.Background(), db2toon.Request{\n        Dialect: \"postgres\",\n        Dump:    \"./schema.sql\",\n        Options: db2toon.Options{ExampleSample: 2},\n    })\n    if err != nil {\n        return err\n    }\n    return db2toon.Encode(os.Stdout, db)\n}\n```\n\nSet exactly one of `Request.DB` or `Request.Dump`. Dump contents are parsed\noffline and never executed. The public API returns `*schema.Database`, so\ncallers may inspect or transform the model before encoding it.\n\n## Usage\n\n### LLM tool integration\n\nBuild and run the MCP-compatible stdio server:\n\n```bash\nCGO_ENABLED=0 go build -o output/db2toon-mcp ./cmd/db2toon-mcp\n./output/db2toon-mcp\n```\n\nThe server exposes `db2toon.extract_schema`. Its required argument is\n`dialect` (`postgres`, `sqlite`, `duckdb`, `mysql`, `mariadb`, `cockroachdb`, `mssql`, `sqlserver`, or `oracle`).\nProvide exactly one of `db` or `dump`; optional extraction settings are\nsupplied in an `options` object. Dump files are parsed offline and never\nexecuted. The tool is read-only, uses a 30-second default timeout, and limits\nresponses to 4 MiB. Set `options.timeout` and `options.max_output_bytes` to\nlower limits when needed. Connection strings are never included in tool errors\nor results.\n\n### Basic Usage\n\n```bash\n./db2toon postgres -db \"postgresql://user:password@localhost/dbname\"\n\n# SQLite database file\n./db2toon sqlite -db ./schema.db\n\n# Plain-text SQL dump\n./db2toon postgres -dump ./schema.sql\n./db2toon sqlite -dump ./schema.sql\n./db2toon mysql -dump ./schema.sql\n./db2toon mssql -dump ./schema.sql\n./db2toon oracle -dump ./schema.sql\n\n# DuckDB database file (requires libduckdb at runtime)\n./db2toon duckdb -db ./analytics.duckdb\n\n# Microsoft SQL Server (defaults to dbo)\n./db2toon mssql -db 'sqlserver://sa:password@localhost:1433?database=app&encrypt=disable'\n\n# Oracle Database; the current schema is used unless -schema/-schemas is set.\n# go-ora accepts an EZConnect-style URL.\n./db2toon oracle -db 'oracle://app:password@localhost:1521/FREEPDB1'\n\n# Compatibility command; PostgreSQL is selected automatically.\n./pg2toon -db \"postgresql://user:password@localhost/dbname\"\n\n# Convert DBML, either from a file or standard input.\n./dbml2toon schema.dbml\ncat schema.dbml | ./dbml2toon -out schema.toon\n```\n\n### Save to File\n\n```bash\n./db2toon postgres -db \"postgresql://user:password@localhost/dbname\" -out schema.toon\n```\n\nInclude up to two sample rows per PostgreSQL table in the TOON output, using a\nstable ordering and a reproducible sample seed:\n\n```bash\n./db2toon postgres -db \"postgresql://user:password@localhost/dbname\" \\\n  -example-sample=2 -example-sample-ordered=true -seed=42\n```\n\nThe default `-example-sample=0` omits `@example` sections.\n\nSQLite and DuckDB also support `-example-sample`, but currently use a simple\n`LIMIT` query. `-example-sample-ordered` and `-seed` are currently effective\nonly for PostgreSQL.\n\nSelect multiple schemas, include partitioned tables, and change the default\n30-second operation timeout with:\n\n```bash\n./db2toon postgres -db \"$DATABASE_URL\" -schema audit\n./db2toon postgres -db \"$DATABASE_URL\" -schemas public,audit -include-partitioned -timeout 1m\n\n# SQLite and DuckDB default to the `main` schema. SQL Server defaults to `dbo`.\n# Oracle defaults to the session's CURRENT_SCHEMA.\n./db2toon sqlite -db ./schema.db -schema main\n./db2toon duckdb -db ./analytics.duckdb -schema analytics\n./db2toon oracle -db 'oracle://app:password@localhost:1521/FREEPDB1' -schema APP\n```\n\n### Flags\n\n- `-db string`: Database connection URL or local database path; mutually exclusive with `-dump`\n- `-dump string`: Plain-text SQL dump path; mutually exclusive with `-db`\n- `dialect`: `postgres`, `sqlite`, `duckdb`, `mysql`, `mariadb`, `cockroachdb`, `mssql`, `sqlserver`, or `oracle` for `db2toon`; `pg2toon` always uses PostgreSQL\n- `-out string`: Output file path (optional, defaults to stdout)\n- `-schema string`: A single schema to extract (defaults to `public` for PostgreSQL, `main` for SQLite/DuckDB, `dbo` for SQL Server, and the session `CURRENT_SCHEMA` for Oracle)\n- `-schemas string`: Comma-separated schemas to extract; cannot be combined with `-schema`\n- `-include-partitioned`: Include PostgreSQL partitioned tables\n- `-include-views`: Include supported views\n- `-exclude-tables string`: Comma-separated tables to exclude entirely; accepts `table` or `schema.table`\n- `-exclude-example-tables string`: Comma-separated tables to exclude from `@example` sampling\n- `-exclude-example-fields string`: Comma-separated qualified fields to exclude from examples, such as `public.users.password_hash`\n- `-example-sample int`: Number of sample rows to include per table (defaults to `0`)\n- `-example-sample-ordered`: Select sample rows using deterministic ordering for PostgreSQL (defaults to `false`)\n- `-seed int`: Seed for reproducible PostgreSQL sample selection (defaults to `0`; currently ignored by SQLite/DuckDB)\n- `-timeout duration`: Connection and extraction timeout (defaults to `30s`)\n\nDump mode supports plain-text SQL exports for PostgreSQL, SQLite, DuckDB,\nMySQL/MariaDB, CockroachDB, SQL Server, and Oracle. Common tables, columns, constraints,\nindexes, comments, and bounded `INSERT` examples are parsed without executing\nthe dump. PostgreSQL retains native enums, sequences, views, functions,\nprocedures, and triggers, including dollar-quoted routine bodies. MySQL/MariaDB\nsupports `DELIMITER`-based routine and trigger declarations. SQL Server and\nOracle retain supported views, functions, procedures, triggers, sequences,\ntypes, synonyms, and selected vendor objects. Complex vendor-specific PL/SQL/\nT-SQL bodies are preserved as available statement text; unsupported declarations\nare ignored rather than executed.\n\n## Output Format\n\nThe Toon format provides a clean, human-readable schema definition:\n\n```\n@database app {dialect=postgres}\n\n[users]\n# User accounts table\n\n  id int {pk}\n  email varchar {req}\n  name varchar\n  created_at timestamptz {req}\n\n@indices\n  idx_email: ON users USING btree (email)\n\n@example[2]{id,email,name,created_at}:\n  1,alice@example.com,Alice,2026-01-10T09:00:00Z\n  2,bob@example.com,Bob,2026-01-11T10:30:00Z\n\n[posts]\n# Blog posts\n\n  id int {pk}\n  user_id int {req} -> users(id)\n  title varchar {req}\n  content text\n  published_at timestamptz\n\n[comments]\n# Post comments\n\n  id int {pk}\n  post_id int {req} -> posts(id)\n  user_id int {req} -> users(id)\n  content text {req}\n  created_at timestamptz {req}\n```\n\n### Format Elements\n\n- `@database name {dialect=dialect}`: Source database metadata. Live connections derive the name from the connection string; dump mode uses the dump filename without its extension.\n- `[TableName]`: Table definition\n- `# comment`: Table or column comments\n- `name type {tags}`: Column definition with optional tags\n  - `{pk}`: Primary key\n  - `{req}`: Required (NOT NULL)\n  - Multiple tags: `{pk,req}`\n- `-> table(column)`: Foreign key reference (inline for single columns)\n- `@indices`: Section for database indexes\n- `@enum`: Enumerated type values\n- `@type`: User-defined type metadata\n- `@sequence`: Sequence configuration\n- `@synonym`: Alternate object name\n- `@routine`: Function or procedure metadata and definition where available\n- `@triggers`: Table trigger metadata\n- `@objects`: Vendor-specific schema objects, including Oracle materialized\n  views, packages, partitioned tables, scheduler jobs, and database links\n- `@example[n]{columns}:`: Up to `n` sampled rows from the table\n- `// comment`: Inline column comment\n\n### Oracle coverage\n\nOracle extraction uses user-visible `ALL_*` catalog views, so the output is\nlimited to objects the connected account can inspect. It supports tables,\nviews, columns and comments, primary/unique/foreign-key/check constraints,\nindependent indexes, triggers, standalone functions and procedures, user\nsequences, object types, synonyms, materialized views, packages/package bodies,\npartitioned-table markers, scheduler jobs, and database links. Oracle-generated\nidentity sequences and system-generated `NOT NULL` checks are omitted because\ntheir information is already represented by the column model.\n\nPackage/type source bodies, materialized-view refresh settings, detailed\npartition definitions, grants/roles, VPD policies, tablespace/storage details,\nspecialized spatial/domain index options, and Oracle SQL dump parsing are not\nyet represented in the canonical model.\n\n### Microsoft SQL Server coverage\n\nMicrosoft SQL Server extraction uses `sys.*` catalog views and defaults to the\n`dbo` schema unless `-schema` or `-schemas` is supplied. It supports tables and\nviews, columns and `MS_Description` comments, defaults, identity/computed\ncolumns, primary/unique/foreign-key/check constraints, independent indexes,\ntriggers, functions/procedures, alias/table types, sequences, synonyms, and\nsample rows. View definitions and vendor-specific schema objects are emitted in\nthe TOON object sections where applicable.\n\nSQL Server dump parsing is not supported. The current model also does not yet\nrepresent partition functions/schemes, filegroups, temporal or memory-optimized\ntable settings, graph tables, full-text/spatial/XML index internals, permissions,\nextended properties other than descriptions, Agent jobs, or server-level objects.\n\n## Requirements\n\n- Go 1.26.0 or later\n- PostgreSQL 9.4+ (for JSON aggregation functions), SQLite, DuckDB, MySQL/MariaDB, CockroachDB, Microsoft SQL Server 2022+, or Oracle Database\n- A valid database connection string or local database path\n- DuckDB also requires a compatible `libduckdb` shared library at runtime\n- Oracle uses the pure-Go `go-ora` driver and does not require Oracle Instant Client or CGO\n\n## License\n\nMIT\n",
  "bytes": 11821,
  "sha": "40450f0a336053f03c750fa25dec1eca016818a6ff9b7bd3301e5fb61a0df2f1",
  "repo_slug": "kamil5b/db2toon",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kamil5b_db2toon_mcp_0eaf0a19/readme"
}