Getting Started

Getting Started

Five minutes to your first multi-server query.

1. Create a config file

propq reads server connections from a TOML file. The search order is:

1. -c PATH (explicit flag)
2. ./propq.toml (current directory)
3. ~/.config/propq/config.toml (platform config dir)

Generate one:

propq config generate -o propq.toml

or copy the repo's example:

cp propq.toml.example propq.toml

Edit it and add your servers:

[connections.local]
host = "127.0.0.1"
port = 3306
user = "myuser"
password = "mypassword"
max_connections = 3
tags = ["dev"]

[connections.prod-eu-1]
host = "db1.example.com"
port = 3306
user = "myuser"
password = "mypassword"
max_connections = 3
tags = ["prod", "eu"]

2. Verify the config

# List servers and their live database counts
propq servers

# Validate config + test every connection
propq config check

3. Run a query

Default mode: once per server — fast (~50 ms per server), uses the server's default database:

propq -s local --sql "SELECT VERSION(), NOW()"

Per-database mode (every matching database on every matching server):

propq -s local -a -d "^test" --sql "SELECT COUNT(*) FROM users"

4. Four ways to supply SQL

# Inline
propq --sql "SELECT 1" -s prod

# File (use '-' for stdin)
propq -f migration.sql -d "^shop_"

# Pipe
echo "SELECT NOW(), DATABASE()" | propq -s staging

# Editor ($EDITOR) — with query history support
propq -e

SQL source priority: --sql → -f → -e → stdin pipe.

5. Output

propq -s prod --sql "SELECT VERSION()"              # table (auto-paged via less)
propq -s prod --sql "SHOW TABLE STATUS" --json      # JSON for scripts/AI
propq -s prod --sql "SELECT * FROM users" --csv     # CSV for Excel
propq -s prod --sql "SELECT 1" --stream             # results as they complete

Long table output auto-pages through less -SRFX when stdout is a TTY — search with /, quit with q. Disable with --no-pager.

What's next

• Configuration — every config key
• CLI-Reference — all flags
• Examples — ready-to-use commands