usql - One Database Client to Rule Them All (Mostly)

Look, usql is basically someone's attempt to create one database client to rule them all. The idea is solid: instead of juggling psql, mysql, sqlite3, and whatever the fuck Oracle calls their client these days, you get one tool that connects to everything.

Does it work? Mostly. Will it occasionally make you want to throw your laptop out the window? Absolutely.

The Problem usql Tries to Solve

If you've worked with databases for more than five minutes, you know this pain: every database has its own special snowflake client. PostgreSQL has psql (which is actually decent), MySQL has that mysql command that never remembers your password correctly, and don't get me started on Oracle's sqlplus - that thing feels like it was designed by someone who hates developers.

So you end up with:

• Different syntax for meta commands (`\d` vs `DESCRIBE` vs whatever)
• Different ways to format output
• Different config files in different places
• Different connection string formats that make no fucking sense

How usql Actually Works (When It Works)

usql takes the psql interface - which most people actually like - and bolts on drivers for 40+ database systems. Version 0.19.25 connects to basically everything that speaks SQL and some things that don't.

Like most Go database tools, usql builds on the standard database/sql package architecture. The universal client provides a consistent interface while different database drivers handle the backend-specific communication protocols.

The good parts:

• One tool, one syntax to remember
• `psql` users can jump right in
• Cross-database copy operations (when they don't crash)
• Actually decent syntax highlighting

The parts that'll bite you:

• Version 0.19.24 completely broke Presto support - had to rollback to 0.11
• macOS config is a mess - docs say ~/.config/usql but it actually uses `~/Library/Application Support/usql`
• ARM builds randomly fail with CGO linking errors
• Auto-completion is hit-or-miss depending on which database you're connected to

When You Should Actually Use This

usql shines when you're:

• Jumping between PostgreSQL, MySQL, and SQLite regularly
• Doing data migrations between different database types
• Working in environments where installing separate clients is a pain in the ass
• Already comfortable with `psql` and want that interface everywhere

When to just use the native client instead:

• If you only use one database type (seriously, just use `psql`)
• When you need database-specific features that usql doesn't support
• If you're doing anything performance-critical (native clients are faster)
• When the team already has workflows built around native tools

The bottom line: usql is useful enough that I keep it installed, but I still have psql and mysql as backups for when things go sideways.

Installing usql should be straightforward, but like everything in software, there are gotchas waiting to ruin your day.

The "Just Works" Methods

Homebrew (macOS/Linux) - Start here

## This works 90% of the time
brew install xo/xo/usql

If you need ODBC support (and you probably don't), there used to be a --with-odbc flag but Homebrew killed that. Now you're stuck building from source.

Docker - When you give up on local installation

## Basic usage - mount your data directory
docker run --rm -it --volume $(pwd):/data docker.io/usql/usql:latest

## Connect to host database (networking can be a pain)
docker run --rm --network host -it docker.io/usql/usql:latest postgres://user:pass@localhost/db

Docker networking will fuck you if your database is running in another container. Use `docker-compose` or give up and install locally.

The "I Like Pain" Method: Building from Source

Go installation - Pick your poison

## Minimal drivers, less likely to break
go install github.com/xo/usql@latest

## Most drivers, good balance of features vs. stability
go install -tags most github.com/xo/usql@latest

## All drivers, prepare for CGO hell
go install -tags all github.com/xo/usql@latest

Real talk about build tags:

• `base`: PostgreSQL, MySQL, SQLite, SQL Server, Oracle. Safe choice.
• `most`: Everything except the problematic CGO drivers. This is what you want.
• `all`: Everything including Oracle ODBC and other CGO nightmares. Only do this if you enjoy suffering.

When Things Go Wrong (And They Will)

ARM64 build failures
If you're on Apple Silicon or ARM, builds randomly fail with:

undefined reference to `resvg_parse_tree_from_data'

This is a known issue #494. Try the most build tag instead of all.

macOS config directory confusion
The docs lie. They say config goes in ~/.config/usql but on macOS it actually looks in:

~/Library/Application Support/usql/config.yaml

This bit me for hours before I figured it out.

CGO dependency hell
If you see errors about missing C libraries, you're in CGO land:

## macOS - might help with ICU4C issues
brew install icu4c

## Still broken? Try the nuclear option
export CGO_ENABLED=0
go install -tags most github.com/xo/usql@latest

First Connection Reality Check

PostgreSQL - Usually works

## Local with defaults (if you're lucky)
usql pg://

## More likely you need this
usql postgres://user:password@localhost:5432/database

## SSL issues? Disable it
usql pg://user:pass@host/db?sslmode=disable

MySQL - Password encoding will get you

## Basic connection
usql mysql://user:password@localhost/database

## Special characters in password? URL encode that shit
usql mysql://user:p%40ssw0rd@localhost/database

SQLite - The reliable one

## Just point at a file
usql database.sqlite3

## Or be explicit
usql sqlite3://./database.db

Quick Sanity Check

## Make sure it actually installed
usql --version

## See what drivers you actually got
usql -c '\drivers'

## Test basic connection
usql sqlite3://test.db -c 'SELECT "hello world";'

If any of these fail, you're probably missing dependencies or hit a build issue. Welcome to the wonderful world of Go CGO dependencies.

Pro tip: Keep both usql and the native clients installed. When usql breaks (and it will), you'll be glad you have `psql` as backup.

usql tries to be the Swiss Army knife of database clients. Sometimes it succeeds, sometimes it cuts you.

The psql-Compatible Stuff (Mostly Works)

Backslash commands - The good part
Most of PostgreSQL's `\` commands work across databases:

• `\d` - Lists tables, but formatting varies wildly by database
• `\dt` - Tables specifically (when the driver supports it)
• `\c` - Connect to different databases (connection strings are a pain)
• ` iming` - Shows query timing (actually useful)
• `\help` - Decent help system

Query buffer stuff

• `\e` - Opens your `$EDITOR` (if it's set correctly)
• `\p` - Shows current query buffer
• `\g` - Execute with formatting options
• `\r` - Clear buffer (you'll use this a lot when things break)

Auto-Completion: Hit or Miss

The auto-completion is... optimistic. Works great with PostgreSQL, decent with MySQL, and completely shits the bed with anything exotic. Don't rely on it for Oracle or any of the NoSQL adapters.

What actually completes:

• SQL keywords (usually)
• Table names (if you're connected to PostgreSQL or MySQL)
• Column names (sometimes, if the stars align)

What doesn't:

• Database-specific functions
• Anything in BigQuery or Snowflake
• Complex schema names with dots

Syntax Highlighting: Pretty but Buggy

Powered by Chroma, which is nice when it works. But complex queries break the parser and you get rainbow vomit instead of useful highlighting.

## Turn it off when it annoys you
\set SYNTAX_HL false

Output Formats: The Actually Useful Part

Multiple output modes that actually work:

• Default aligned tables (good for human consumption)
• `\json` - JSON output (great for scripts)
• `\csv` - CSV export (works better than most native clients)
• `\G` - Vertical display (lifesaver for wide tables)
• `\H` - HTML tables (useful for reports)

Cross-Database Copy: When It Doesn't Crash

The `\copy` command is usql's killer feature, but it's also where most of the pain happens:

-- This works (usually)
\copy postgres://source mysql://target 'SELECT * FROM small_table' 'backup_table'

-- This will timeout or crash
\copy postgres://source mysql://target 'SELECT * FROM huge_table' 'backup_table'

Reality check:

• Great for small datasets (< 100MB)
• Timeouts on anything substantial
• No progress indicators, so you're flying blind
• Error messages are cryptic as hell

Configuration: macOS Will Betray You

Remember that config file location issue? It gets worse:

Linux/WSL:

## ~/.config/usql/config.yaml
connections:
  prod: postgres://user:pass@prod-host/db

macOS (the special snowflake):

## ~/Library/Application Support/usql/config.yaml
connections:
  prod: postgres://user:pass@prod-host/db

The .usqlpass file for password storage works, but good luck remembering the format:

## protocol:host:port:database:user:password
postgres:localhost:5432:mydb:myuser:mypass
mysql:*:*:*:myuser:mypass

What's Actually Missing

No connection pooling - Each connection is brand new
No transaction state preservation - Switching connections kills your transaction
Spotty schema support - Multi-schema databases are a nightmare
No query history persistence - Restart usql, lose your history
Performance monitoring - iming is basic, no detailed stats

Terminal Graphics: Gimmicky

The "terminal graphics" and chart generation features exist, but they're mostly novelty. Unless you're presenting to someone who's never seen a database client before, just export to CSV and use real visualization tools.

When to Use Native Clients Instead

Use `psql` when:

• You need PostgreSQL-specific features
• Performance matters
• You're debugging complex transactions
• Connection pooling is required

Use `mysql` when:

• You need MySQL-specific utilities (`mysqldump`, etc.)
• Working with complex stored procedures
• Performance tuning

Use usql when:

• Jumping between different database types
• Quick ad-hoc queries across systems
• Data migration between different databases
• You're too lazy to remember different client syntaxes

Bottom line: usql is a decent Swiss Army knife, but sometimes you need an actual screwdriver.