A CLI toolset for working with DBML (Database Markup Language) files and databases.
Blog post: https://www.tqdev.com/2026-dbml-database-schema-plain-text-genai/
- Convert DSN (or SQL file, see below) to DBML
- Convert DBML to SQL
- Convert DBML to Graphviz DOT diagrams
- Compare DSN/DBML and create SQL migration
go install dbml-tools@latestOr build from source:
git clone ...
cd dbml-tools
go build -o dbml-tools .| Command | Description |
|---|---|
check <file> |
Check a DBML file for parse/semantic errors |
todbml [options] <dsn> |
Connect to a database and print its schema as DBML |
tosql <file> |
Generate CREATE TABLE SQL from a DBML file |
todot <file> |
Generate Graphviz DOT diagram from a DBML file |
migrate [options] <old> <new> |
Generate migration SQL from schema diff |
| Flag | Description |
|---|---|
--normalize |
Map column types to database-agnostic DBML equivalents |
--data |
Also export row data as DBML records blocks |
--exclude p,... |
Comma-separated table name patterns to exclude (supports * glob) |
--include p,... |
Comma-separated table name patterns to include (all others excluded) |
| Flag | Description |
|---|---|
--exclude p,... |
Comma-separated table name patterns to exclude |
--include p,... |
Comma-separated table name patterns to include |
| Command | Description |
|---|---|
lex <file> |
Tokenize a DBML file and output lexer JSON |
parse <file> |
Parse a DBML file and output AST JSON |
interpret <file> |
Interpret a DBML file and output database schema JSON |
The SQL dialect used by tosql and migrate is determined in this order:
- DSN auto-detect (
migrateonly) — inferred from the connection string scheme database_typeProject setting — read from the DBML file- Default — MariaDB when none of the above yields a specific dialect
Project {
database_type: 'PostgreSQL' // or 'MariaDB', 'SQLite'
// todbml --normalize produces e.g. 'MariaDB normalized'
}
todbml writes the database_type setting automatically based on the database
engine it connects to, even when --normalize is used. This means tosql and
migrate can always auto-detect the dialect from the DBML file or the DSN.
DBML column types flow through the toolchain in one of two modes:
Native (default for todbml)
Column types are preserved exactly as they appear in the source database (e.g.
character varying(255), bytea, mediumtext). The database_type Project
setting records which engine they came from, so downstream tools (tosql,
migrate) emit the correct SQL syntax.
Normalized (todbml --normalize)
Type names are mapped to canonical DBML equivalents (e.g. integer → int,
character varying(255) → varchar(255), bytea → binary). The
database_type is set to '<engine> normalized' (e.g. 'MariaDB normalized')
so that downstream tools know both the source engine and that types are
normalized. Unrecognised or vendor-specific types (e.g. geometry) are copied
verbatim. This mode produces database-agnostic DBML.
Connects to a live database, reads its schema, and outputs DBML to stdout. By
default column types are preserved as-is from the database and a database_type
Project setting is written (e.g. 'PostgreSQL').
Pass --normalize to map types to database-agnostic canonical DBML equivalents
(e.g. character varying → varchar, bytea → binary).
Supported engines: MariaDB, PostgreSQL, SQLite.
# MariaDB (native types)
dbml-tools todbml mariadb://user:pass@host:3306/mydb
# PostgreSQL (defaults to schema "public"; override with ?schema=)
dbml-tools todbml postgres://user:pass@host:5432/mydb
dbml-tools todbml postgres://user:pass@host:5432/mydb?schema=myschema
# SQLite
dbml-tools todbml sqlite:///path/to/file.db
# Normalized / database-agnostic output
dbml-tools todbml --normalize postgres://user:pass@host:5432/mydb
# Save to a file
dbml-tools todbml sqlite:///path/to/file.db > schema.dbml
# Exclude specific tables (exact name or glob pattern, comma-separated)
dbml-tools todbml --exclude 'spatial_ref_sys,geography_columns' postgres://...
dbml-tools todbml --exclude 'tmp_*,_*' mariadb://...
# Include only specific tables
dbml-tools todbml --include 'orders,order_*' postgres://...
# Export schema together with row data
dbml-tools todbml --data mariadb://user:pass@host:3306/mydbNote: flags must be placed before the DSN argument.
--data also fetches all rows from each table and emits them as DBML
records blocks. Binary column types (binary, varbinary, blob, bytea,
bit, geometry, point, etc.) are hex-encoded using X'...' notation.
Filter patterns support * (any sequence of characters) and ? (any single
character), matched case-insensitively. Comma-separate multiple patterns.
The public schema prefix is omitted from PostgreSQL output since it is the
default schema.
todbml reads from a live database, so to convert a SQL file (for instance a
mysqldump or pg_dump schema dump) load it into a throwaway database first.
With Docker this takes a few commands and no local database install.
MariaDB / MySQL:
docker run -d --rm --name dbml-tmp -e MARIADB_ROOT_PASSWORD=pass -e MARIADB_DATABASE=mydb -p 3306:3306 mariadb:11
until docker exec dbml-tmp mariadb-admin ping -h 127.0.0.1 -uroot -ppass --silent >/dev/null 2>&1; do sleep 1; done
docker exec -i dbml-tmp mariadb -uroot -ppass mydb < schema.sql
dbml-tools todbml mariadb://root:pass@127.0.0.1:3306/mydb > schema.dbml
docker stop dbml-tmpPostgreSQL:
docker run -d --rm --name dbml-tmp -e POSTGRES_PASSWORD=pass -e POSTGRES_DB=mydb -p 5432:5432 postgres:17
until docker exec dbml-tmp pg_isready -h 127.0.0.1 -U postgres -q; do sleep 1; done
docker exec -i dbml-tmp psql -q -v ON_ERROR_STOP=1 -U postgres mydb < schema.sql
dbml-tools todbml "postgres://postgres:pass@127.0.0.1:5432/mydb?sslmode=disable" > schema.dbml
docker stop dbml-tmpThe wait loop checks over TCP on purpose: the image's init phase only listens on
a local socket, so the loop ends once the server is really up. If port 3306 or
5432 is already taken, map another host port (e.g. -p 33306:3306) and use it
in the DSN. Pick an image version that matches the dump if it uses newer syntax.
SQLite needs no container, the sqlite3 CLI is enough:
sqlite3 schema.db < schema.sql
dbml-tools todbml sqlite:///path/to/schema.db > schema.dbmlChecks a DBML file for syntax and semantic errors.
dbml-tools check schema.dbmlGenerates a CREATE TABLE SQL script from a DBML file. The SQL dialect is
determined by the database_type Project setting in the file. Foreign keys are
emitted as ALTER TABLE ... ADD CONSTRAINT statements, carrying the delete:
and update: referential actions from the Ref declaration. SQLite cannot add
constraints with ALTER TABLE, so for SQLite they are declared inside
CREATE TABLE; SQLite only enforces them on connections that run
PRAGMA foreign_keys = ON. If the DBML contains records blocks (from
todbml --data), matching INSERT INTO statements are generated after each
table. For SQLite the inserts follow all tables in a single transaction with
PRAGMA defer_foreign_keys = ON, so the script also loads with foreign keys
enforced. A schema-qualified name such as
Table my_schema.my_table is emitted as two quoted identifiers, so the table
is created in my_schema rather than as a table with a dot in its name.
Each entry of an indexes { } block becomes a CREATE [UNIQUE] INDEX after its
table, with columns and backtick expressions in order, and type: as
USING <type> (SQLite has a single index type, MariaDB supports btree and
hash, and does not support expression indexes, which are left as a comment).
An index marked pk becomes the table's PRIMARY KEY, under its name: where
the dialect allows. An unnamed index is named <table>_<columns>_idx, as
PostgreSQL would. Index names are scoped to the table in MariaDB, but shared
with tables and other indexes across a schema in PostgreSQL and SQLite, so a
name used more than once in its scope is prefixed with <table>_. In MariaDB
that scope includes the key name a unique column takes, which is its own name. Names
are cut to the length the database takes: PostgreSQL keeps 63 bytes and MariaDB
64 characters.
dbml-tools tosql schema.dbmlGenerates a Graphviz DOT diagram of the database schema. Tables are rendered with columns, types, PK/FK markers, and constraint badges. Foreign key relationships are drawn as orthogonal edges with crow's foot notation.
# Output DOT to stdout
dbml-tools todot schema.dbml
# Generate a PDF
dbml-tools todot schema.dbml | dot -Tpdf -o schema.pdf
# Generate a PNG
dbml-tools todot schema.dbml | dot -Tpng -o schema.png
# Generate an SVG
dbml-tools todot schema.dbml | dot -Tsvg -o schema.svgRequires Graphviz (dot) to be installed for
rendering.
Compares two schemas and outputs the SQL statements needed to migrate from the
first to the second. Either argument can be a DBML file path or a live database
connection string. The dialect is auto-detected from any DSN present or from the
database_type Project setting in DBML files.
# Diff two DBML files (dry-run by default)
dbml-tools migrate old.dbml new.dbml
# Compare a DBML file against a live database
dbml-tools migrate schema.dbml postgres://user:pass@host/db
# Compare two live databases
dbml-tools migrate mariadb://host/db1 mariadb://host/db2
# Exclude system or extension tables from the comparison
dbml-tools migrate --exclude 'spatial_ref_sys,geography_columns' old.dbml postgres://...Normalized DBML support: when either schema has a database_type ending in
" normalized" (as produced by todbml --normalize), type names are normalized
before comparison. This means equivalent types with different names (e.g.
binary vs blob, text vs longtext) are correctly recognized as identical
and do not produce spurious ALTER statements.
Indexes are matched by the name tosql would give them, prefix included, so a
database created from a DBML file compares equal to it. A new or changed index
is created after the column changes, and a dropped or changed one is dropped
before them. Index expressions are compared without casts, parentheses and
whitespace, as databases report them in their own form (PostgreSQL reads
lower(email) back as lower((email)::text)). A change of primary key drops
the old key and adds the new one (SQLite needs a table rebuild for that, so it
gets a comment). In PostgreSQL a renamed primary key is renamed, as an unnamed
one is named <table>_pkey.
Column types are compared under the name the database reports them by, so
int matches PostgreSQL's integer, and bigint and boolean match
MariaDB's bigint(20) and tinyint(1). When nothing differs, migrate writes
nothing to stdout and -- No changes detected to stderr.
The --exclude / --include filter flags work the same as for todbml and
apply to both schema sides.
What is introspected:
| Feature | MariaDB | PostgreSQL | SQLite |
|---|---|---|---|
| Tables & columns | ✓ | ✓ | ✓ |
| Column types | ✓ | ✓ | ✓ |
| NOT NULL | ✓ | ✓ | ✓ |
| Default values | ✓ | ✓ | ✓ |
| Primary keys | ✓ | ✓ | ✓ |
| Unique constraints | ✓ | ✓ | ✓ |
| Indexes | ✓ | ✓ | ✓ |
| Foreign keys | ✓ | ✓ | ✓ |
| Check constraints | ✓ | ✓ | — |
| Enums | ✓ (inline) | ✓ (types) | — |
| Table/column comments | ✓ | ✓ | — |
The SQL queries used for introspection live in sql/ and use :schema as
a named parameter so they can be run independently against any compatible
client.