DOCSEARCHbyAlgolia
Submit Docs

ERD Editor Documentation

website·Indexed 32 days ago

https://docs.erd-editor.io/

Documentation for ERD Editor, an Entity-Relationship Diagram editor available as a web app, Google Drive app, and VS Code extension. Includes guides on table and relationship editing, a code generator, and API references for the ErdEditorElement interface and ERDEditorSchemaV3. Also features details on the @dineug/erd-editor-mcp server for integrating coding agents like Claude Code and Codex.

Tokens
22.6K
Snippets
82
Records
165
Agent score
59%

What's inside ERD Editor

  1. Overview of @dineug/erd-editor-mcp capabilities

    @dineug/erd-editor-mcp is an MCP server that enables coding agents to edit erd-editor diagrams. The agent acts as a collaborator, with tools to perform operations such as adding tables, renaming columns, relating tables, importing DDL dumps, and reading schemas as SQL.

    Key capabilities include:

    • Modifying schema elements: tables, columns (and options), relationships, indexes, memos, colors, and canvas positions.
    • Replacing documents: Supports parsing SQL DDL, GraphQL SDL, DBML, AML, or other .erd.json files.
    • Reading diagrams: Can export as IDs, entities, DDL for eight different databases, or raw JSON.
    • Managing settings: Configuring the database, Code Generator language/name cases, bracket types, and table visibility.
    • Transactional edits: Using erd_batch to run multiple edits as a single unit.
    • Independent undo/redo: The agent can undo its own edits without affecting the user's changes.

    Limitations:

    • Cannot control the viewer (zoom, scroll, or switch tabs).
    • Cannot execute the Code Generator directly; it reads DDL/JSON via erd_read and generates code itself.

  2. ERD Editor Portability and Framework Compatibility

    The ERD Editor is developed using standard web components, which ensures it is portable and can be integrated into any project regardless of the frontend framework being used.

  3. Understand ERD Editor operation modes (Live vs Headless)

    The ERD Editor server determines how to apply edits based on whether an editor (VS Code, Obsidian, or JetBrains) holds a lock file for the document in ~/.erd-editor/ide/.

    • Live Mode: Occurs when an editor is found that has the document open or contains the document's workspace/vault. The server joins the editing session, and changes appear immediately in the editor. If the document isn't open, the server opens it without taking keyboard focus.
    • Headless Mode: Occurs when no editor is found. The server loads the file from disk, applies the change, and replaces the file directly. erd_save is not required in this mode.
    • Refused: The server will refuse edits in the following scenarios:
      • Hub Off: The editor is open but its hub is disabled. Reads work from disk, but writes are blocked to prevent overwriting unsaved changes.
      • Path Mismatch (Windows): The agent uses a network share/mapped drive path while the editor uses a local drive path (or vice versa). The server returns invalidPath with the expected path.
      • Permissions (Windows): The editor was started as administrator while the agent was not, or the agent is in a sandbox. The server returns hubUnreachable.

  4. Access and navigate the Visualization tab

    The Visualization tab provides a high-level overview of the document. It can be opened via the Visualization tab in the top toolbar or through Quick Search under Tab.

    Shortcut to open directly in Flow mode (narrowed to selected tables and their immediate relationships):

    • Windows/Linux: Alt + F
    • Mac: ⌥ + F
    • Alternatively, use the Focus on this table entry in a table's context menu.

  5. ERD Editor JSON Schema Overview

    The .erd.json document format follows a specific schema (version 3.0.0) used by editor.value and setInitialValue(). The root object requires four main properties: version, settings, doc, and collections. The collections object must contain the following entity sets: tableEntities, tableColumnEntities, relationshipEntities, indexEntities, indexColumnEntities, and memoEntities.
    {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "version": "3.0.0",
  "settings": { ... },
  "doc": { ... },
  "collections": {
    "tableEntities": { ... },
    "tableColumnEntities": { ... },
    "relationshipEntities": { ... },
    "indexEntities": { ... },
    "indexColumnEntities": { ... },
    "memoEntities": { ... }
  }
}

  6. ErdEditorElement Interface Overview

    The ErdEditorElement is a custom HTMLElement that provides a full-featured ERD editor. It renders into a closed shadow root, meaning internal elements cannot be accessed via CSS selectors. Styling should be handled via setTheme() or --erd-editor-* CSS custom properties.
    interface ErdEditorElement extends HTMLElement {
  readonly: boolean;
  systemDarkMode: boolean;
  enableThemeBuilder: boolean;
  value: string;
  focus: () => void;
  blur: () => void;
  clear: () => void;
  destroy: () => void;
  setInitialValue: (value: string) => void;
  setPresetTheme: (themeOptions: Partial<ThemeOptions>) => void;
  setTheme: (theme: Partial<Theme>) => void;
  setKeyBindingMap: (keyBindingMap: Partial<Omit<KeyBindingMap, 'edit' | 'stop' | 'search' | 'undo' | 'redo' | 'zoomIn' | 'zoomOut' | 'zoomReset'>>) => void;
  setSchemaSQL: (value: string) => void;
  setSchemaGraphQL: (value: string) => void;
  setSchemaDBML: (value: string) => void;
  setSchemaAML: (value: string) => void;
  getSchemaSQL: (databaseVendor?: DatabaseVendor) => string;
  getSharedStore: (config?: SharedStoreConfig & { mouseTracker?: boolean; focusTracker?: boolean; }) => SharedStore;
  setDiffValue: (value: string) => void;
}

  8. Use the ERD Editor engine in Web Workers

    For environments without a DOM, such as Web Workers, use the @dineug/erd-editor/engine.js entry point. This allows the document store to run headlessly.
    import { ... } from '@dineug/erd-editor/engine.js';

  10. Focus on specific tables

    Focusing narrows the Visualization tab (Flow mode) to the selected tables and any table exactly one relationship away from them. Memos are excluded from this view.
    - Shortcut: Alt + F (with tables selected)
- Context Menu: "Focus on this table" or "Focus on selected tables"

  11. Import GraphQL SDL documents

    Import GraphQL SDL files via Import > GraphQL. The file must end in .graphql, .gql, or .graphqls.

    Mapping Logic:

    • Object type definitions $ ightarrow$ Tables.
    • extend type blocks $ ightarrow$ Merged into the extended type.
    • Interface fields $ ightarrow$ Inherited by implementing types.
    • Fields typed as another table $ ightarrow$ Relationships.
    • Lists on both sides $ ightarrow$ Junction table.
    • Skipped Content: Root types (Query, Mutation, Subscription), introspection types, and Relay/Federation/Hasura wrappers (e.g., PageInfo, *Connection).
    • Supported Directives: @id, @primaryKey, @unique, @autoincrement, @default, @map, @relation, @column, @table, @index, and @db.*.