@dbml/core

@dbml/core is the engine that powers Holistics’ Database Markup Language (DBML) tooling, including dbdiagram.io and dbdocs.io. It parses DBML source into a normalized in-memory schema model — tables, fields, references, enums, indexes, and table groups — and exports that model back out as DBML, JSON, or dialect-specific SQL DDL for PostgreSQL, MySQL, MSSQL, Oracle, and Snowflake.

Beyond DBML parsing, the package also imports existing SQL schemas by running vendor SQL through hand-written ANTLR grammars per dialect, normalizing the result into the same schema model so it can be re-exported as DBML or translated into a different SQL dialect. A documented feature-support matrix tracks exactly which SQL constructs (primary keys, foreign keys, checks, indexes, auto-increment styles, and more) each dialect parser currently handles.

What You Get

• A DBML parser that builds a normalized schema model (tables, fields, refs, enums, indexes, table groups, notes) from DBML source
• SQL-to-DBML importers for PostgreSQL, MySQL, MSSQL, Oracle, and Snowflake backed by dedicated ANTLR grammars per dialect
• Exporters that render the same schema model back out as DBML, JSON, or dialect-specific SQL DDL
• A documented per-dialect feature-support matrix showing exactly which SQL constructs each importer/exporter currently handles

Common Use Cases

• Powering visual schema tools like dbdiagram.io and documentation tools like dbdocs.io on top of a shared DBML core
• Converting an existing PostgreSQL/MySQL/MSSQL/Oracle/Snowflake schema into DBML for documentation or version control
• Translating a schema between SQL dialects by importing from one and exporting to another
• Embedding DBML parsing and generation in a custom CLI, editor plugin, or code-generation pipeline

Under The Hood

Architecture The package follows a text-in, text-out pipeline with a normalized object model at its center: parse/Parser.js dispatches DBML source to the companion @dbml/parse package (or vendor SQL to per-dialect ANTLR grammars under parse/ANTLR), the resulting AST is normalized into the model_structure/ object graph (Database → Schema → Table → Field, plus Ref, Enum, Index, TableGroup, and TablePartial), and the export/ directory holds one exporter per target format (DbmlExporter, JsonExporter, MysqlExporter, PostgresExporter, OracleExporter, SqlServerExporter) that all walk the same normalized model. This layering means adding a new SQL dialect is largely a matter of adding a grammar plus an importer/exporter module without touching the core model.

Tech Stack A mixed TypeScript/JavaScript codebase (the model and export layers are TypeScript; the ANTLR-generated dialect parsers remain legacy JavaScript) built with Vite into dual ESM/CJS bundles, tested with Vitest, and orchestrated as one package inside a Lerna/Yarn-workspaces monorepo alongside @dbml/parse, @dbml/cli, and @dbml/connector. Dependencies include antlr4 for grammar-driven parsing, lodash/lodash-es and parsimmon for utilities and combinator parsing, and luxon/pluralize for value formatting.

Code Quality Sixteen Vitest spec files drive a large fixture-based regression suite (hundreds of paired .in./.out. SQL, DBML, and JSON fixtures across the importer, exporter, parser, and model-structure test folders), and CI runs this suite against live PostgreSQL and MSSQL containers rather than mocks. A dedicated ESLint flat config (@typescript-eslint plus @stylistic) runs in its own lint workflow, and the TypeScript layer compiles under strict: true, though several legacy modules under model_structure/ and parse/ still predate the TypeScript migration and lean on loose typing. Errors surface through a dedicated CompilerError type rather than being swallowed.

What Makes It Unique DBML’s differentiator is bidirectional translation across five SQL dialects through one shared schema model — parsing arbitrary vendor DDL into a normalized representation and re-emitting it as DBML or a different dialect’s DDL, backed by a published feature-support matrix that documents exactly which constructs each dialect parser handles. That breadth of dialect coverage, plus the visual tooling ecosystem (dbdiagram.io, dbdocs.io) built on top of it, is a practical differentiator even though schema DSLs and SQL translators are not conceptually new.