# Schema Diagram

Visualize your database structure with an interactive entity-relationship diagram.

## Overview

The Schema Diagram provides a visual map of your database, showing all tables and their relationships at a glance. It helps you understand unfamiliar databases quickly and navigate between related data.

## Accessing the Schema Diagram

1. Open any database connection  
2. Click **Schema** in the sidebar navigation  
3. The diagram loads automatically with all tables

## Understanding the Diagram

### Tables

Each table appears as a card showing:

- **Table name** \- Header with the table name  
- **Row count** \- Estimated number of records (formatted: 1K, 10K, 1M)  
- **Columns** \- Expandable list of all columns

### Column Indicators

Columns display icons indicating their type and role:

| Icon | Meaning |
| --- | --- |
| Key (amber) | Primary Key |
| Link (violet) | Foreign Key |
| Calendar | Date/timestamp column |
| Hash | Numeric column |
| Type | Text column |

### Relationships

Lines connect tables that have foreign key relationships:

- Lines flow from the foreign key column to the referenced table
- Hover over a table to highlight its relationships
- Connected tables and their relationship lines become emphasized

### Legend

The legend in the top-left explains the visual indicators:

- **PK** \- Primary Key (amber)
- **FK** \- Foreign Key (violet)
- **Lines** \- Foreign key relationships

## Interacting with the Diagram

### Expand and Collapse Tables

Toggle column visibility for each table:

1. Click a table card to expand/collapse its columns  
2. Use **Expand All** / **Collapse All** buttons in the header  
3. Collapsed tables show just the name and row count

### Hover Highlighting

Hover over any table to:

- Highlight the table
- Highlight all related tables
- Emphasize the connecting relationship lines
- Fade unrelated tables

This helps trace relationships in complex schemas.

### Navigate to Table Data

Click a table name to:

1. Navigate to that table's data view  
2. Start browsing records immediately  
3. Apply filters and sorting as needed

### Pan and Zoom

Navigate large diagrams:

- **Drag** the background to pan
- **Scroll** to zoom in/out
- Use the **zoom controls** in the bottom-left
- Click **Fit View** to see all tables

### Mini Map

The mini map in the bottom-right shows:

- Your current viewport position
- Overview of the entire diagram
- Click to jump to different areas

## Diagram Layout

### Automatic Arrangement

Tables are automatically arranged based on:

- Foreign key dependencies (referenced tables appear first)
- Grid-based positioning for clarity
- Logical grouping of related tables

### Manual Positioning

Drag tables to reposition them:

- Click and drag any table card
- Arrangement persists during your session
- Refresh to reset to automatic layout

## Refreshing the Schema

When your database schema changes:

1. Click the **Refresh** button in the header  
2. Wait for schema introspection to complete  
3. The diagram updates with new tables/columns

Schema is cached for 1 hour and refreshes automatically.

## Table Sidebar

On larger screens, a sidebar lists all tables:

- Alphabetically sorted
- Shows row count per table
- Click to highlight that table in the diagram

On mobile, access this via the menu button.

## Best Practices

### Understanding New Databases

When exploring an unfamiliar database:

1. Start with the schema diagram for an overview
2. Identify the main entities (users, orders, products)
3. Trace relationships to understand data flow
4. Click through to explore actual data

### Tracing Relationships

To understand how tables connect:

1. Hover over the main table you're interested in
2. See which tables it references (outgoing)
3. See which tables reference it (incoming)
4. Follow the highlighted lines

### Complex Schemas

For databases with many tables:

1. Use zoom to see the full picture
2. Use the mini map for navigation
3. Collapse tables you're not focused on
4. Hover to isolate specific relationships

## Performance

### Large Schemas

The diagram handles large schemas efficiently:

- Tables render on-demand as you pan
- Relationship lines use optimized paths
- Row counts use PostgreSQL estimates

### Loading States

While the diagram loads:

- A skeleton placeholder appears
- Tables populate as schema loads
- Relationships draw after all tables

## Current Limitations

- **Single schema** \- Shows only the public schema by default
- **No editing** \- The diagram is read-only; use data views to edit
- **Session layout** \- Manual positioning resets on page refresh
- **Dense schemas** \- Very large schemas (100+ tables) may require more panning

## Next Steps

- [Navigate relationships](/content/docs/features/relationships/index.html) in the data view  
- [Browse table data](/content/docs/features/browsing/index.html) after identifying tables of interest  
- [Search for records](/content/docs/features/search/index.html) across your database