Skip to content

v1.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 27 May 14:42
· 140 commits to main since this release
v1.0.0
17240e7

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

demo

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.

Assets 6
Loading