TUI-ERD

A Terminal UI Entity-Relationship Diagram generator that visualizes SQL database schemas in your terminal.

Features

• Multi-DB Support: Generate ERD diagrams from SQLite, MySQL, PostgreSQL, Oracle, and MariaDB databases
• Interactive Terminal Rendering: Color-coded, ASCII-based ERD visualization
• Multiple Layout Options:
  • spaced: Full-width layout with uniform grid spacing between tables
  • compact: Minimal spacing layout for compact diagrams
  • detail: Vertical list layout with enhanced field metadata (type, index, unique, nullable, default)
• Invert Mode: Switch between dark (default) and light theme using --invert
• Custom Width Control: Set maximum diagram width (default: 80 columns)
• Relationship Lines: Visual connectors showing table relationships with cardinality indicators
• Debug Mode: Visualize grid cells and checkpoints for debugging layout issues

Installation

npm install -g tui-erd

Usage

tui-erd --help

Basic Usage

# Generate ERD from SQL schema file
tui-erd -f sample/sqlite-schema.sql

# Generate with color support
tui-erd -f sample/sqlite-schema.sql --color

# Use light theme (invert colors)
tui-erd -f sample/sqlite-schema.sql --invert

# Set custom width
tui-erd -f sample/sqlite-schema.sql --max-width 100

# Specify database type (default: sqlite)
tui-erd -f sample/sqlite-schema.sql --type sqlite

# Use compact layout
tui-erd -f sample/sqlite-schema.sql --layout compact

# Use detail layout (vertical list with field metadata)
tui-erd -f sample/sqlite-schema.sql --layout detail

# Disable random layout optimization
tui-erd -f sample/sqlite-schema.sql --random false

# Debug mode
tui-erd -f sample/sqlite-schema.sql --debug

Command Line Options

| Option | Short | Description | | --------------------------- | ----- | ------------------------------------------------------- | | -f, --file <path> | -f | Path to SQL schema file | | -t, --type <type> | -t | Database type: sqlite, mysql, postgres, oracle, mariadb | | -c, --color <on/off> | -c | Enable/disable color output | | -s, --stats <on/off> | -s | Enable/disable stats display | | -i, --invert <bool> | -i | Invert colors: false=dark (default), true=light | | -w, --max-width <columns> | -w | Maximum diagram width in columns (default: 80) | | -l, --layout <type> | -l | Layout: spaced (default), compact, detail | | -r, --random <bool> | -r | Enable/disable random layout optimization (default: on) | | -d, --debug | -d | Show debug markers and ruler | | -v, --version | -v | Output version number | | -h, --help | -h | Show help message |

Examples

SQLite Schema Example

The following SQL schema defines a simple e-commerce database with users, orders, products, and order_items tables:

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    total DECIMAL(10, 2) NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    price DECIMAL(10, 2) NOT NULL,
    stock INTEGER DEFAULT 0
);

CREATE TABLE order_items (
    id INTEGER PRIMARY KEY,
    order_id INTEGER NOT NULL,
    product_id INTEGER NOT NULL,
    quantity INTEGER NOT NULL,
    price DECIMAL(10, 2) NOT NULL,
    FOREIGN KEY (order_id) REFERENCES orders(id),
    FOREIGN KEY (product_id) REFERENCES products(id)
);

Generated ERD Output:

      +------------+                                       +--------------+
      | USERS      |                                       | ORDERS       |
      +------------+                                       +--------------+
      | * id       |-<-----------------+               +-->| * id         |
      | username   |                   +---------------|--*| user_id (FK) |
      | email      |                user_id            |   | total        |
      | created_at |                                   |   | status       |
      +------------+                                   |   | created_at   |
                                                        |   +--------------+
                                                        |
                                                        |
                                                        |
      +------------+                                   |   +-----------------+
      | PRODUCTS   |                                   |   | ORDER_ITEMS     |
      +------------+                                   |   +-----------------+
      | * id       |-<-----------------+               |   | * id            |
      | name       |                   |               +--*| order_id (FK)   |
      | price      |                   +------------------*| product_id (FK) |
      | stock      |              product_id               | quantity        |
      +------------+                                       | price           |
                                                            +-----------------+

This diagram shows:

• Users are related to Orders (1:N relationship)
• Orders are related to Order Items (1:N relationship)
• Products are related to Order Items (1:N relationship)
• Primary keys are marked with *
• Foreign key relationships are shown with (FK) labels

Architecture

Modules

• Parser (src/parser/): Parses SQL schemas and extracts table/relationship information
• Layout (src/layout/): Arranges tables and relationships using grid-based algorithms
• Renderer (src/renderer/): Renders the ERD diagram with ASCII art and styling

Components

src/
├── index.ts          # CLI entry point
├── parser/           # SQL schema parsing
│   └── table-parser.ts # Parse SQL and extract entities
├── layout/           # Layout algorithms
│   └── layout-engine.ts # Grid-based layout with spaced/compact modes
├── renderer/         # Rendering logic
│   ├── erd-renderer.ts  # Main ERD renderer
│   └── line-renderer.ts # Relationship line drawing
└── config/           # Configuration management
    └── index.ts      # Config loading and defaults

Sample Databases

The sample/ directory contains example SQL schemas for testing:

• sqlite-schema.sql: SQLite e-commerce schema (users, orders, products, order_items)
• demo-sqlite-schema.sql: Demo schema for testing grid layout and relationships
• postgres-schema.sql: PostgreSQL multi-tenant schema (tenants, roles, users, refresh_tokens, files, logs, mails)

# Test with SQLite sample schema
tui-erd -f sample/sqlite-schema.sql

# Test with PostgreSQL sample schema
tui-erd -f sample/postgres-schema.sql --type postgres

# Debug layout with demo schema
tui-erd -f sample/demo-sqlite-schema.sql --debug

Debug Mode

When running with the --debug flag, the renderer displays:

• ---------1---------2... ruler at the top showing character positions
• + markers at grid cell corners (green for table cells, blue for spacing cells)
• @ markers at checkpoint positions (center of spacing cells)

This helps visualize how the layout engine positions tables and routes relationship lines.

License

MIT License