🌳 sqltree

1. Prerequisites

• Node.js 20+ — download or use nvm install 20
• A running PostgreSQL or MySQL (or compatible) database you can connect to

That's it — sqltree has no native dependencies and works on macOS, Linux, and Windows.

2. Installation

Zero-install (recommended)

Run directly with npx — nothing to install:

npx sqltree

Global install

If you use sqltree often, install it globally:

npm install -g sqltree
sqltree

3. Connecting to a Database

Interactive mode

Just run npx sqltree with no arguments. You'll be guided through choosing a database type, entering your host, port, user, password, and database name.

$ npx sqltree

  ╔══════════════════════════════════════╗
  ║   🌳 sqltree v1.4.6                  ║
  ║   PostgreSQL · MySQL · CLI Client    ║
  ╚══════════════════════════════════════╝

? Select a database type:
  ❯ PostgreSQL
    MySQL
    CockroachDB
    Redshift
    YugabyteDB
    ...

URI string

Pass a connection URI directly:

# PostgreSQL
npx sqltree --uri postgresql://user:pass@localhost:5432/mydb

# MySQL
npx sqltree --uri mysql://root:secret@127.0.0.1:3306/app

Individual parameters

npx sqltree -t postgres -H localhost -p 5432 -U postgres -d mydb

Environment variable

Set DATABASE_URL and sqltree picks it up automatically:

export DATABASE_URL=postgresql://user:pass@localhost/mydb
npx sqltree

4. Navigating the Tree

After connecting, sqltree displays a two-column TUI: a tree browser on the left and a detail panel on the right.

 sqltree — postgres@localhost:5432                 Connected
┌─ 🌳 Browser ────┐┌─ Detail ──────────────────────┐
│ ▼ 📦 mydb        ││  Database: mydb               │
│   ▼ 📂 public    ││  Owner: postgres              │
│     ▸ 📋 users   ││  Encoding: UTF8               │
│     ▸ 📋 orders  ││  Size: 24 MB                  │
│     ▸ 📋 items   ││  Tables: 3                    │
│   ▸ 📂 pg_catalog││                               │
│ ▸ 📦 template0   ││                               │
│ ▸ 📦 template1   ││                               │
│                   ││                               │
└───────────────────┘└───────────────────────────────┘
 ↑↓ navigate │ → expand │ ← back │ Tab REPL │ q quit

5. Browsing Table Data

Press Enter on any table node to browse its rows. Data is paginated — use ↑/↓ to page through results and w/s to scroll within a page.

┌─ 📋 users (page 1 of 4) ─────────────────────────┐
│ id │ name          │ email              │ active  │
│────│───────────────│────────────────────│─────────│
│  1 │ Alice Johnson │ alice@example.com  │ true    │
│  2 │ Bob Smith     │ bob@example.com    │ true    │
│  3 │ Carol White   │ carol@example.com  │ false   │
│  4 │ Dan Lee       │ dan@example.com    │ true    │
│ .. │ ..            │ ..                 │ ..      │
└───────────────────────────────────────────────────┘
 ↓ next page │ ↑ prev page │ ← exit │ w/s scroll

Press ← to exit browse mode and return to the tree.

6. Using the SQL REPL

Press Tab to enter the full-screen SQL REPL. Type any SQL query ending with ; to execute it. Tab-completion is available for SQL keywords and table names.

 SQL REPL — type a query ending with ; to execute
─────────────────────────────────────────────────────
sql> SELECT name, email FROM users WHERE active = true;

 name          │ email
───────────────│────────────────────
 Alice Johnson │ alice@example.com
 Bob Smith     │ bob@example.com
 Dan Lee       │ dan@example.com

(3 rows)

sql> 

REPL commands

7. Exporting Results

After running a query (in the REPL or by browsing a table), press e to export. You'll be prompted to choose a format:

Export format:  1) CSV  2) SQL  3) Markdown  4) JSON
> 1
✔ Exported to export.csv

From the REPL, use \export <format> directly:

sql> SELECT * FROM orders;
(42 rows)

sql> \export sql
✔ Exported to export.sql

Supported formats:

8. Dump & Restore

In the SQL REPL, you can create full database dumps or restore from a file using the native tools (pg_dump/psql or mysqldump/mysql).

Dump

sql> \dump
✔ Dumped database to dump_mydb_2026-04-10.sql

sql> \dump backup.sql
✔ Dumped database to backup.sql

Restore

sql> \restore backup.sql
✔ Restored from backup.sql

9. Saved Connections

Save a connection profile for quick reuse:

# In the REPL:
sql> \save production

# Next time, load it:
npx sqltree --saved

Profiles are stored in ~/.sqltree/connections.json with file permissions 0600 (owner-only read/write).

10. Config File

Create ~/.sqltree/config.json to set default preferences. CLI flags override config values.

{
  "pageSize": 100,
  "ascii": false,
  "timeout": 15000,
  "ssl": true,
  "keyBindings": {}
}

11. Custom Key Bindings

Override any default key binding in your config file. Each action maps to an array of keys:

{
  "keyBindings": {
    "quit":     ["q", "C-c"],
    "up":       ["up", "k"],
    "down":     ["down", "j"],
    "open":     ["right", "enter", "l"],
    "back":     ["left", "h", "backspace"],
    "repl":     ["tab"],
    "export":   ["e"],
    "refresh":  ["r"],
    "describe": ["d"],
    "scrollUp": ["w"],
    "scrollDn": ["s"]
  }
}

For example, to use Vim-style splits and add Space as a REPL trigger:

{
  "keyBindings": {
    "repl": ["tab", "space"],
    "refresh": ["r", "f5"]
  }
}

12. Tips & Tricks

ASCII mode for CI or minimal terminals

npx sqltree --ascii --uri postgresql://...

Replaces all emoji with plain text symbols — useful for CI logs, SSH sessions, or terminals without Unicode support.

SSL connections

# Enable SSL
npx sqltree --ssl --uri postgresql://...

# Skip certificate verification (self-signed certs)
npx sqltree --ssl --ssl-reject-unauthorized false --uri postgresql://...

Connection timeout

# Set a 30-second timeout
npx sqltree --timeout 30000 --uri postgresql://...

Large tables

Increase page size for fewer round-trips when browsing large tables:

npx sqltree --page-size 500 --uri postgresql://...

Custom adapters

Register your own database adapter programmatically:

import { registerAdapter } from 'sqltree/adapters';
import { MyCustomAdapter } from './my-adapter.js';

registerAdapter('mydb', MyCustomAdapter);

Supported database aliases