v2.3.0

narwhal v2.3.0

The agent-native database workbench, now sharper end-to-end.

This release is the agent-native one. The README, the docs, and the
internals all converge on the same story: one binary that does DBA
work and speaks MCP to your editor.

Highlights

• 🤖 Agent-native repositioning. narwhal mcp is now a first-class
  product surface. Point Claude / Cursor / Zed at it and the agent
  can list_connections → describe_schema → run_query against
  your saved databases — read-only, sandboxed, every call wrapped
  in a ROLLBACK.
• 📚 Documentation rewritten end-to-end — install, configuration,
  MCP, plugins, schema diff, upgrading.
• 🛡 No more panics in production paths. Every unwrap() and
  expect() on a fallible operation in driver setup, audit sinks,
  dispatch routing, and config loading is gone. Errors now surface
  cleanly instead of taking the process down.
• 🧱 Big internal refactor. Pure state, value, and view types
  moved out of narwhal-tui / narwhal-app into narwhal-domain.
  The TUI crate is now a thin renderer over the domain model.
  Legacy per-driver crate trees are gone.

See CHANGELOG.md for the full list.

Install

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

Or cargo install narwhaldb, the Nix flake, prebuilt tarballs in
this release, or brew/AUR (see docs/install.md).

Wire it to your editor

narwhal mcp --read-only

Claude Desktop, Cursor, and Zed configs are documented in
docs/mcp.md.

Engines

Postgres, MySQL, SQLite, DuckDB, ClickHouse, SQL Server — one binary.

Compatibility

Drop-in replacement for v2.2.0. No config migration required.

Full changelog: v2.2.0...v2.3.0

v2.2.0

Full Changelog: v2.1.0...v2.2.0

v2.1.0

Full Changelog: v2.0.0...v2.1.0

v2.0.0

Full Changelog: v1.2.0...v2.0.0

v1.2.0

Full Changelog: v1.1.0...v1.2.0

v1.1.0

What's Changed

• chore(ci): bump actions/checkout from 4 to 6 by @dependabot[bot] in #3
• chore(deps): bump tokio-postgres-rustls from 0.13.0 to 0.14.0 by @dependabot[bot] in #8
• chore(deps): bump the patch-updates group across 1 directory with 2 updates by @dependabot[bot] in #7

New Contributors

• @dependabot[bot] made their first contribution in #3

Full Changelog: v1.0.0...v1.1.0

v1.0.0

First public release of narwhal — a TUI database client with a built-in MCP server.

Highlights

• Built-in MCP server. narwhal mcp runs a Model Context Protocol JSON-RPC server on stdio. Any MCP-capable agent (Claude Desktop, Cursor, Continue, Aider, your own) gets list_connections, describe_schema, describe_table, run_query, explain_query. Read-only by default with a three-layer SQL guard and a workspace ACL (.narwhal/workspace.toml).
• Five databases, one binary. Postgres, MySQL, SQLite, DuckDB, ClickHouse. The default feature set installs Postgres + SQLite; opt into the rest with cargo install narwhaldb --features all-drivers.
• Vim editing + completion. Modal Normal / Insert / Visual, schema-aware tab-completion, alias-resolved column hints, a proper : command palette.
• Lua plugin runtime. Drop a .lua file in ~/.config/narwhal/plugins/ and it is live. Sandboxed via timeout; reject during open transactions.
• Headless exec mode. narwhal exec -- "SELECT ..." with table / csv / json / tsv output. The --read-only flag refuses row-level DML across the entire process.

Install

# Cargo (any platform with Rust)
cargo install narwhaldb

# Cargo binstall (prebuilt binary, no toolchain needed)
cargo binstall narwhaldb

# Homebrew tap (macOS, Linuxbrew)
brew tap Nonanti/tap
brew install narwhal

# Nix flake
nix run github:Nonanti/narwhal

Prebuilt tarballs for x86_64-unknown-linux-gnu and aarch64-apple-darwin are attached below. Intel Mac users: cargo install narwhaldb for now; the prebuilt Intel binary lands once the macos-13 free-runner backlog clears.

crates.io workspace

The binary crate ships as narwhaldb because the bare narwhal slot was squatted in 2018. The 19 library crates use the natural prefix: narwhal-core, narwhal-app, narwhal-mcp, narwhal-tui, narwhal-driver-postgres, and so on. The installed command name is still just narwhal.

What's inside

• 20 crates, ~48 K LOC of Rust
• 830 passing tests, 17 driver-integration tests gated behind docker
• #![forbid(unsafe_code)] in every crate
• clippy -D warnings + pedantic + nursery clean
• Three-layer MCP guard against PG_SLEEP/SLEEP/backtick-bypass and write-by-default
• Atomic writes + 0600 perms for last_used.toml
• Full TLS chain + hostname verification from prefer upward
• SSH tunnels shell out to OpenSSH (inherits ~/.ssh/config, agent, FIDO2)
• pgpass + OS keyring + ${env:VAR} interpolation + pre-connect command capture

See CHANGELOG.md for the full per-component breakdown.

Security

Disclose privately via SECURITY.md. The default narwhal mcp posture is read-only; opt into writes with read_only=false plus a workspace ACL that says allow_writes = true.

Thanks

Built by @Nonanti. Bug reports, PRs, and :show-hn-shaped feedback all welcome.