github.com/Nonanti/narwhal @v2.3.0

# narwhal

The agent-native database workbench for the terminal. A DBA toolkit, an MCP server, and a vim-mode SQL editor — in one static binary.

Install · Quick start · Why narwhal · Docs

What is narwhal?

narwhal is a terminal database client built around two things every other client misses:

1. DBA-grade tooling, not a toy REPL. Schema diff with dialect-aware DDL emit, append-only audit log, capability-gated plugin sandbox, streaming cancellable queries, ER diagrams, SSH tunnels, secret vault — the operational surface a real database day needs.
2. First-class agent integration. A built-in MCP server exposes your connections, schema, and query execution to Claude, Cursor, Zed, and any MCP-aware client. No proxy, no adapter — narwhal mcp and you're wired.

Six engines (Postgres, MySQL, SQLite, DuckDB, ClickHouse, SQL Server), three editor modes (vim / basic / emacs), one static binary.

Install

curl -fsSL https://github.com/Nonanti/narwhal/releases/latest/download/install.sh | sh

Other channels — cargo install narwhaldb, Homebrew, AUR, Nix flake, prebuilt tarballs — are listed in docs/install.md.

Quick start

narwhal                                    # launches the TUI

Inside:

1. :add — connection wizard, or :url postgres://user:pass@host/db
2. :open <name> — connect; the sidebar fills with schemas and tables
3. F6 — run the buffer; results stream into the lower pane
4. F1 — full keymap

Headless:

narwhal exec --conn prod 'SELECT count(*) FROM orders' --format json

Agent-native: wire it to your editor

narwhal embeds an MCP server over stdio. Run it once and your AI assistant can browse schema, sample data, and run queries against your saved connections — with the same read-only / per-connection guards the TUI uses.

narwhal mcp --read-only

Claude Desktop (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "narwhal": {
      "command": "narwhal",
      "args": ["mcp", "--read-only"]
    }
  }
}

Cursor, Zed, Continue, Aider, and custom clients work the same way. Full setup: docs/mcp.md.

Database support

Highlights

• Six engines, one TUI. Switch with :open, every driver speaks the same Connection trait — same streaming, same cancellation, same schema introspection.
• Three editor modes. vim (with motions, text objects, registers, marks, macros), basic (modeless), emacs — sharing one buffer.
• Full mouse. Click, drag-select, double / triple-click word and line, middle-click paste, right-click context menu.
• Schema tooling. ER diagrams in the terminal, :schema-diff between two connections with dialect-aware DDL emit (Postgres ↔ MySQL ↔ MSSQL ↔ generic).
• Plugins. Lua (trusted, fast) and WASM (sandboxed, capability-gated filesystem / network / clipboard) — the same surface used by the built-ins.
• Streaming, cancellable. Rows arrive incrementally; Ctrl-C cancels mid-run on every backend that supports it.
• Secrets. Vault, 1Password, OS keyring, ~/.pgpass — no plaintext-on-disk fallback.
• Audit log. Append-only JSONL with redaction rules, suitable as compliance evidence.
• Inline output. Charts, pivot tables, JSON viewer, row detail pane, exports to CSV / JSON / Markdown / Parquet.
• SSH tunnels. Single config block, no ~/.ssh/config plumbing required.

Documentation

Contributing

Issues and PRs welcome. See CONTRIBUTING.md. Commit messages follow Conventional Commits; the four CI checks (fmt, clippy -D warnings, doc -D warnings, test) must pass.

License

Dual-licensed under MIT and Apache 2.0, at your option.