Import Methods

Learn about the three powerful ways to import database schemas into ChartDB

ChartDB supports three distinct import methods, each designed for different use cases and workflows. The import system automatically detects the format of your input and processes it accordingly.

Supported Import Methods

ChartDB recognizes three import methods defined in the codebase:

export type ImportMethod = 'query' | 'ddl' | 'dbml';

Smart Query

Import from database metadata JSON

DDL Import

Import from SQL DDL scripts

DBML Import

Import from DBML definitions

Automatic Format Detection

ChartDB automatically detects which import method to use based on the content structure. The detection logic is implemented in detectImportMethod:

Format Detection

export const detectImportMethod = (content: string): ImportMethod | null => {
    if (!content || content.trim().length === 0) return null;

    const upperContent = content.toUpperCase();

    // Check for DBML patterns first (case sensitive)
    const dbmlPatterns = [
        /^Table\s+\w+\s*{/m,
        /^Ref:\s*\w+/m,
        /^Enum\s+\w+\s*{/m,
        /^TableGroup\s+/m,
        /^Note\s+\w+\s*{/m,
        /\[pk\]/,
        /\[ref:\s*[<>-]/,
    ];

    const hasDBMLPatterns = dbmlPatterns.some((pattern) =>
        pattern.test(content)
    );
    if (hasDBMLPatterns) return 'dbml';

    // Common SQL DDL keywords
    const ddlKeywords = [
        'CREATE TABLE',
        'ALTER TABLE',
        'DROP TABLE',
        'CREATE INDEX',
        'CREATE VIEW',
        'CREATE PROCEDURE',
        'CREATE FUNCTION',
        'CREATE SCHEMA',
        'CREATE DATABASE',
    ];

    // Check for SQL DDL patterns
    const hasDDLKeywords = ddlKeywords.some((keyword) =>
        upperContent.includes(keyword)
    );
    if (hasDDLKeywords) return 'ddl';

    // Check if it looks like JSON
    try {
        if (
            (content.trim().startsWith('{') && content.trim().endsWith('}')) ||
            (content.trim().startsWith('[') && content.trim().endsWith(']'))
        ) {
            return 'query';
        }
    } catch (error) {
        console.error('Error detecting content type:', error);
    }

    return null;
};

The detection happens in order: DBML → DDL → JSON. This ensures that each format is correctly identified based on its unique patterns.

Detection Patterns

DBML Detection

ChartDB looks for these specific patterns to identify DBML format:

Table Definitions

Pattern: Table table_name {

Table users {
  id int [pk]
  name varchar
}

References

Pattern: Ref: or [ref: </-/>]

Ref: posts.user_id > users.id

Table posts {
  user_id int [ref: > users.id]
}

Enums

Pattern: Enum enum_name {

Enum order_status {
  pending
  shipped
  delivered
}

Primary Keys

Pattern: [pk]

Table products {
  id int [pk]
  sku varchar [unique]
}

DDL Detection

ChartDB identifies SQL DDL by looking for these keywords:

Table Operations

• CREATE TABLE
• ALTER TABLE
• DROP TABLE

Index Operations

• CREATE INDEX

View Operations

• CREATE VIEW

Schema Operations

• CREATE SCHEMA
• CREATE DATABASE

Stored Procedures

• CREATE PROCEDURE
• CREATE FUNCTION

JSON Detection

For database metadata queries, ChartDB looks for:

• Content starting with { and ending with }
• Content starting with [ and ending with ]

This is typically JSON exported from database information_schema queries.

Import Workflow

Supported Database Types

All import methods support multiple database types:

PostgreSQL

Full support including extensions, custom types, and array fields

MySQL

Complete support for MySQL 5.7+ and 8.0+

SQL Server

Microsoft SQL Server 2016+

SQLite

SQLite 3.x with full constraint support

MariaDB

MariaDB 10.2+

Oracle

Oracle Database 11g+

CockroachDB

CockroachDB with PostgreSQL compatibility

ClickHouse

ClickHouse analytics database

Import Features Comparison

Feature	Smart Query	DDL Import	DBML Import
Tables	✅	✅	✅
Fields	✅	✅	✅
Relationships	✅	✅	✅
Indexes	✅	✅	✅
Views	✅	✅	❌
Custom Types	✅	✅	✅ (Enums)
Check Constraints	✅	✅	✅
Comments	✅	✅	✅ (Notes)
Default Values	✅	✅	✅
Array Types	✅	✅	✅ (PostgreSQL)

Error Handling

When import detection fails or content is invalid:

If the content cannot be detected as any of the three formats, ChartDB will return null from the detection method. Ensure your content matches one of the supported patterns.

For best results, ensure your DDL scripts are properly formatted with clear CREATE TABLE statements, and your DBML includes the required Table definitions.

Next Steps

Smart Query Import

Learn about importing from database metadata

DDL Import

Import SQL DDL scripts

DBML Import

Work with DBML format