#db-cli

CLI to inspect and query relational databases (MySQL, PostgreSQL, SQLite) through named connection profiles, with table/json/csv output. Built to pair with an LLM doing schema exploration — describe a table, sample rows, run a read-only query — without hand-rolling a PHP script per database each time.

Built with Laravel Zero and modeled on the other CLIs in this monorepo.

#Requirements

• PHP ^8.2 with ext-pdo (plus the driver you need: pdo_mysql, pdo_pgsql, pdo_sqlite)

#Install

#Global (recommended)

composer global require jeffersongoncalves/db-cli

The binary db will be on your PATH as long as Composer's global vendor/bin is in it.

#From source

git clone https://github.com/jeffersongoncalves/db-cli.git
cd db-cli
composer install

#Usage

#Update

db self-update

#Connection profiles

Profiles are saved to ~/.db-cli/config.json (mode 0600).

db connections:add            # interactive: name, driver, host, port, database, user, password
db connections:list
db connections:remove alfa

To connect through an SSH bastion (mysql/pgsql only), answer yes to "Connect through an SSH tunnel?" during connections:add, or pass the --ssh-host/--ssh-port/--ssh-username/--ssh-private-key options. host/port stay the database's real address as seen from the bastion; the CLI opens a local port forward through the system ssh client (so your ~/.ssh/config, agent and keys apply as usual) and tears it down when the command exits. Requires an ssh client on PATH.

db connections:add prod --driver=pgsql --host=127.0.0.1 --port=5432 \
    --username=app --ssh-host=bastion.example.com --ssh-username=deploy \
    --ssh-private-key=~/.ssh/id_ed25519

#Explore a database

db tables alfa
db describe alfa users
db sample alfa users
db sample alfa users --column=role --distinct

#Run a read-only query

db query alfa "select id, email from users where active = 1"
db query alfa "select * from orders" --limit=50 --format=json

query only accepts SELECT / SHOW / DESCRIBE / EXPLAIN / WITH / PRAGMA, rejects stacked statements (a; b), and appends a LIMIT when the query doesn't already have one — this CLI is meant for read-only exploration, including against production databases.

#Benchmark a query

db benchmark alfa "select * from orders where status = 'open'" --runs=20
db benchmark alfa --file=queries.sql --runs=20 --warmup=2 --format=json

Runs the statement --runs times (plus --warmup discarded runs to prime caches) and reports min/avg/median/max in milliseconds, plus the row count. --file accepts a .sql file with one or more ;-terminated statements; a -- label comment on a statement names it in the output, otherwise statements are labeled q1, q2, ... Same read-only restriction as query.

#Output formats

Every read command accepts --format=table|json|csv (default table). json is the format to reach for when piping results to an LLM or another program.

#Development

composer install
composer test       # Pest tests + Pint lint
composer lint        # Auto-fix style
composer phpstan      # Static analysis
composer build        # Build the PHAR into builds/db

#License

MIT © Jefferson Goncalves