narwhal: one TUI, five databases, built-in MCP
narwhal (Nonanti/narwhal) is a Rust TUI database client that ships v1.0.0 today with connections to PostgreSQL, MySQL, SQLite, DuckDB, and ClickHouse in one interface. It offers vim modal editing, schema-aware completion, SSH tunnel support, headless exec mode, and a built-in MCP server — the standout feature — that exposes five JSON-RPC tools for AI agents with read-only defaults and workspace ACL scoping. The repo went public with 309 commits, indicating substantial prior private development. Five install paths available, including `cargo install narwhaldb`, Homebrew, and AUR.
You open a new project. It uses Postgres for the main app, SQLite for the local test fixtures, and DuckDB for the analytics pipeline. You've got
psql aliased, a DataGrip license you keep meaning to cancel, and a sqlite3 REPL you still can't remember how to exit cleanly. Context switching is not the bottleneck people complain about — but it compounds.narwhal shipped its v1.0.0 today 1. It's a Rust TUI database client that connects to PostgreSQL, MySQL, SQLite, DuckDB, and ClickHouse from a single interface — vim modal editing, schema-aware tab completion, Lua plugins, SSH tunnel support, and a built-in MCP server you can wire directly into Claude Code or any other MCP-compatible agent. The repo went public today with 309 commits already in it, which means this was a private project for a while before the author pushed it out. The code is noticeably more complete than most day-one releases.
Loading content card…
Install
Five paths, all working 1:
| Method | Command |
|---|---|
| cargo | cargo install narwhaldb |
| cargo-binstall | cargo binstall narwhaldb |
| Homebrew | brew tap Nonanti/tap && brew install narwhal |
| AUR (Arch) | yay -S narwhal |
| Nix flake | see README |
| Binary | download from GitHub Releases |
The binary name is
narwhal; the crates.io package name is narwhaldb — that mismatch will catch you once. Pre-compiled binaries cover Linux x86_64 and Apple Silicon (aarch64). If you're on an Intel Mac, cargo install narwhaldb is your path; the author notes in the README that the macOS-13 runner backlog on GitHub Actions is the reason the Intel binary isn't up yet 1.What the TUI gives you
The interface is built around vim modality: Normal, Insert, and Visual modes, with
: command palette. If you live in Neovim, the muscle memory transfers. Schema-aware tab completion works on table names and column names mid-query — not just at the start of a SELECT.Transactions get first-class treatment:
:begin, :commit, :rollback, and :savepoint are all supported, with a TX: active badge in the status bar so you don't accidentally leave an open transaction and lock yourself out 1. This is the kind of thing that sounds minor until you've spent 20 minutes wondering why a test won't pass because a previous interactive session left a row locked.The headless exec mode is useful for scripts:
narwhal exec -c <connection> 'SELECT ...' outputs in table, csv, json, or tsv format. You can drive it from a shell pipeline without opening the TUI at all.SSH tunnel support works directly from the connection config — declare
ssh_host and narwhal handles the port-forward, reusing your ~/.ssh/config 1. No separate tunnel setup before opening the client.Everything narwhal does — TUI queries, MCP calls, headless exec — gets appended to
~/.local/share/narwhal/history.jsonl, tagged by source. That's a clean audit trail if you're debugging what an AI agent actually ran against your database.
The MCP server is the interesting part
narwhal mcp starts a JSON-RPC stdio server that exposes five tools: list_connections, describe_schema, describe_table, run_query, and explain_query 1. Any MCP-compatible agent (Claude Code, Cursor, anything using the MCP protocol) can connect to it and query your databases directly.The defaults are conservative. The MCP server is read-only unless you explicitly change that. There's a three-layer SQL guard and a workspace ACL file at
.narwhal/workspace.toml that controls which connections the MCP server can see. So you can give an AI agent access to your dev database without worrying it'll discover your prod credentials are also in the config.A concrete flow: you're debugging a query that's behaving differently than expected. Instead of copy-pasting schema definitions and sample rows into the chat context, you point Claude Code at the narwhal MCP server, and the agent calls
describe_table and run_query directly. The schema context is accurate, not hand-typed. The agent's suggestions reflect what's actually in the database, not what you thought was in it.Loading content card…
Lua plugins and extensibility
There's a Lua plugin runtime: drop
.lua files in ~/.config/narwhal/plugins/ and they load on startup 1. The repo ships with ARCHITECTURE.md, CONTRIBUTING.md, and SECURITY.md — docs that usually show up after a project has run into the problems those documents address.The plugin system is v1.0.0 territory, meaning the API will probably shift. But having the extension point there on day one matters for a tool in this category — DBA teams and power users accumulate a lot of workflow-specific shortcuts.
What to calibrate for
4 stars on the day it went public. No Hacker News thread, no Reddit discussion — nothing in the community signal layer yet 1. The 309 commits tell you the tool is more mature than a typical new repo, but you're still among the first people to actually run it publicly. Expect rough edges the author hasn't encountered yet.
Intel Mac binary is missing. The pre-built binary for x86_64-apple-darwin isn't up yet — CI runner backlog.
cargo install narwhaldb works, but adds compile time 1.Dual license: MIT or Apache-2.0. Pick whichever fits your project's licensing constraints. Both are permissive 1.
Bottom line: if you regularly touch more than one database type, narwhal's single-TUI approach cuts the per-database tool-switching overhead. The MCP server is the part worth evaluating even if you don't end up adopting the TUI long-term — a read-only, ACL-scoped MCP bridge to your actual database schema is genuinely useful for AI-assisted development workflows. At 309 commits on v1.0.0, the foundation is there. The community adoption will tell you whether the rough edges get filed down quickly.
Cover image: AI-generated illustration
References
- 1GitHub: Nonanti/narwhal
github.com
This story was produced automatically by a channel. One sentence is all it takes for Neodrop to keep producing for you.