Skip to content
Get packs

Guide · Open source

How to use usql: install it and run queries across databases

Updated · written with AI from the project's own documentation and checked against our catalogue data

usql is a free, MIT-licensed command-line program written in Go for connecting to SQL databases and running queries. It works with PostgreSQL, MySQL, Oracle, SQLite3 and Microsoft SQL Server, using a command set modeled on PostgreSQL's psql. This guide shows you how to install usql, connect to a database, and use the basic commands.

usqlxo/usql · ★ 10.2k · MIT

Quick start

  1. 1Pick an install route. Choose Homebrew, the AUR, Go or Docker based on what you already have installed.
  2. 2Install usql. Run the install command for your route, such as brew install xo/xo/usql or the Docker run command.
  3. 3Prepare your database. For SQLite, point to an existing file; for PostgreSQL, have the host, user and password ready.
  4. 4Connect with a URL. Pass a database URL such as sqlite3://path/to/file.db or postgres://user:password@host to usql.
  5. 5Run queries. Type SQL at the prompt and use backslash commands like \drivers for help.
  6. 6Quit. Type \q to leave the usql shell.

Install usql with Homebrew, Go, AUR or Docker

usql can be installed from a release download, Homebrew, the Arch Linux AUR, Go, or Docker. The route you pick determines which prerequisite you need: Homebrew, the AUR helper yay, Go, or Docker.

The Homebrew route installs from the xo/xo tap and includes most drivers. Docker runs the official image, so you do not need to install anything else on the machine.

  • Homebrew (macOS and Linux): install with the command below.
  • Arch Linux: the usql-bin package installs the released binary; the usql package builds from source and takes considerably longer.
  • Go: the default install includes only the base drivers.
  • Docker: the official image is docker.io/usql/usql and works with Docker, Podman or other container runtimes.
$ brew install xo/xo/usql

Run usql in Docker or a container

The README shows how to run usql against a local SQLite file by mounting a directory into the container. You can also run a PostgreSQL container and connect to it with usql on the same host network.

The sample output in the README shows usql reporting the driver it connected with and prompting with a 'Type "help" for help.' message. Type \q to quit.

$ docker run --rm -it --volume $(pwd)/data:/data docker.io/usql/usql:latest sqlite3://data/test.db

Connect to a database with a URL

You connect by giving usql a database URL. The README examples use schemes such as sqlite3://, postgres:// and the short alias pg. Schemes come from the github.com/xo/dburl library that usql uses.

Once connected, the prompt shows the driver name and the database, for example sq:data/test.db=>. Run SQL statements at the prompt as you would in psql.

  • SQLite file: sqlite3://data/test.db
  • PostgreSQL: postgres://user:password@host
  • Check which drivers your build has with \drivers
$ docker run --rm --network host -it docker.io/usql/usql:latest postgres://postgres:P4ssw0rd@localhost

Use psql-style commands

usql supports most of the core psql features, including variables, backticks and backslash commands. It also adds features psql lacks, such as working with multiple databases, copying data between databases, context-based completion and terminal graphics.

Use \drivers to list the drivers your build includes. The README uses this to show which databases a particular build can connect to.

  • Backslash commands work as they do in psql.
  • \drivers lists built-in drivers.
  • \q quits the shell.
$ ./usql -c '\drivers'

Add drivers with build tags

A go install build includes only the base drivers for PostgreSQL, MySQL, SQLite3, Microsoft SQL Server, Oracle and CSVQ. If you need another database, you must build with its driver's build tag. Tags 'most' and 'all' include more drivers; 'all' also includes CGO and problematic drivers.

If you see that a driver you need is missing, the README says it is not included in the default build. Rebuild with the matching tag.

  • Base drivers: go install github.com/xo/usql@latest
  • Most drivers: go install -tags most github.com/xo/usql@latest
  • All drivers (includes CGO and problematic drivers): go install -tags all github.com/xo/usql@main
$ go install -tags most github.com/xo/usql@latest

What people use it for

  • Running quick queries against a local SQLite file from the terminal.
  • Using psql habits to work with MySQL, Oracle or SQL Server.
  • Connecting to PostgreSQL or other databases running in Docker containers.
  • Working with more than one database from a single tool.

Frequently asked questions

Is usql free to use?

Yes. The project is licensed under the MIT licence, which the listing gives as the licence for usql. Check the repository's licence file for the full terms.

Which databases does usql support?

The README names PostgreSQL, MySQL, Oracle Database, SQLite3 and Microsoft SQL Server, and says it works with many other SQL and NoSQL databases. Which ones you can use depends on the drivers in your build.

Why can't usql connect to my database?

The README says a default Go build includes only base drivers. If your database is not one of those, rebuild usql with the build tag for its driver, or use a build that includes it, such as the -tags most install.

Is usql a replacement for psql?

For non-PostgreSQL databases, the README describes usql as a great replacement for other command-line clients. It keeps most psql features and adds multi-database support and copying between databases.

Does usql have a graphical interface?

No. The README describes usql as a command-line interface only. If you want a graphical browser, look at tools such as DBeaver.

What are the alternatives to usql?

Projects listed as comparable are psql, mycli, pgcli and dbeaver. psql is the PostgreSQL client that usql's commands are modeled on; mycli and pgcli add completion for MySQL and PostgreSQL; dbeaver is a graphical tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

usql suits developers and administrators who work with several SQL databases and want one command-line tool with psql-style commands. If you only need PostgreSQL, psql or pgcli may be enough, and if you want a graphical browser, pick dbeaver instead.

Install options & downloads