How to Install and Use usql in Linux for a Universal Command-Line SQL Client

Database administrators and software engineers routinely juggle multiple database engines across development, staging, and production environments. Switching between dedicated command-line utilities such as psql, mysql, sqlite3, and proprietary drivers introduces fragmented keyboard shortcuts, inconsistent query syntax highlighting, and conflicting configuration formats. usql solves this operational friction by providing a universal, standalone command-line client built with Go that connects seamlessly to PostgreSQL, MySQL, MariaDB, SQLite3, Microsoft SQL Server, Oracle, and modern distributed stores using a unified, responsive interface.

Featuring interactive multi-line editing, contextual autocompletion, connection bookmarks, configurable visual themes, and native tabular data formatting, usql delivers an intuitive terminal environment across modern Linux distributions. In this tutorial, you will explore how to install usql on Linux, configure secure database connections, navigate relational schemas, and streamline everyday query workflows.

What Is usql and Why Use It?

Standard relational database distributions bundle distinct interactive clients that vary significantly in capability and ergonomics:

• Unified Command Syntax: Employs familiar meta-commands inspired by PostgreSQL (such as \d to describe schema elements, \l to list databases, and \x for expanded record layouts) across all connected database engines.
• Broad Database Driver Support: Natively compiles drivers for PostgreSQL, MySQL, SQLite, Oracle Database, Microsoft SQL Server, Snowflake, CockroachDB, ClickHouse, and Google BigQuery.
• No Runtime Dependencies: Distributed as a self-contained static Go binary, requiring no runtime Python scripts, Java virtual machines, or external driver linkers.
• Connection Bookmarks: Allows users to map verbose database connection strings (DSNs) to concise shorthand identifiers within a local configuration file.

Step 1: Installing usql on Linux

You can install usql on Linux via official pre-compiled release binaries, Homebrew for Linux, or Go package managers depending on your environment preference.

Method 1: Installing the Pre-Compiled Binary (Universal Linux)

The fastest deployment method across Ubuntu, Debian, Fedora, Arch Linux, and Rocky Linux utilizes the official GitHub releases.

First, verify your system architecture and download the latest release tarball using curl or wget:

curl -s https://api.github.com/repos/xo/usql/releases/latest \
  | grep "browser_download_url.*linux_amd64.tar.bz2" \
  | cut -d : -f 2,3 \
  | tr -d \" \
  | wget -qi -

Extract the compressed archive to your current directory:

tar -xjf usql-*.tar.bz2

Move the executable binary into your system executable path (such as /usr/local/bin) and assign appropriate execution permissions:

sudo mv usql /usr/local/bin/
sudo chmod +x /usr/local/bin/usql

Verify that the binary runs properly by querying its version string and compiled driver manifest:

usql --version

Method 2: Installing via Homebrew on Linux

If you maintain development toolchains using Homebrew on Linux, install usql with a single command:

brew install xo/xo/usql

Step 2: Connecting to Common Relational Databases

usql accepts standard Data Source Names (DSNs) or protocol-prefixed URLs directly from the terminal shell.

Connecting to Local SQLite Databases

To inspect a local SQLite database file, provide the path directly with the sqlite: protocol prefix:

usql sqlite:/var/data/analytics.db

If the target database file does not yet exist, usql creates the file automatically upon connection.

Connecting to PostgreSQL

Pass your credentials, server hostname, target port, and database name using standard URI format:

usql postgres://postgres:SecretPassword123@localhost:5432/production_db?sslmode=disable

Connecting to MySQL or MariaDB

Connect to local or remote MySQL services by defining credentials and host addresses:

usql mysql://root:[email protected]:3306/ecommerce_db

Step 3: Navigating and Querying Inside the usql Shell

Once connected, usql presents an interactive prompt showing the active driver and database instance:

production_db=> 

Listing Databases and Tables

Querying schema structures does not require memorising different vendor commands. Use universal meta-commands across any driver:

\l      -- List all available databases
\dt     -- List all user tables in current schema
\dv     -- List all database views
\di     -- List all database indexes
\d users -- Describe columns and constraints for the 'users' table

Executing Multi-Line SQL Queries

Input SQL statements across multiple lines; usql buffers the command until you type a terminating semicolon (;):

SELECT id, username, email, created_at 
FROM users 
WHERE is_active = true 
ORDER BY id DESC 
LIMIT 5;

Toggling Expanded Display Layout

When query results contain dozens of horizontal columns, terminal lines frequently wrap and become difficult to read. Activate the expanded display mode (identical to PostgreSQL’s \x):

\x on

Subsequent queries will display records in a vertical key-value layout, making extensive tables readable in narrow terminal windows.

Step 4: Setting Up Connection Bookmarks

Entering long connection URLs containing complex passwords into shell history poses security risks and operational inconvenience. usql resolves this through local configuration bookmarks.

Create the default configuration directory and configuration file in your home profile:

mkdir -p ~/.config/usql
nano ~/.config/usql/config.yaml

Define named bookmarks matching your regular workflow environments:

connections:
  local-pg:
    url: "postgres://postgres:SecretPassword123@localhost:5432/app_dev"
  staging-mysql:
    url: "mysql://staging_user:[email protected]:3306/shop_staging"
  local-sqlite:
    url: "sqlite:~/.local/share/tracker.db"

Save the file and secure its read permissions so other local accounts cannot access database credentials:

chmod 600 ~/.config/usql/config.yaml

Launch an interactive session instantly by supplying the bookmark identifier:

usql local-pg

Step 5: Exporting Query Results to CSV and JSON

usql provides built-in output redirection commands for extracting query data into common file formats directly from automated shell scripts or interactive sessions.

To export query output directly to a comma-separated values (CSV) file, run:

\c local-pg
\pset format csv
\o /home/user/exports/active_users.csv
SELECT id, username, email FROM users WHERE is_active = true;
\o

Typing \o without arguments closes the output file descriptor and restores terminal rendering.