# How to Import DBML into DrawDB: A Complete Guide

> Learn how to import DBML into DrawDB with this complete guide. Discover how DrawDB converts DBML text into visual diagrams using its built-in parser and hooks.

- Repository: [drawDB/drawdb](https://github.com/drawdb-io/drawdb)
- Tags: how-to-guide
- Published: 2026-08-10

---

**DrawDB converts DBML text into visual diagrams using the `fromDBML` parser located in [`src/utils/importFrom/dbml.js`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/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.

```javascript
// 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`](https://github.com/drawdb-io/drawdb/blob/main/src/utils/importFrom/dbml.js)** – Contains the `fromDBML` parser that transforms DBML text into DrawDB's diagram structure.
- **[`src/utils/exportAs/dbml.js`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/src/components/EditorHeader/Modal/ImportDiagram.jsx)** – The React component handling file reading and UI interactions for imports.
- **[`src/data/constants.js`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/src/components/EditorSidePanel/DBMLEditor.jsx), displays the current diagram as DBML text using the `toDBML` function from [`src/utils/exportAs/dbml.js`](https://github.com/drawdb-io/drawdb/blob/main/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:

```javascript
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`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/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`](https://github.com/drawdb-io/drawdb/blob/main/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.