sq

A CLI tool for managing SQL connections and running queries interactively via your editor. Results are streamed to stdout as CSV, making it easy to pipe into other tools.

Features

• Store named database connections in ~/.config/sq/connections.json
• Open your $EDITOR to write a query, then stream results as CSV to stdout
• Pass a query directly via flag, file, or stdin
• Supports PostgreSQL, MySQL, SQLite, Amazon Athena

Installation

Requires Go 1.22+

git clone <repo>
cd sq
make install        # installs to $GOPATH/bin

Or build without installing:

make build          # produces ./sq
make build-all      # cross-compile for all platforms into dist/

Usage

Manage connections

# Add a connection — prompts interactively if no flags given
sq add mydb

# Add non-interactively with a raw DSN
sq add mydb --driver postgres --dsn "host=localhost port=5432 user=alice password=secret dbname=myapp sslmode=disable"

# List saved connections
sq list

# Show details for a connection
sq show mydb

# Remove a connection
sq remove mydb

Run queries

# Open $EDITOR, write query, save & exit — results printed as CSV
sq run mydb

# Pass query directly (skip editor)
sq run mydb -q "SELECT * FROM users LIMIT 10"

# Use a query file
sq run mydb -f query.sql

# Pipe query from stdin
echo "SELECT 1" | sq run mydb --stdin

Output options

# Default: CSV with header to stdout
sq run mydb -q "SELECT * FROM orders"

# Omit header row
sq run mydb -q "SELECT id FROM users" --no-header

# Save to file
sq run mydb -q "SELECT * FROM users" > output.csv

# Pipe into other tools
sq run mydb -q "SELECT id, amount FROM orders" | awk -F, '$2 > 100'

Interactive add prompts

Running sq add <name> without flags walks through a prompt flow:

Configure connection "mydb":
Database type (postgresql/mysql/sqlite/athena/other) [postgresql]: postgresql
Host [localhost]:
Port [5432]:
Database name: myapp
Username: alice
Password:
Description (optional): local dev
Connection "mydb" saved to ~/.config/sq/connections.json

For Athena:

Database type (...) [postgresql]: athena
AWS region [us-east-1]: us-west-2
Glue database (schema) [default]: analytics
S3 staging dir (e.g. s3://my-bucket/results/): s3://my-bucket/athena-results/
Workgroup [primary]:
Provide AWS access key / secret? (no = use default credential chain) [y/N]: N

Answering N to credentials uses the standard AWS credential chain (env vars → ~/.aws/credentials → IAM role).

Config file

Connections are stored in ~/.config/sq/connections.json (created automatically). You can edit it directly. Example:

{
  "local": {
    "type": "postgresql",
    "host": "localhost",
    "port": 5432,
    "database": "myapp",
    "username": "alice",
    "password": "secret"
  },
  "prod-athena": {
    "type": "athena",
    "region": "us-east-1",
    "database": "analytics",
    "s3_staging_dir": "s3://my-bucket/results/",
    "work_group": "primary",
    "description": "production Athena"
  }
}

Environment variables

Variable	Default	Description
EDITOR	vi	Editor opened for interactive query
SQ_CONFIG	~/.config/sq/connections.json	Config file path