QueryVault

A desktop home for the SQL you run every day — save queries with notes and parameters, run them against Oracle behind guard rails, and watch results over time. Free and open source.

Visit Website · Download · Walkthrough · Features · Quick start · Contributing

---

Why

Everyone who works with SQL — support engineers, developers, analysts, DBAs — runs on tribal queries. The right one lives in a text file on someone's desktop, a chat scroll, or one colleague's memory. When that person is away, everyone else re-derives it: slowly, and sometimes dangerously, against production.

QueryVault makes those queries first-class — documented, searchable, and executed behind guard rails. It's a local-first desktop app: your library and credentials never leave your machine, and there's no telemetry.

Download

Grab the latest installer from the Releases page:

Platform	File
macOS (Apple silicon / Intel)	.dmg
Windows (x64)	.exe (NSIS installer), portable .exe, or .zip
Linux	.AppImage (x64 / arm64) or .deb (x64)

Builds are unsigned — on macOS, if Gatekeeper flags the app as "damaged" or "broken", clear the quarantine flag and apply an ad-hoc signature:

# 1. Remove Gatekeeper quarantine attribute
sudo xattr -rd com.apple.quarantine "/Applications/QueryVault.app"

# 2. Apply ad-hoc code signature (required for Apple Silicon M1/M2/M3/M4)
codesign --force --deep --sign - "/Applications/QueryVault.app"

On Windows dismiss the SmartScreen prompt. No database needed to try it: the app ships with a built-in demo dataset of 250,000 rows.

Walkthrough

Sixteen slides, captioned, on a loop.

Prefer to click through at your own pace? screenshots/index.html is a self-contained slider with a scrubber, arrows and ← → keys — open it locally (open screenshots/index.html) or publish screenshots/ with GitHub Pages. Individual stills are below.

Dark and light

Dark	Light

Every screen, one by one

	Library — full-text search across titles, SQL, notes and tags; tag chips filter on top.
	Schema Navigator — object tree (Tables, Views, Packages, Procedures, Sequences, Synonyms, DB Links) & Other Users multi-schema browsing.
	Bind parameters — prompted at run time, remembered per query.
	Execution preview — the exact statement and bind values, before anything runs.
	Safety guard — anything that isn't a SELECT needs typed confirmation.
	Pending transaction — nothing commits itself; Commit or Rollback, deliberately.
	Review changes — every uncommitted statement, the rows it affected, and old → new for cell edits.
	Commit asks first — totals stated, with Roll back instead offered beside it.
	Edit cells in place — low-cardinality columns offer their known values.
	Copy anything — text, CSV, JSON or Markdown; whole row or column.
	Snapshots — a CSV per run, with a row-count trend over time.
	History — every run with its SQL and the bind values it used.
	Read-only profiles — writes refused in the backend, not just the UI.
	First launch — it asks what to call you, under a sky that tracks your day.

Features

Keep a library

• Save once, reuse forever — every query keeps a title, markdown notes, tags and its run statistics.
• Full-text search — SQLite FTS5 across titles, SQL, notes and tags; tag chips filter on top.
• Bind parameters — named binds like :customer_id are detected outside strings and comments, prompted at run time, and remembered per query.
• Share it — export the library (title, SQL, notes, tags, profile name) to JSON; import merges and skips duplicates. Passwords, bind values and run stats never travel.

Execute with confidence

• Nothing commits itself — writes run with autocommit disabled on a long-lived connection. The status bar turns amber with a live pending indicator until you press Commit; Rollback undoes everything, and quitting rolls back too.
• Review before you commit — click the pending indicator to see every uncommitted statement: how many rows each affected, its bind values, and — for in-grid edits — the exact old → new value and which row changed. Commit is never one click from the status bar: it opens a confirmation stating the totals, with Roll back instead offered beside it.
• Safety guard — anything that isn't a SELECT needs typed confirmation: type RUN, or the profile name on a red dialog when the profile is tagged prod.
• Read-only profiles refuse writes outright — enforced in the background process, not just greyed out in the UI.
• Preview before you run — a header toggle shows the exact normalized statement and its bind values, with Execute / Cancel. Either way, history records what ran.

Explore & edit

• Object Navigator Tree — Oracle SQL Developer-style object hierarchy with independent, asynchronous node expansion for Tables, Views, Packages, Procedures, Functions, Sequences, Synonyms, and Database Links.
• Other Users (Multi-schema browsing) — Expand and explore database objects across other user schemas (ALL_USERS & ALL_OBJECTS).
• Tabbed Table Schema Inspector — Click any table or view to inspect Columns (nullability, default values, PK/FK badges, comments), Data Preview (live 100-row sample grid), Constraints (Primary Keys, Foreign Keys, Unique, Check conditions), Indexes, Triggers, Grants, Statistics (row count, block count, last analyzed timestamp), and SQL (DDL) script generation via DBMS_METADATA.GET_DDL with 1-click copy.
• Autocomplete — SQL keywords, schema tables/columns, and the binds in your buffer.
• Run selection or statement at cursor (⌘⏎ / Ctrl+⏎), so multi-statement scratch pads behave like any SQL IDE.
• Edit cells in place — single-table SELECTs become editable; low-cardinality columns offer a dropdown of their values. Each edit is a parameterised UPDATE (refused unless exactly one row matches) that joins the pending transaction.
• Monaco editor — the VS Code core, with SQL highlighting in dark and light themes.

Work with results

• Fast grid — virtualized, streaming in 5,000-row batches with Load more and a 50,000-row display cap, so the renderer never holds unbounded rows. Cancel works mid-statement and mid-pagination.
• Copy anything — select a range and ⌘C, or right-click for CSV, JSON, Markdown, whole row or whole column.
• Export & snapshot — CSV export streams every row to disk regardless of the display cap; snapshots chart a row-count trend per query, so you can watch a backlog shrink over days.
• Full history — every run logged with its SQL and the bind values it used.

Connect securely

• Oracle 12.1+ over plain TCP via node-oracledb Thin mode — no Instant Client, no native libraries, nothing to install.
• Local-only credentials — passwords are encrypted with your OS keychain (macOS Keychain, Windows DPAPI) and only ever used in the background process; plaintext never touches disk and never reaches the UI layer.
• Hardened shell — sandbox: true, contextIsolation: true, nodeIntegration: false; the UI reaches the backend through one typed invoke().
• No phoning home — no telemetry, no accounts, no analytics. The app makes no network calls except to the Oracle databases you configure. The ambient sky behind the greeting is drawn entirely from your system clock — no location lookup, no weather service, no third-party requests of any kind.
• Reset — wipe every query, credential and setting from Help → Security notes.

Quick start

Install from Releases, open the app, and it boots straight into the demo dataset — example queries, history and snapshots included, no database required. When you're ready, add a connection via Manage… → New profile.

The bundled demo queries target the SQLite demo dataset, so a few use SQLite idioms (LIMIT, date('now', …)). On Oracle you'd write FETCH FIRST … ROWS ONLY / SYSDATE.

Development

Requires Node.js 24+.

git clone https://github.com/rajeshkumaravel/queryvault.git
cd queryvault
npm install
npm run dev          # launch with hot reload
npm run typecheck    # tsc for main + preload + renderer
npm run test:ui      # drive the real app end-to-end (~23 scenarios)

npm run test:ui launches the actual Electron app with Playwright in an isolated data directory and walks the whole feature set. Screenshots land in /tmp/qv-shots/ — useful for reviewing UI changes.

Try it against a real database

No Oracle handy? The demo dataset covers every screen. To point at a real instance, add a profile with host / port / service name / username / password and hit Test connection. Tag it dev / stage / prod — the badge follows the profile, and prod turns the safety guard red.

Build production installers

npm run build        # -> dist/  (.dmg on macOS, .exe on Windows)

CI builds macOS and Windows in parallel and attaches the installers to a GitHub Release — see .github/workflows/release.yml. Cutting a release is: bump version in package.json, commit, push to main. Pushing a tag (git tag v0.1.0 && git push origin v0.1.0) works too.

Code signing — builds are unsigned (identity: null in electron-builder.yml). To sign, set mac.identity to a "Developer ID Application" certificate and add notarization credentials.

Where your data lives

macOS	Windows
~/Library/Application Support/QueryVault/	%APPDATA%\QueryVault\

queryvault.db (profiles, queries, tags, bind memory, history, settings, FTS5 index) · demo-data.db (regenerates on launch) · snapshots/<query-id>/*.csv. Deleting the folder resets the app to a fresh, re-seeded state. Legacy note: portracker-data/portracker.db is historical and unused by the current runtime.

Tech stack

Electron · electron-vite · React · TypeScript (strict) · node-oracledb (Thin mode) · better-sqlite3 (local store, FTS5, demo data) · Monaco (SQL editor) · TanStack Virtual · Zustand · Playwright (end-to-end verification)

Project layout

src/
  shared/        types.ts, ipc.ts, sqlAnalysis.ts  — types, typed IPC, binds + statement guard
  main/
    db/          adapter.ts, oracleAdapter.ts, demoAdapter.ts, executionManager.ts
    store/       sqlite.ts                         — local store, migrations, FTS5, seed
    credentials.ts, csv.ts, ipc.ts, index.ts
  preload/       index.ts                          — single typed invoke bridge
  renderer/src/
    components/  TopBar, Sidebar, EditorPane, ResultsPane, DetailsPanel, dialogs/…
    state/       store.ts                          — zustand app state

All database work lives in main/; the renderer only ever calls window.api.invoke('channel', …), typed end-to-end by src/shared/ipc.ts.

Every backend implements one DatabaseAdapter interface — the real Oracle client and the in-memory demo dataset are two implementations of it. Adding SQL Server or Postgres means writing a third; the UI, execution manager, CSV export and history don't change.

Screenshots & walkthrough

Everything in screenshots/ is generated from the end-to-end suite, so the docs can't drift from what the app actually renders:

npm run test:ui                        # writes the raw screenshots
python3 scripts/make-walkthrough.py    # curates them + builds the GIF and slider

The script owns the slide order and captions; it emits the numbered stills, walkthrough.gif, and the self-contained index.html slider. (Maintainer tool — needs Pillow. The outputs are committed, so contributors never need to run it.)

App icons

Icons live in resources/ (icon.icns for macOS, icon.ico for Windows, icon.png as the master) and are generated from the vector source resources/icon.svg:

npm run icons   # .icns generation is macOS-only (sips + iconutil)

In dev, scripts/dev-app-name.mjs (run from postinstall) also brands the Electron shell so the Dock shows QueryVault instead of Electron.

Roadmap / non-goals

QueryVault speaks Oracle today. Other engines are a matter of writing one DatabaseAdapter — contributions welcome. It is not a schema-migration tool, a BI dashboard, or a database admin console; it's a place to keep and safely run the queries you already write.

Ideas and PRs very welcome for: TCPS/wallet connect strings, more database adapters, snapshot diffing, result-grid filtering, and Linux packaging.

Contributing

Contributions are welcome — bug reports, feature ideas, docs fixes and code. See CONTRIBUTING.md for setup, the PR checklist, and project conventions. Good first steps:

• Open an issue for a bug or feature
• Check the issue tracker for something to pick up

Found a security issue? Please report it privately — see SECURITY.md.

License

MIT — free to use, modify and distribute.