Diagram Editor - ChartDB

The ChartDB diagram editor provides a powerful, interactive canvas for creating and editing database diagrams. Built on ReactFlow, it offers a modern, intuitive interface for database schema design.

Canvas Overview

The editor canvas is the heart of ChartDB, providing real-time visual editing of your database schema.

Drag & Drop

Move tables and organize your layout

Visual Relationships

See connections between tables in real-time

Inline Editing

Edit tables, fields, and relationships directly on canvas

Multi-Select

Select and manipulate multiple tables at once

Node Types

The canvas supports multiple node types for different diagram elements:

export type NodeType =
    | TableNodeType
    | AreaNodeType
    | NoteNodeType
    | TempCursorNodeType
    | CreateRelationshipNodeType;

const nodeTypes: NodeTypes = {
    table: TableNode,
    area: AreaNode,
    note: NoteNode,
    'temp-cursor': TempCursorNode,
    'create-relationship': CreateRelationshipNode,
};

Table Nodes

Table nodes are the primary elements representing database tables:

Structure
Visual Indicators
Editing Mode

Each table node displays:

Table name and schema
Column list with types
Primary key indicators
Foreign key badges
Index information
Relationship handles

// Primary key fields
🔑 Primary key icon

// Foreign key fields  
🔗 Foreign key badge

// Unique constraints
⚡ Unique indicator

// Not null
Bold field names

// Array types (PostgreSQL)
[] Array brackets

Area Nodes

Group related tables together using area nodes:

interface Area {
    id: string;
    name: string;
    x: number;
    y: number;
    width: number;
    height: number;
    color?: string;
}

Areas provide visual organization and can contain multiple tables.

Note Nodes

Add documentation directly to your diagram:

interface Note {
    id: string;
    content: string;
    x: number;
    y: number;
    width?: number;
    height?: number;
}

Edge Types

The canvas supports multiple edge types for different relationships:

export type EdgeType =
    | RelationshipEdgeType
    | DependencyEdgeType
    | TempFloatingEdgeType;

const edgeTypes: EdgeTypes = {
    'relationship-edge': RelationshipEdge,
    'dependency-edge': DependencyEdge,
    'temp-floating-edge': TempFloatingEdge,
};

Relationship Edges

Visual representation of foreign key relationships:

Cardinality Indicators

Relationships show cardinality at both ends:

One: Single line endpoint
Many: Crow’s foot endpoint
One-to-Many
Many-to-One
One-to-One
Many-to-Many

Relationship Labels

Edges display:

Constraint name
Source/target fields
Cardinality symbols

Interactive Editing

Click a relationship edge to:

Change cardinality
Edit constraint name
Delete relationship
View relationship details

Dependency Edges

For view dependencies and table relationships:

interface Dependency {
    id: string;
    tableId: string;
    dependentTableId: string;
    createdAt: number;
}

Views show dashed dependency lines to their source tables.

Canvas Controls

Background and Grid

The canvas includes a customizable background:

<Background 
    variant={BackgroundVariant.Dots} 
    gap={12} 
    size={1} 
/>

MiniMap

Navigate large diagrams with the minimap:

<MiniMap
    nodeStrokeWidth={3}
    zoomable
    pannable
/>

Zoom Controls

Built-in zoom and pan controls:

<Controls
    showZoom
    showFitView
    showInteractive
/>

Table Editing

Field Management

Edit fields directly in table edit mode:

const addField = () => {
    const newField: DBField = {
        id: generateId(),
        name: 'new_field',
        type: { id: 'varchar', name: 'varchar' },
        nullable: true,
        primaryKey: false,
        unique: false,
        createdAt: Date.now(),
    };
    
    updateTable({
        ...table,
        fields: [...table.fields, newField],
    });
};

Constraints

Set field constraints in edit mode:

Primary Key
Unique
Not Null
Auto Increment
Default Value

field.primaryKey = true;
field.nullable = false; // PKs are automatically NOT NULL

field.unique = true;

field.nullable = false;

field.increment = true;

field.default = 'default_value';

Data Types

ChartDB supports all major database data types:

interface DataType {
    id: string;
    name: string;
    fieldAttributes?: {
        characterMaximumLength?: boolean;
        precision?: boolean;
        scale?: boolean;
    };
}

Common types include:

Numeric: INT, BIGINT, DECIMAL, NUMERIC
String: VARCHAR, TEXT, CHAR
Date/Time: TIMESTAMP, DATE, TIME
Boolean: BOOLEAN
JSON: JSON, JSONB
Arrays: TEXT[], INT[] (PostgreSQL)
Binary: BYTEA, BLOB

Creating Relationships

Visual Relationship Creation

Create relationships by connecting table fields:

Enter Relationship Mode

Click the “Add Relationship” button or press R

Select Source Field

Click on the source field in the first table

Select Target Field

Click on the target field in the second table

Configure Relationship

Set cardinality and constraint name:

const relationship: DBRelationship = {
    id: generateId(),
    name: `fk_${sourceTable.name}_${sourceField.name}`,
    sourceTableId: sourceTable.id,
    targetTableId: targetTable.id,
    sourceFieldId: sourceField.id,
    targetFieldId: targetField.id,
    sourceCardinality: 'many',
    targetCardinality: 'one',
    createdAt: Date.now(),
};

Relationship Validation

ChartDB validates relationships in real-time:

const areFieldTypesCompatible = (
    sourceType: DataType,
    targetType: DataType
): boolean => {
    // Check if field types are compatible for FK relationship
    return sourceType.id === targetType.id;
};

Foreign key fields must have compatible data types. ChartDB will warn you if types don’t match.

Right-click any table to access quick actions:

interface TableContextMenuActions {
    edit: () => void;
    duplicate: () => void;
    delete: () => void;
    addField: () => void;
    exportSQL: () => void;
    changeColor: (color: string) => void;
}

Edit Table

Opens the table in edit mode

Duplicate

Creates a copy of the table with all fields

Delete

Removes table and all associated relationships

Add Field

Quickly add a new field to the table

Change Color

Set a custom color for visual organization

Keyboard Shortcuts

Selection
Editing
Navigation
Tools

Cmd/Ctrl + A - Select all tables
Cmd/Ctrl + Click - Multi-select tables
Shift + Drag - Box selection

Delete - Delete selected items
Cmd/Ctrl + C - Copy selected tables
Cmd/Ctrl + V - Paste tables
Cmd/Ctrl + Z - Undo
Cmd/Ctrl + Shift + Z - Redo

R - Create relationship
T - Add table
N - Add note
A - Add area
Esc - Cancel current action

Mouse Controls

Left Click: Select/deselect
Double Click: Edit table
Right Click: Context menu
Drag: Move selected items
Scroll: Zoom in/out

Layout Management

Auto Layout

ChartDB provides automatic table positioning:

const adjustedTables = adjustTablePositions({
    tables,
    relationships,
    mode: 'perSchema', // or 'single'
});

Layout modes:

perSchema: Groups tables by schema
single: All tables in one group

Manual Positioning

Drag tables to arrange them manually:

const onNodesChange: OnNodesChange = useCallback((changes) => {
    changes.forEach(change => {
        if (change.type === 'position' && change.position) {
            updateTablePosition(change.id, change.position);
        }
    });
}, []);

Alignment Tools

Align multiple selected tables:

Align left
Align right
Align top
Align bottom
Distribute horizontally
Distribute vertically

Table Filtering

Filter tables on the canvas by various criteria:

interface DiagramFilter {
    schemas?: string[];
    tables?: string[];
    searchTerm?: string;
    showViews?: boolean;
}

const filterTable = (
    table: DBTable,
    filter: DiagramFilter
): boolean => {
    if (filter.schemas && !filter.schemas.includes(table.schema)) {
        return false;
    }
    
    if (filter.searchTerm) {
        const term = filter.searchTerm.toLowerCase();
        return table.name.toLowerCase().includes(term);
    }
    
    if (!filter.showViews && table.isView) {
        return false;
    }
    
    return true;
};

The filter panel allows you to:

Filter by Schema

Show/hide specific schemas

Search Tables

Find tables by name

Toggle Views

Show or hide database views

Filter Relationships

Show only related tables

Visual Customization

Table Colors

Customize table appearance:

const defaultTableColor = '#3b82f6';

const updateTableColor = (tableId: string, color: string) => {
    updateTable({
        ...table,
        color,
    });
};

Theme Support

ChartDB supports light and dark themes:

const { theme } = useTheme();

// Canvas adapts to theme
const canvasStyle = {
    background: theme === 'dark' ? '#1a1a1a' : '#ffffff',
};

Advanced Features

Overlap Detection

ChartDB detects and highlights overlapping tables:

const findOverlappingTables = (
    tables: DBTable[],
    currentTable: DBTable
): DBTable[] => {
    return tables.filter(t => {
        if (t.id === currentTable.id) return false;
        
        const overlap = 
            currentTable.x < t.x + t.width &&
            currentTable.x + currentTable.width > t.x &&
            currentTable.y < t.y + t.height &&
            currentTable.y + currentTable.height > t.y;
            
        return overlap;
    });
};

Dynamic Table Sizing

Tables automatically resize based on content:

const calcTableHeight = (table: DBTable): number => {
    const headerHeight = 40;
    const fieldHeight = 32;
    const padding = 8;
    
    return headerHeight + 
           (table.fields.length * fieldHeight) + 
           padding;
};

const MIN_TABLE_SIZE = { width: 200, height: 100 };

Lost in Canvas Detection

Warning when you’re far from visible tables:

const useIsLostInCanvas = () => {
    const { getViewport } = useReactFlow();
    const { tables } = useChartDB();
    
    // Detect if viewport is far from any tables
    const isLost = useMemo(() => {
        const { x, y, zoom } = getViewport();
        // Calculate distance from nearest table
        return distanceFromNearestTable > threshold;
    }, [viewport, tables]);
    
    return isLost;
};

Performance Optimization

The canvas is optimized for large diagrams:

Virtualization

Only visible nodes and edges are rendered

Debounced Updates

Position updates are debounced to reduce re-renders:

const debouncedUpdate = debounce((position) => {
    updateTablePosition(position);
}, 100);

Memoization

Expensive calculations are memoized:

const visibleTables = useMemo(() => {
    return tables.filter(t => filterTable(t, filter));
}, [tables, filter]);

Edge Optimization

Edges are only recalculated when tables move

Accessibility

The editor includes keyboard navigation and screen reader support:

All actions accessible via keyboard
Focus management for modals and panels
ARIA labels for all interactive elements
High contrast mode support

Next Steps

Export Options

Export your diagram to various formats

AI Migration

Use AI to migrate between databases

Get Started

Core Features

Database Support

Guides

Self-Hosting

​Canvas Overview

Drag & Drop

Visual Relationships

Inline Editing

Multi-Select

​Node Types

​Table Nodes

​Area Nodes

​Note Nodes

​Edge Types

​Relationship Edges

​Dependency Edges

​Canvas Controls

​Background and Grid

​MiniMap

​Zoom Controls

​Table Editing

​Field Management

​Constraints

​Data Types

​Creating Relationships

​Visual Relationship Creation

​Relationship Validation

​Table Context Menu

​Canvas Navigation

​Keyboard Shortcuts

​Mouse Controls

​Layout Management

​Auto Layout

​Manual Positioning

​Alignment Tools

​Table Filtering

​Canvas Filter Panel

Filter by Schema

Search Tables

Toggle Views

Filter Relationships

​Visual Customization

​Table Colors

​Theme Support

​Advanced Features

​Overlap Detection

​Dynamic Table Sizing

​Lost in Canvas Detection

​Performance Optimization

​Accessibility

​Next Steps

Export Options

AI Migration

Canvas Overview

Node Types

Table Nodes

Area Nodes

Note Nodes

Edge Types

Relationship Edges

Dependency Edges

Canvas Controls

Background and Grid

MiniMap

Zoom Controls

Table Editing

Field Management

Constraints

Data Types

Creating Relationships

Visual Relationship Creation

Relationship Validation

Table Context Menu

Canvas Navigation

Keyboard Shortcuts

Mouse Controls

Layout Management

Auto Layout

Manual Positioning

Alignment Tools

Table Filtering

Canvas Filter Panel

Visual Customization

Table Colors

Theme Support

Advanced Features

Overlap Detection

Dynamic Table Sizing

Lost in Canvas Detection

Performance Optimization

Accessibility

Next Steps