Core Concepts
AI-ERD's data model is intentionally close to a real relational database. If you know how databases work, you already know most of this.
Diagram
A diagram is the top-level container — one diagram represents one logical schema. Each diagram has:
- A name and an optional note
- An owner (the user who created it)
- A list of tables, relationships (refs), enums, and table groups
- An auto-generated UUID that uniquely identifies it across the system
- Optional shareToken for public read-only sharing
Diagrams have version history — see Version History.
Table
A table is a database table. Each table has:
| Field | Description |
|---|---|
name | Table name (unique within schemaName) |
schemaName | Optional schema (e.g., public, auth) |
alias | Short alias for use in relationships |
note | Free-text description |
headerColor | Visual color for the canvas header |
columns | Ordered list of columns |
indexes | Indexes defined on the table |
Tables can belong to a table group for visual organization.
Column
Each column has:
| Field | Description |
|---|---|
name | Column name |
type | SQL type (e.g., bigint, varchar(255), timestamp) |
isPk | Primary key flag |
isUnique | Unique constraint |
isNotNull | Not-null constraint |
isIncrement | Auto-increment |
defaultValue | Default value (literal or function) |
note | Inline comment |
Index
Indexes are defined per table:
| Field | Description |
|---|---|
name | Index name |
isPk | Marks the primary key index |
isUnique | Unique index |
type | Index type (e.g., BTREE, HASH, GIN) |
columns | Ordered list of columns with sortOrder (ASC/DESC) |
Relationship (Ref)
A ref is a foreign key relationship between two columns (or column sets, for composite keys).
| Field | Description |
|---|---|
name | Optional ref name |
fromTableUuid / fromColumnUuids | The referencing side |
toTableUuid / toColumnUuids | The referenced side |
relationship | Cardinality (see below) |
onDelete | Action on delete (CASCADE, SET NULL, RESTRICT, etc.) |
onUpdate | Action on update |
Cardinality types
| Symbol | Meaning |
|---|---|
> | Many-to-one |
< | One-to-many |
- | One-to-one |
<> | Many-to-many |
Note: Relationships in AI-ERD use UUIDs, not table or column names. This makes refs stable across renames. The visual editor abstracts this away, but the API and MCP tools require UUIDs.
Enum
An enum is a named set of allowed values, useful for fields like status or role.
| Field | Description |
|---|---|
name | Enum name |
schemaName | Optional schema |
values | List of {value, note} entries |
note | Free-text description |
Columns can reference an enum as their type.
Table Group
A table group visually groups related tables on the canvas with a colored container. Groups don't change the schema — they're a layout / organization tool.
| Field | Description |
|---|---|
name | Group name |
color | Container color |
tables | Member tables |
Table groups require a paid plan.
Identity & UUIDs
Every entity (diagram, table, column, ref, enum, group) has a 32-character hex UUID. UUIDs are stable across renames and are how the API, MCP server, and version history identify things.
You generally won't see UUIDs in the visual editor — they're mostly relevant when you call the REST API or the MCP tools.
Permissions
Each diagram has access controls per user:
| Role | Can view | Can edit | Can delete | Can manage shares |
|---|---|---|---|---|
| OWNER | ✓ | ✓ | ✓ | ✓ |
| EDITOR | ✓ | ✓ | ✗ | ✗ |
| VIEWER | ✓ | ✗ | ✗ | ✗ |
| NONE | ✗ | ✗ | ✗ | ✗ |
In addition, a diagram can have a public share token that lets anyone with the link view (read-only) without signing in. See Collaboration.