Skip to content
QuerybaraQuerybara

Installing and running

  • CLI

querybara is the command-line tool that runs the same engine as the desktop app, without a window. Use it in scripts and CI jobs to test connections, run SQL, compare and sync databases, move data, and back up and restore. It reads and writes the same saved connections as the desktop app.

Requirements

Section titled “Requirements”
  • Node.js 22.13 or later. Parquet files with ZSTD compression need Node.js 22.15 or later.
  • pnpm 10. Run corepack enable in the checkout to pick up the pinned version.

Build the CLI

Section titled “Build the CLI”

The CLI is built from the Querybara source. From the root of the checkout:

Terminal window
pnpm install
pnpm --filter @querybara/cli build
node apps/cli/dist/querybara.mjs --help

The build writes one file, apps/cli/dist/querybara.mjs. The database drivers (pg, mysql2, mongodb, ioredis) and the SSH and SOCKS libraries are not bundled into it; pnpm install puts them in the workspace. Run the file from the checkout you built it in.

In this reference, querybara stands for node apps/cli/dist/querybara.mjs. To type it the short way, define a shell alias from the checkout root:

Terminal window
alias querybara="node $PWD/apps/cli/dist/querybara.mjs"
querybara --version

Saved connections

Section titled “Saved connections”

The CLI shares the desktop app’s local store, so every connection you save in the app is a target you can name on the command line:

Terminal window
querybara test shop-prod
querybara query shop-prod -e "select count(*) from shop.orders"

By default the CLI opens the store where the desktop app keeps it, the file querybara.db in the app’s data folder:

System Default store
Linux ~/.config/Querybara/querybara.db (or $XDG_CONFIG_HOME/Querybara/querybara.db)
macOS ~/Library/Application Support/Querybara/querybara.db
Windows %APPDATA%\Querybara\querybara.db

To use another store, pass --store <path> or set QUERYBARA_STORE. The CLI picks the first of:

  1. --store
  2. QUERYBARA_STORE
  3. QUERYBARA_USER_DATA_DIR (the desktop app’s own data folder override), with querybara.db inside
  4. the default above

When --store or QUERYBARA_STORE names an existing folder, the CLI uses querybara.db inside it.

Terminal window
querybara --store ./ci-store.db profiles list
QUERYBARA_STORE=/srv/querybara/store.db querybara test shop-staging

Commands that only read, such as profiles list or resolving a profile name, do not create a store that does not exist yet. A CI job that only uses connection URIs leaves no store file behind.

Passwords on the command line

Section titled “Passwords on the command line”

The desktop app seals saved passwords with the OS keychain, which the CLI cannot open. When the CLI needs a password for a saved profile, it takes the first of:

  1. a password the CLI itself saved, sealed with QUERYBARA_PASSPHRASE
  2. QUERYBARA_PASSWORD_<NAME> for that profile, then QUERYBARA_PASSWORD
  3. a hidden prompt, when a terminal is attached

A password in a connection URI is used for that run only and never stored. See Global options and environment for every variable.

Section titled “Related”

Documents Querybara 0.1.1 · built frombc9f5aa