Managing Relationships

Understanding Relationships

Relationships define how tables connect to each other through foreign keys. ChartDB supports all standard relationship types and provides visual tools for managing them.

Relationship Types

ChartDB supports four relationship cardinalities:

One-to-One (1:1)

Each record in Table A relates to exactly one record in Table B.Example: User → UserProfile

One-to-Many (1:N)

Each record in Table A relates to multiple records in Table B.Example: Customer → Orders

Many-to-One (N:1)

Multiple records in Table A relate to one record in Table B.Example: Orders → Customer

Many-to-Many (N:M)

Records in both tables can relate to multiple records in the other table (requires junction table).Example: Students ↔ Courses

Creating Relationships

Method 1: Visual Connection (Recommended)

The fastest way to create relationships:

Start Connection

Right-click on a table and select Add Relationship.A floating connection line will appear from the table.

Select Target Table

Click on the target table to complete the relationship.ChartDB will automatically select matching fields if available.

Configure Relationship

A relationship configuration dialog appears. Set:

Source field (foreign key field)
Target field (primary key field)
Relationship cardinality
Relationship name (optional)

ChartDB automatically detects and suggests relationships when field names match the pattern {table}_id → {table}.id.

Method 2: Create Relationship Dialog

For more control over relationship creation:

Open Dialog

Right-click on the canvas and select New Relationship.

Select Tables

Choose:

Source table
Target table

Select Fields

Choose:

Source field (the foreign key)
Target field (usually the primary key)

Set Cardinality

Choose the relationship type:

One-to-One (1:1)
One-to-Many (1:N)
Many-to-One (N:1)
Many-to-Many (N:M)

Relationship Properties

string

required

Unique identifier for the relationship.

name

string

required

Relationship name, typically follows the pattern:

fk_{source_table}_{target_table}
{source_table}_ibfk_1 (MySQL auto-generated)

Example: dept_emp_ibfk_1

sourceTableId

string

required

The ID of the table containing the foreign key.

targetTableId

string

required

The ID of the table being referenced (usually contains the primary key).

sourceFieldId

string

required

The field in the source table (foreign key field).

targetFieldId

string

required

The field in the target table (primary key or unique field).

sourceCardinality

'one' | 'many'

required

Cardinality on the source side of the relationship.

targetCardinality

'one' | 'many'

required

Cardinality on the target side of the relationship.

sourceSchema

string

Schema of the source table (for databases with schema support).

targetSchema

string

Schema of the target table (for databases with schema support).

Editing Relationships

Click on any relationship line to open the edit popover:

Click Relationship

Click on the relationship line connecting two tables.

Edit Cardinality

The popover shows buttons to quickly change between:

1:1 (One-to-One)
1:N (One-to-Many)

Click the desired type to update.

Other Actions

The popover also provides:

Switch (⇄): Reverse the relationship direction
Details (◉): Open full relationship details in sidebar
Delete (🗑): Remove the relationship

For detailed relationship configuration:

Open Sidebar

Press ⌘B (Mac) or Ctrl+B (Windows) to toggle the sidebar.

Select Relationships Tab

Click on the Relationships tab in the sidebar.

Find Relationship

Browse or search for the relationship you want to edit.

Edit Properties

Modify:

Relationship name
Source/target fields
Cardinality
On Delete/On Update actions (if supported)

Switching Relationship Direction

You can reverse the source and target of a relationship:

Click on the relationship line
Click the Switch button (⇄) in the popover
The source and target tables/fields are swapped

Switching a relationship reverses which table contains the foreign key. Ensure this matches your actual database schema.

Deleting Relationships

To remove a relationship:

Relationship Visualization

Visual Elements

Relationships are displayed as connecting lines with visual indicators:

Line Style

Solid lines for foreign key relationships
Arrow heads indicate direction
Hover to highlight

Cardinality Markers

Circle (◯) = “one”
Crow’s foot (⋮) = “many”
Positioned at each end of the line

Connection Points

Relationships connect at the specific fields involved:

The line extends from the foreign key field
To the referenced primary key field
Labels show field names on hover

Common Relationship Patterns

One-to-Many: Customer → Orders

CREATE TABLE customers (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL
);

CREATE TABLE orders (
    id INT PRIMARY KEY AUTO_INCREMENT,
    customer_id INT NOT NULL,
    order_date DATE NOT NULL,
    FOREIGN KEY (customer_id) REFERENCES customers(id)
);

Create Tables

Create both customers and orders tables.

Add Foreign Key Field

Add customer_id field to orders table.

Create Relationship

Connect orders.customer_id → customers.id with cardinality many-to-one.

One-to-One: User → Profile

CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    email VARCHAR(255) UNIQUE NOT NULL
);

CREATE TABLE user_profiles (
    id INT PRIMARY KEY AUTO_INCREMENT,
    user_id INT UNIQUE NOT NULL,
    bio TEXT,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

For one-to-one relationships, add a UNIQUE constraint on the foreign key field.

Many-to-Many: Students ↔ Courses

CREATE TABLE students (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL
);

CREATE TABLE courses (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL
);

CREATE TABLE student_courses (
    student_id INT NOT NULL,
    course_id INT NOT NULL,
    enrolled_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (student_id, course_id),
    FOREIGN KEY (student_id) REFERENCES students(id),
    FOREIGN KEY (course_id) REFERENCES courses(id)
);

Create Entity Tables

Create students and courses tables.

Create Junction Table

Create student_courses with foreign keys to both tables.

Create Relationships

Create two relationships:

student_courses.student_id → students.id (many-to-one)
student_courses.course_id → courses.id (many-to-one)

Self-Referencing: Employee → Manager

CREATE TABLE employees (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL,
    manager_id INT,
    FOREIGN KEY (manager_id) REFERENCES employees(id)
);

Self-referencing relationships point from a table back to itself. Useful for hierarchical data like org charts, category trees, etc.

Composite Foreign Keys

For tables with composite primary keys:

CREATE TABLE order_items (
    order_id INT,
    item_id INT,
    quantity INT NOT NULL,
    PRIMARY KEY (order_id, item_id)
);

CREATE TABLE shipments (
    id INT PRIMARY KEY,
    order_id INT,
    item_id INT,
    FOREIGN KEY (order_id, item_id) REFERENCES order_items(order_id, item_id)
);

ChartDB currently displays composite foreign keys as multiple individual relationships. When exporting to SQL, they are correctly combined into a single constraint.

Cross-Schema Relationships

For databases supporting schemas (PostgreSQL, SQL Server):

CREATE SCHEMA auth;
CREATE SCHEMA app;

CREATE TABLE auth.users (
    id INT PRIMARY KEY
);

CREATE TABLE app.posts (
    id INT PRIMARY KEY,
    user_id INT,
    FOREIGN KEY (user_id) REFERENCES auth.users(id)
);

Relationships can connect tables across different schemas. ChartDB tracks both:

sourceSchema and sourceTableId
targetSchema and targetTableId

Referential Actions

While creating relationships, you can specify what happens on UPDATE and DELETE:

ON DELETE Actions

CASCADE: Delete related rows
SET NULL: Set foreign key to NULL
SET DEFAULT: Set to default value
RESTRICT: Prevent deletion
NO ACTION: Similar to RESTRICT

ON UPDATE Actions

CASCADE: Update related rows
SET NULL: Set foreign key to NULL
SET DEFAULT: Set to default value
RESTRICT: Prevent update
NO ACTION: Similar to RESTRICT

Referential action support varies by database. ChartDB exports the appropriate syntax for your selected database type.

Best Practices

Foreign Key Naming

Use consistent naming conventions:

{referenced_table}_id for the field name
fk_{source_table}_{target_table} for constraint name

Examples:

Field: customer_id, Constraint: fk_orders_customers
Field: user_id, Constraint: fk_posts_users

Index Foreign Keys

Always index foreign key fields for performance:

Speeds up joins
Required for some databases
ChartDB exports appropriate indexes

Choose Correct Cardinality

Think carefully about relationship types:

One-to-Many is most common
One-to-One needs UNIQUE constraint on FK
Many-to-Many requires junction table

Document Relationships

Add comments explaining:

Why tables are related
Business rules enforced
Special cascade behaviors

Avoid Circular Dependencies

Be cautious of circular references:

Can cause issues with data loading
May need to temporarily disable constraints
Document any circular dependencies clearly

Troubleshooting

Relationship Won't Create

Common causes:

Data types don’t match
Target field is not a primary key or unique
Schema mismatch

Solution: Ensure field types and constraints match exactly.

Relationship Line Not Visible

Possible reasons:

Tables are overlapping
Canvas is zoomed too far out
Relationship is filtered out

Solution: Zoom in, reposition tables, or check filter settings.

Can't Delete Relationship

Issue: Diagram is in readonly mode.Solution: Ensure you have edit permissions and the diagram is not locked.

Next Steps

Editing Schema

Learn how to create and modify tables

Using Areas

Group related tables visually

Export Schema

Export your schema to SQL, DBML, or images

Keyboard Shortcuts

Speed up relationship management

Get Started

Core Features

Database Support

Guides

Self-Hosting

​Understanding Relationships

​Relationship Types

One-to-One (1:1)

One-to-Many (1:N)

Many-to-One (N:1)

Many-to-Many (N:M)

​Creating Relationships

​Method 1: Visual Connection (Recommended)

​Method 2: Create Relationship Dialog

​Relationship Properties

​Editing Relationships

​Quick Edit via Popover

​Edit via Sidebar

​Switching Relationship Direction

​Deleting Relationships

​Relationship Visualization

​Visual Elements

Line Style

Cardinality Markers

​Connection Points

​Common Relationship Patterns

​One-to-Many: Customer → Orders

​One-to-One: User → Profile

​Many-to-Many: Students ↔ Courses

​Self-Referencing: Employee → Manager

​Composite Foreign Keys

​Cross-Schema Relationships

​Referential Actions

​Best Practices

​Troubleshooting

​Next Steps

Editing Schema

Using Areas

Export Schema

Keyboard Shortcuts

Build docs developers (and LLMs) love

Understanding Relationships

Relationship Types

Creating Relationships

Method 1: Visual Connection (Recommended)

Method 2: Create Relationship Dialog

Relationship Properties

Editing Relationships

Quick Edit via Popover

Edit via Sidebar

Switching Relationship Direction

Deleting Relationships

Relationship Visualization

Visual Elements

Connection Points

Common Relationship Patterns

One-to-Many: Customer → Orders

One-to-One: User → Profile

Many-to-Many: Students ↔ Courses

Self-Referencing: Employee → Manager

Composite Foreign Keys

Cross-Schema Relationships

Referential Actions

Best Practices

Troubleshooting

Next Steps