The first SQLite viewer designed to be driven by coding agents and humans — at the same time.
Why · Install · Quick start · For agents · Architecture · Design · Roadmap
Every other SQLite tool was built for one kind of user: a developer sitting at a keyboard. sqlv was built for a developer plus their coding agent — both inspecting the same database, watching the same results pop into the same window, arguing about the same query.
- CLI-first, JSON-first.
sqlvis a proper command-line tool with stable exit codes, JSON output, and a SKILL.md that teaches any LLM agent how to drive it safely.sqlv query ... | jqjust works. - A native desktop app that listens.
sqlv push "<SQL>"sends a query from your terminal into the running desktop window — the SQL appears in the editor, the grid renders the result, and the human next to you sees exactly what the agent just did. Nothing about this flow exists in TablePlus, DB Browser, DataGrid, orsqlite3. - Fast by default, safe by default. Databases open read-only until you flip a toggle. The toggle puts a warning strip across the top of the window so you can't forget. Writes from the CLI require an explicit
--writeflag. - Pure SQLite. No support for Postgres or MySQL, ever. We're not another Beekeeper — we're the best tool for local SQLite files.
| sqlv | TablePlus / Beekeeper / DBB | sqlite3 CLI | |
|---|---|---|---|
| Browse rows, edit cells, run queries | ✅ | ✅ | ❌ |
| JSON-first CLI with stable exit codes | ✅ | ❌ | |
Agent skill file (SKILL.md) |
✅ | ❌ | ❌ |
CLI ↔ GUI live sync (sqlv push) |
✅ | ❌ | ❌ |
| MCP server (stdio) | ✅ | ❌ | ❌ |
| Read-only safe default, OS-enforced | ✅ | ❌ | |
| Pure open source (MIT), one binary | ✅ | ❌ (paid / freemium) | ✅ |
brew install shizhigu/sqlv/sqlvgit clone https://github.com/shizhigu/sqlite-viewer
cd sqlite-viewer
# CLI
cargo install --path crates/cli
sqlv --version
# Desktop app (dev)
cd apps/desktop && bun install && bunx tauri devGrab the latest release from the Releases page:
sqlv-v0.1.0-x86_64-apple-darwin.tar.gzsqlv-v0.1.0-aarch64-apple-darwin.tar.gzsqlv-v0.1.0-x86_64-unknown-linux-gnu.tar.gzsqlv-v0.1.0-x86_64-pc-windows-msvc.zipSQLite-Viewer-0.1.0.dmg(desktop app, macOS)
# Try it against the included sample (46k rows, e-commerce-like schema)
sqlv tables --db samples/ecommerce.sqlite
# Describe a table
sqlv schema --db samples/ecommerce.sqlite orders
# Ad-hoc query with parameters
sqlv query --db samples/ecommerce.sqlite \
"SELECT name, total_spent FROM customers WHERE total_spent >= ?1 LIMIT 5" \
-p 100000
# Full dump
sqlv dump --db samples/ecommerce.sqlite --schema-only > schema.sqlOpen the desktop app, then from any terminal:
sqlv push-open samples/ecommerce.sqlite
sqlv push "SELECT name, total_spent FROM v_top_customers"The desktop app:
- Opens the file and populates the sidebar.
- Switches to the Query tab.
- Renders your SQL in the editor.
- Runs it and shows the grid.
- Flashes a
↓ pushed from CLIbadge in the toolbar.
You see exactly what your agent did. No screen-sharing, no "paste it in chat" — same window, both of you.
┌────────────────────────┐ ┌──────────────────────┐
│ Claude Code (agent) │ │ sqlv GUI │
│ ▸ sqlv push "..." ──┼──HTTP 🔒──▶│ Query tab updates │
│ │ │ ↓ pushed from CLI │
│ ◀── JSON result ─────┼─────────── │ Grid re-renders │
└────────────────────────┘ └──────────────────────┘
Agent's view Your view
(JSON) (same data)
sqlv ships with a SKILL.md that onboards any LLM agent in seconds:
- When to reach for
sqlv(and when not to). - The discovery workflow (
tables → schema → query). - How to handle errors by
code, not message. - How to get user consent before any write.
- Recipes for common agent tasks.
With Claude Code: drop the SKILL.md into your project or user skills directory and the agent will auto-invoke sqlv when the user references a .sqlite / .db file.
With MCP-aware hosts (Claude Desktop, Cursor, Windsurf, Zed): run sqlv mcp as a stdio server; all the CLI's capabilities appear as structured tools your agent can call directly.
┌────────────────────────────────────────────────────────────┐
│ Your workflow │
├───────────────┬──────────────────────┬─────────────────────┤
│ CLI (sqlv) │ Desktop (Tauri) │ MCP server (sqlv) │
│ clap + stdout│ React + CodeMirror │ stdio / JSON-RPC │
├───────────────┴──────────────────────┴─────────────────────┤
│ sqlv-core (shared Rust library) │
│ • Db::open / read-only or read-write │
│ • Typed schema introspection (tables, views, indexes, FK) │
│ • Parameterized query + exec │
│ • Stats, pragma (injection-safe), dump │
│ • Value enum with JSON-stable serialization │
├────────────────────────────────────────────────────────────┤
│ rusqlite (bundled SQLite) │
└────────────────────────────────────────────────────────────┘
One Rust core, three frontends. A query run through the CLI, the desktop, or MCP hits the same code path — so the semantics can't diverge.
sqlv open | tables | views | indexes | schema | query | exec | stats | pragma | dumpsqlv push | push-open— live-mirror into the running desktop app--jsonfirst; TTY-detection makes it automatic for pipes- Stable exit codes:
0ok,2usage,3not-found,4readonly,5sql - Structured errors on stderr:
{"error": {"code":"sql", "message":"..."}}
- Sidebar schema tree with filter — tables, views, and attached databases (ATTACH-ed files appear as their own collapsible groups)
- Browse tab — virtualized grid (1000 rows/page,
@tanstack/react-virtual), inline cell edit, FK navigation, add / delete rows - Staged changes — flip the
Stagetoggle and all grid edits queue into a pending-changes panel with per-row revert and one-click bulk commit (single transaction, atomic rollback on failure) - Query tab — CodeMirror SQL editor with schema-aware completion, folding, parameterized queries, live "≈ N rows match" ghost annotation for simple
SELECT … WHERE …shapes - Agent preview banner — when an agent pushes a mutating query, the SQL lands in the editor behind a loud warning banner with EXPLAIN QUERY PLAN + an "affects N rows in
<table>" pill; nothing runs until the human clicks Run - Cancel query — a live Cancel button in the toolbar interrupts the running statement via
sqlite3_interrupt(also exposed asPOST /cancelon the local HTTP server) - Schema tab — structured columns / FK / indexes / triggers / CREATE-statement view
- Activity drawer — two tabs: a live in-session feed and the persistent
~/.sqlv/activity.db(shared with the CLI'ssqlv history), with grep + per-DB filtering and one-click replay - Light / dark / auto theme, ⌘+ ⌘− zoom, ⌘1/⌘2/⌘3 tab shortcuts, ⌘P history, ⌘S saved queries
- Read/write toggle with a 3-px warning strip across the window — you can't forget you're in write mode
- Smooth Bézier-curve motion throughout (respects
prefers-reduced-motion)
SKILL.mdwith triggers, recipes, and safety rules- MCP stdio server for Claude Desktop / Cursor / Windsurf / Zed
- Auth-token'd HTTP loopback for the
sqlv push/sqlv push-open/sqlv cancelpipeline - Every query, exec, open, and cancel (from UI, CLI, or MCP) lands in
~/.sqlv/activity.db— one shared timeline across all three surfaces
Want to try without a real DB? The repo includes a ~52k-row e-commerce sample:
python3 scripts/make_sample.py # regenerate (deterministic)
sqlv stats --db samples/ecommerce.sqlite9 tables, 3 views, composite PKs, FK cascades, BLOBs, and a sprinkle of Unicode. Built to exercise every interesting code path in the viewer.
| Shipped | CLI, desktop app, SKILL.md, push / push-open / cancel, MCP server, transactional writes, streaming query mode, schema-aware completion, query history + saved queries, FK navigation, CSV / JSON import, schema diff, persistent activity log (CLI + UI + MCP), attached DBs (ATTACH DATABASE), EXPLAIN QUERY PLAN preview + affected-rows estimate, virtualized grid, staged-changes panel, live row-count ghost, Bézier motion, light / dark / auto theme |
| Next | Multi-DB tabs (open N files at once), schema editor GUI, CSV / JSONL export from the grid, column sort + per-column filter |
| On purpose, not happening | Postgres / MySQL / remote databases (use a different tool) |
See open issues for specifics.
We'd love your help. See CONTRIBUTING.md for the dev loop, coding standards, and how to propose changes. First-time contributor? Grab an issue labelled good-first-issue.
Key entry points:
docs/DESIGN.md— authoritative UI spec; UI work flows through here firstskills/sqlite-viewer/SKILL.md— how agents are onboardedcrates/core/— shared Rust library, well-testedapps/desktop/— Tauri + React + CodeMirror
Run the tests:
cargo test --workspace # Rust: 124 tests across core + CLI
cd apps/desktop && bun run test # Frontend: 30 tests on SQL buildersMIT — do what you want, no warranties. See SECURITY.md for vulnerability reporting.
Built in the open by @shizhigu. If sqlv saves you a frustrating afternoon, star the repo — that's how other people find it.