dbqm — Database Query Manager

A fullscreen terminal app and a scriptable CLI for running SQL across Oracle, SQL Server, PostgreSQL, MySQL and SQLite — from one place, with one set of saved connections.

Built with Textual. Credentials are encrypted at rest; nothing is ever written to your shell history.

📖 Full documentation on GitHub

Install

pip install dbqm

Python 3.10+. Database drivers come with it, and SQLite needs none — it is in the standard library, so dbqm connection add local --type sqlite --database ./app.db --no-password works on a fresh install with nothing else to set up.

Windows on ARM: some drivers have no win-arm64 wheel and are skipped automatically. Use Python AMD64 (it runs under x64 emulation) — see the installation notes.

Oracle connections additionally need the Oracle Instant Client. dbqm can download and install it for you from Settings › Oracle Instant Client.

pip install "dbqm[mcp]" additionally installs the MCP server for AI agents (dbqm mcp) — see docs/MCP.md.

Use it interactively

dbqm tui

An eight-tab dashboard (F1–F8): collect, connections, objects, multi-exec, history, settings, queries and tools. Fully keyboard-driven, dark and light themes.

On first use it creates ~/.dbqm/, generates an encryption key and walks you through your first connection. A bare dbqm, no arguments, prints the help instead of opening this.

Use it from a script

Every command but dbqm tui is non-interactive — no prompts, no TTY required, and -f json everywhere — which is what makes dbqm usable from a script, from CI or from an AI agent. dbqm describe-cli -f json reports the whole surface, read live from the parser.

# Create a connection -- one shape per engine, the password piped rather
# than passed in argv, and the port defaulted when you leave it out
# (1433 SQL Server, 3306 MySQL, 5432 PostgreSQL, 1521 Oracle).
echo "s3cret" | dbqm connection add mssql-prod --type sqlserver \
    --host sql.example.com --database Sales --user sa --password-stdin

echo "s3cret" | dbqm connection add mysql-prod --type mysql \
    --host db.example.com --database shop --user app --password-stdin

echo "s3cret" | dbqm connection add prod --type oracle --mode direct \
    --host db.example.com --port 1521 --service ORCL --user admin \
    --password-stdin --test

# Run SQL. -f json for a machine, -f raw to pipe a CLOB somewhere else.
dbqm sql "SELECT * FROM orders WHERE status = :s" prod -p s=PAID -f json

# Save a query once, run it with different parameters later.
dbqm run open-orders -p start_date=2026-01-01

# Compare the same logical query across environments.
dbqm run-group daily-reconciliation -p day=2026-01-01

# Or compare one ad-hoc statement across connections -- including across
# DIFFERENT ENGINES -- without saving anything. Exits 5 when they diverge,
# so a script can branch on the verdict.
dbqm multi "SELECT id, total FROM orders WHERE day = :d" \
    -c oracle-prod -c postgres-replica -p d=2026-01-01 -f json

# Call an Oracle routine, with OUT parameters and the return value as data.
dbqm call PKG_BILLING.CLOSE_MONTH <conn> -p p_month=1 --commit -f json

# Get an execution plan in one step (no EXPLAIN PLAN FOR boilerplate).
dbqm sql "SELECT * FROM orders WHERE customer_id = :id" prod --explain -p id=42

# See a database's shape: what exists, one object's columns/keys/indexes,
# and a table's rows, paged.
dbqm objects prod --type TABLE
dbqm describe orders prod
dbqm rows orders prod --limit 20

# Extract DDL, browse connections, review history.
dbqm ddl PKG_BILLING prod
dbqm connection list -f json
dbqm history -n 20

--help on any command lists its flags.

What it does

Saved queries with parameters, organised in folders, with favourites and a value mapping for codes that differ between systems.
Cross-database comparison — run the same logical query against several connections and get a per-row OK / DIFF / ABSENT verdict, as a table or an interactive HTML report.
Object browser — tables, views, routines and Oracle packages: columns, primary keys, foreign keys and indexes, without writing catalogue SQL. Works on every engine, SQLite included, which makes it a zero-setup way to try the whole tool against a local file.
Ad-hoc SQL — SELECT, CTEs, DML, DDL with compilation-error detection, and anonymous PL/SQL blocks with DBMS_OUTPUT captured and shown.
Execute routines — packages, procedures and functions, with parameter input and output capture.
Package editor for Oracle PL/SQL, with inline compilation errors.
Read-only connections — mark a connection so dbqm refuses anything but a query on it, with a one-invocation --force-write override for dbqm sql.
Exports — CSV, JSON, TXT, SQL and HTML reports, plus IDE-style execution evidence (the SQL, the connection, the timestamp, the outcome) for an audit trail you can hand to someone else.
Portable configuration — export and import your connections and queries as an encrypted .dbqm bundle.
English and Portuguese — every screen, message and --help string is translated; dbqm config set language pt, or DBQM_LANG=pt for one run.

Security

Connection passwords are encrypted at rest with Fernet.
Passwords are read from stdin or an environment variable, never from argv — they do not reach your shell history or the process table.
Queries use bind variables; SQL identifiers are validated against an allowlist.
HTML reports escape every user-controlled value.

Links

MIT licensed.

Metadata

Release files for dbqm 3.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dbqm 3.1.1
File	Size	Uploaded
dbqm-3.1.1.tar.gz	361.8 kB	Oct 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dbqm 3.1.1
File	Interpreter	ABI	Platform	Reset
dbqm-3.1.1-py3-none-any.whl 369.3 kB Oct 16, 2026	Python 3	none	any	Details

Total release size: 731.1 kB

Release files / dbqm-3.1.1.tar.gz

Download URL	dbqm-3.1.1.tar.gz
Size	361.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`f33bc8e387be182fecb5e9fd7c864fe83bc8d549ae82885767669cb0ce7d4562`
BLAKE2b-256 checksum How to use checksums	`6e4a8d57694d212be2a8201374dcb615de412c667c7bab7dd5a2c612b725ce95`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`

Release files / dbqm-3.1.1-py3-none-any.whl

Download URL	dbqm-3.1.1-py3-none-any.whl
Size	369.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`da059e96566bf0709a14e5ebb911d1eff352a75d1d2a4bd0e6bc610e7f01f8b1`
BLAKE2b-256 checksum How to use checksums	`b629e8f62fb9d95e223233daef1b3f616f552cc97a689ced2fe12dd0ca4c69f6`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`