How to Import DBML into DrawDB: A Complete Guide

DrawDB converts DBML text into visual diagrams using the fromDBML parser located in src/utils/importFrom/dbml.js, which updates the central diagram store via the useDiagram hook.

DrawDB is an open-source database diagramming tool that supports importing Database Markup Language (DBML) to quickly generate visual schemas. Understanding how to import DBML into DrawDB allows you to migrate existing database definitions into the editor without manual reconstruction. The import pipeline leverages a dedicated parser that transforms DBML text into DrawDB's internal state structure.

Understanding the DBML Import Architecture

The import system relies on a bidirectional mapping between DBML text and DrawDB's internal diagram model. When you initiate an import, the application calls fromDBML(src, database) from src/utils/importFrom/dbml.js, which utilizes the dbml-parser library to parse table definitions, columns, relationships, and notes.

The parsed result is a plain JavaScript object representing the diagram structure. This object passes to setImportData within the ImportDiagram component, which commits the data to the Redux-style store managed by useDiagram in src/hooks/useDiagram.js. The UI then re-renders to display the imported tables and relationships.

Importing DBML Through the User Interface

Opening the Import Dialog

To start the import process, click Import → DBML in the editor header. This opens the modal defined in src/components/EditorHeader/Modal/ImportDiagram.jsx. The interface provides two input methods:

• Paste raw DBML text directly into the text area.
• Upload a .dbml file using the file picker, which triggers the loadDBMLData function.

Parsing and Loading the Schema

Once you confirm the import, the component invokes fromDBML to convert the source text into diagram objects. The function maps DBML constructs—such as Table blocks, column types, and ref relationships—to their corresponding DrawDB internal representations. After parsing, the store update replaces the current canvas state with the imported schema, instantly rendering the visual tables and connection lines.

Programmatic DBML Import

You can also import DBML programmatically within custom scripts or extensions. The fromDBML function is pure and safe to call outside the React component tree, making it suitable for headless imports or automated migrations.

// Programmatically import DBML into an existing DrawDB instance
import { fromDBML } from "./utils/importFrom/dbml";
import { useDiagram } from "./hooks/useDiagram";

const dbmlString = `
Table users {
  id int [pk]
  name varchar
}
Table posts {
  id int [pk]
  user_id int [ref: > users.id]
  title varchar
}
`;

function importDbmlIntoDiagram() {
  const { setDiagram } = useDiagram();
  const diagram = fromDBML(dbmlString, /* optional base database */);
  setDiagram(diagram); // Replaces current diagram with imported schema
}

This approach is useful when integrating DrawDB into larger applications where DBML definitions arrive from APIs or version control systems.

Key Files in the Import Pipeline

Understanding the source code layout helps when extending or debugging the import functionality:

• src/utils/importFrom/dbml.js – Contains the fromDBML parser that transforms DBML text into DrawDB's diagram structure.
• src/utils/exportAs/dbml.js – Houses the toDBML serializer for the reverse operation, converting diagrams back to DBML text.
• src/components/EditorHeader/Modal/ImportDiagram.jsx – The React component handling file reading and UI interactions for imports.
• src/data/constants.js – Defines supported import types, including the DBML format identifier.

Both fromDBML and toDBML are pure functions, ensuring they can be invoked from any context—whether from the Import dialog, the DBML side-panel, or external automation scripts.

Editing and Syncing DBML After Import

After importing, you can view or modify the DBML representation using the built-in DBML Editor side panel. This component, located at src/components/EditorSidePanel/DBMLEditor.jsx, displays the current diagram as DBML text using the toDBML function from src/utils/exportAs/dbml.js.

The editor maintains bidirectional sync: changes in the visual diagram update the DBML text, and edits to the DBML text can re-import into the visual state. To export the current diagram as DBML programmatically:

import { toDBML } from "./utils/exportAs/dbml";
import { useDiagram } from "./hooks/useDiagram";

function exportCurrentDbml() {
  const { diagram } = useDiagram();
  const dbmlText = toDBML(diagram);
  console.log("Current diagram as DBML:\n", dbmlText);
}

Summary

• Import via UI: Click Import → DBML in src/components/EditorHeader/Modal/ImportDiagram.jsx, paste text or upload a file, and let fromDBML parse the schema.
• Core Parser: The fromDBML function in src/utils/importFrom/dbml.js uses the dbml-parser library to map DBML constructs to DrawDB objects.
• State Management: Parsed diagrams update the store via useDiagram, instantly rendering tables and relationships on the canvas.
• Bidirectional Support: Use toDBML in src/utils/exportAs/dbml.js to serialize diagrams back to DBML text for the side-panel editor or external export.
• Pure Functions: Both import and export utilities are stateless, making them safe for programmatic use in scripts and custom integrations.

Frequently Asked Questions

What file formats does DrawDB support for DBML import?

DrawDB accepts raw DBML text pasted into the import dialog or .dbml files uploaded through the file picker in src/components/EditorHeader/Modal/ImportDiagram.jsx. The system does not currently support importing DBML embedded within other file types like Markdown or SQL dumps.

Can I import DBML programmatically without using the React UI?

Yes. The fromDBML function exported from src/utils/importFrom/dbml.js is a pure function that accepts a DBML string and an optional database parameter. You can call it from Node.js scripts or automation tools to generate diagram objects, then pass them to setDiagram from the useDiagram hook to update the editor state.

How does DrawDB handle DBML relationships and references?

During parsing, fromDBML processes DBML ref statements (such as [ref: > users.id]) and converts them into DrawDB's internal relationship objects. These appear as connection lines between tables in the visual editor, preserving cardinality and foreign key constraints defined in the DBML source.

Is it possible to edit DBML after importing into DrawDB?

Yes. After import, open the DBML Editor side panel (src/components/EditorSidePanel/DBMLEditor.jsx) to view the live DBML representation. The panel uses toDBML to serialize the current diagram state. You can copy this text for external use or modify it to re-import changes back into the visual schema.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}