Introduction

Welcome to rsql, a command line interface for SQL databases. rsql is designed to work with a variety of SQL databases, operating systems, and CPU architectures.

Getting Started

Installation

To install rsql, use one of the commands below, or navigate to the rsql site and select an installation method. If you are attempting to install on a platform not listed on the project site, you can find additional builds attached to the latest release.

Linux / MacOS

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/theseus-rs/rsql/releases/latest/download/rsql_cli-installer.sh | sh

Windows

irm https://github.com/theseus-rs/rsql/releases/latest/download/rsql_cli-installer.ps1 | iex

First Query

The following examples show how to run a simple query using the rsql CLI tool for different database engines.

CockroachDB

rsql --url "cockroachdb://<user[:password>]@<host>[:<port>]/<database>" -- "SELECT version();"

DuckDB

rsql --url "duckdb://?memory=true" -- "SELECT version();"

LibSQL

rsql --url "libsql://?memory=true" -- "SELECT sqlite_version();"

MariaDB

rsql --url "mariadb://<user>[:<password>]@<host>[:<port>]/<database>" -- "SELECT version();"

MySQL

rsql --url "mysql://<user>[:<password>]@<host>[:<port>]/<database>" -- "SELECT version();"

Postgres

rsql --url "postgres://?embedded=true" -- "SELECT version();"

PostgreSQL

rsql --url "postgresql://?embedded=true" -- "SELECT version();"

Redshift

rsql --url "redshift://<user[:password>]@<host>[:<port>]/<database>" -- "SELECT version();"

Rusqlite

rsql --url "rusqlite://?memory=true" -- "SELECT sqlite_version();"

Snowflake

rsql --url "snowflake://<user>@<account>.snowflakecomputing.com/[?private_key_file=pkey_file&public_key_file=pubkey_file]" -- "SELECT CURRENT_VERSION();"

or

rsql --url "snowflake://<user>[:<token>]@<account>.snowflakecomputing.com/" -- "SELECT CURRENT_VERSION();"

Sqlite

rsql --url "sqlite://?memory=true" -- "SELECT sqlite_version();"

Commands

Commands are the primary way to interact with the rsql CLI. A command is a single word that is used to perform a specific action preceded by the command identifier (eg: .help). The commands are localized for each supported language. A shortened version of the command can be used as long as it is unique. For example, .desc can be used in place of .describe.

Demonstration

bail

Usage

.bail <on|off>

Description

The bail command sets the behavior of the CLI when an error occurs. By default, the CLI will continue processing after the first error. If the bail command is set to on, the CLI will exit after the first error.

Examples

Show the current bail setting:

.bail

Enable bail on first error:

.bail on

Disable bail on first error:

.bail off

Demonstration

changes

Usage

.changes <on|off>

Description

The changes command toggles the display of the number of rows changed by a SQL statement. When the display is turned on, the number of rows changed is displayed after the execution of a SQL statement. When the display is turned off, the number of rows changed is not displayed.

Examples

Show the current changes setting:

.changes

Turn on the rows changed display:

.changes on

Turn off the rows changed display:

.changes off

Demonstration

clear

Usage

.clear

Description

The clear command clears the screen.

Examples

Clear the screen:

.clear

Demonstration

color

Usage

.color <on|off>

Description

Controls if output is in color. By default, the color command is set to on. If the color command is set to off, the output will not be in color.

Examples

Show the current color setting:

.color

Enable color output:

.color on

Disable color output:

.color off

Demonstration

describe

Usage

.describe [table]

Description

The describe command provides information about the specified database table.

Examples

Describe the table named users.

.describe users

Demonstration

drivers

Usage

.drivers

Description

The drivers command displays the available database drivers.

Examples

Show the available drivers:

.drivers

Demonstration

echo

Usage

.echo <on|prompt|off>

Description

Echo executed commands. By default, the echo command is set to off. If the echo command is set to on, the commands will be echoed to the defined output. If the echo command is set to prompt, prompt and commands will be echoed to the defined output.

Examples

Show the current echo setting:

.echo

Enable echoing commands:

.echo on

Enable echoing the prompt and commands:

.echo prompt

Disable echoing commands:

.echo off

exit

Usage

.exit [code]

Description

Exit the shell with an optional status code. If no status code is provided, the exit status will be the exit status of the last command executed.

Examples

Exit the shell with a status code of 0.

.exit

Exit the shell with a status code of 1.

.exit 1

Demonstration

footer

Usage

.footer <on|off>

Description

The footer command sets the display of the footer in the CLI. By default, the footer is displayed. If the footer command is set to off, the footer will not be displayed.

Examples

Show the current footer setting:

.footer

Enable the footer:

.footer on

Disable the footer:

.footer off

Demonstration

format

Usage

.format [format]

Description

The format command sets the format mode for the CLI. The default format mode is unicode.

Examples

Show the current format mode:

.format

Set the format mode to ascii:

.format ascii

Set the format mode to unicode:

.format unicode

Demonstration

header

Usage

.header <on|off>

Description

The header command sets the display of the header in the CLI. By default, the header is displayed. If the header command is set to off, the header will not be displayed.

Examples

Show the current header setting:

.header

Enable the header:

.header on

Disable the header:

.header off

Demonstration

help

Usage

.help

Description

The help command displays help information for the CLI.

Examples

Show the help information:

.help

Demonstration

history

Usage

.history <on|off>

Description

The history command displays the command history for the CLI.

Examples

Show the current history setting and display the history:

.history

Enable history:

.history on

Disable history:

.history off

indexes

Usage

.indexes [table]

Description

Display the indexes for a table. If no table is specified, display the indexes for all tables.

Examples

Display the indexes for all tables:

.indexes

Display the indexes for the users table:

.indexes users

Demonstration

limit

Usage

.sleep <seconds>

Description

Set the limit of rows to be displayed. The default limit is 100. If the limit is set to 0, then all rows are displayed.

Examples

Display the current limit setting:

.limit

Set row limit to unlimited:

.limit 0

Set row limit to 10:

.limit 10

Demonstration

locale

Usage

.locale [locale]

Description

The locale command sets the locale for the CLI. The locale is used to display numeric values in the specified locale. The default locale is determined by the system settings, or the en locale if the system settings can not be determined.

Examples

Show the current locale setting:

.locale

Set the locale to en-GB:

.locale en-GB

Demonstration

output

Usage

.output [filename]

Description

The output command redirects the output commands to the system clipboard or a file. If no option is provided, the output is redirected to stdout (console).

Examples

Redirect the output of commands to the system clipboard:

.output clipboard

Redirect the output of commands to a file named output.txt:

.output output.txt

Redirect the output of commands to stdout (console):

.output

print

Usage

.print [string]

Description

The print command prints a message to the output.

Examples

Print a message to the output:

.print "hello, world!

Demonstration

quit

Usage

.quit

Description

The quit command exits the CLI.

Examples

Exit the CLI:

.quit

Demonstration

read

Usage

.read [filename]

Description

Read and execute SQL commands from a file. The file must contain valid SQL commands. Multi-line SQL statements should be terminated with a semicolon (;).

Examples

Read and execute SQL commands from a file named commands.sql:

.read commands.sql

rows

Usage

.rows <on|off>

Description

The rows command toggles the display of the number of rows returned by a query. When enabled, the number of rows returned by a query is displayed after the query results.

Examples

Show the current rows setting:

.rows

Turn on the rows returned display:

.rows on

Turn off the rows returned display:

.rows off

Demonstration

tables

Usage

.schemas

Description

The schemas command lists the schemas in the database.

Examples

List the schemas in the database:

.schemas

Demonstration

sleep

Usage

.sleep <seconds>

Description

The sleep command pauses the CLI for the specified number of seconds. This command is can be used in scripts to simulate delayed user interaction with a database.

Examples

Sleep for 1 second:

.sleep

Sleep for 3 seconds:

.sleep 3

Sleep for .5 seconds:

.sleep .5

Demonstration

system

Usage

.system command [args]

Description

The system command executes the specified operating system command. The command and any optional arguments are passed to the operating system shell for execution. The output of the command is displayed to the defined output.

Examples

Print the current working directory:

.system pwd

List the current directory:

.system ls -l

Demonstration

tables

Usage

.tables

Description

The tables command lists the tables in the schema.

Examples

List the tables in the schema:

.tables

Demonstration

output

Usage

.tee [filename]

Description

The tee command redirects the output of commands to the system clipboard or a file and stdout (console). If option is provided, the output is redirected to stdout (console).

Examples

Redirect the output of commands to the system clipboard and the console:

.tee clipboard

Redirect the output of commands to a file named output.txt and the console:

.tee output.txt

Redirect the output of commands to stdout (console):

.tee

timer

Usage

.timer <on|off>

Description

The timer command toggles the display of the time taken to execute a query.

Examples

Show the current timer setting:

.timer

Turn on the timer:

.timer on

Turn off the timer:

.timer off

Demonstration

Appendix

Configuration File (rsql.toml)

A default rsql.toml file will be created on startup if one does not already exist. This file is used to configure the behavior of the rsql CLI and will be written to the $HOME/.rsql directory on Unix-like systems and %APPDATA%\rsql on Windows. The file is written in the TOML format.

rsql.toml

The following is an example of a rsql.toml file:

[global]

# The locale to use.  If not specified, an attempt will be made to detect
# the system locale, but if that fails, the default "en" (US English)
# locale will be used.
#locale = "en"

# Indicate if the program should exit after the first error occurs.
#
# Possible values:
#   true - exit after the first error
#   false - continue processing after the first error
bail_on_error = false

# Indicate if color should be used in the output.
#
# Possible values:
#   true - use color in the output
#   false - don't use color in the output
#color = true

# The string used to initiate a command.
#
# This is used to determine if a line is a command or not. For example,
# if the command identifier is set to ".", then any line that starts with
# a "." will be considered a command.
command_identifier = "."

# Indicate if executed commands should be echoed to the defined output.
#
# Possible values:
#   true - echo executed commands
#   prompt - echo prompt and executed commands 
#   false - don't echo executed commands
echo = false

[log]

# The log level to use.
#
# Possible values:
#   "off"  - Designates that trace instrumentation should be completely
#            disabled.
#   "error" - Designates very serious errors.
#   "warn" - Designates hazardous situations.
#   "info" - Designates useful information.
#   "debug" - Designates lower priority information.
#   "trace" - Designates very low priority, often extremely verbose,
#             information.
level = "info"

# The frequency to rotate the logs.
#
# Possible values:
#   "minutely" - Rotate the logs minutely.
#   "hourly" - Rotate the logs hourly.
#   "daily" - Rotate the logs daily.
#   "never" - Never rotate the logs.
rotation = "daily"

[shell]

# The key binding mode to use.
#
# Possible values:
#   "emacs" - use the Emacs key bindings
#   "vi" - use the Vi key bindings
edit_mode = "emacs"

# Indicate if commands should be saved to the history file.
#
# Possible values:
#   true - save commands to the history file
#   false - don't save commands to the history file
history.enabled = true

# Indicate if duplicate commands should be saved to the history file.
#
# Possible values:
#   true - save duplicate commands to the history file
#   false - don't save duplicate commands to the history file
history.ignore_dups = true

# The maximum number of history entries to keep.
#
# 0 means no limit.
history.limit = 1000

# Indicate if smart completions should be used.
#
# Possible values:
#   true - smart completions are enabled
#   false - smart completions are disabled
smart.completions = true

# The theme to use when light mode is detected.
theme.light = "Solarized (light)"

# The theme to use when dark mode is detected.
theme.dark = "Solarized (dark)"

# The theme to use. This value overrides the light and dark mode themes
# when set.
#
# Possible values:
#   "base16-ocean.dark"
#   "base16-ocean.light"
#   "Solarized (dark)"
#   "Solarized (light)"
#theme = "Solarized (dark)"

[results]

# Indicate if changes should be displayed.
#
# Possible values:
#   true - display the changes
#   false - don't display the changes
changes = true

# Indicate if footer should be displayed when displaying results.
#
# Possible values:
#   true - display the footer
#   false - don't display the footer
footer = true

# The format to use for results.
#
# Possible values:
#   "ascii" - ASCII characters to draw a table
#   "csv" - Comma Separated Values (CSV)
#   "html" - HyperText Markup Language (HTML)
#   "json" - JavaScript Object Notation (JSON)
#   "jsonl" - JSON Lines (JSONL)
#   "markdown" - Markdown
#   "plain" - Column based layout
#   "psql" - PostgreSQL formatted table
#   "sqlite" - SQLite formatted table
#   "tsv" - Tab Separated Values (TSV)
#   "unicode" - Unicode characters to draw a table
#   "xml" - Extensible Markup Language (XML)
#   "yaml" - YAML Ain’t Markup Language (YAML)
format = "psql"

# Indicate if header should be displayed when displaying results.
#
# Possible values:
#   true - display the header
#   false - don't display the header
header = true

# The maximum number of rows to display. 0 means no limit.
limit = 100

# Indicate if rows returned should be displayed.
#
# Possible values:
#   true - display the rows
#   false - don't display the rows
rows = true

# Enable timer for commands.
#
# Possible values:
#   true - enable timer
#   false - disable timer
timer = true

Supported Locales

Each locale includes a ISO 639-1 language code and an optional ISO 3166-1 country code to specify language and regional settings.

The following locales have translations available for use. Most of the translations are "machine translations" and will often be less than perfect. If you would like to contribute a better translation, or add a new locale, please submit your contribution to rsql.