Introduction

Welcome to rsql, a powerful and flexible command-line SQL interface for working with data from a wide variety of sources. Whether you are a data engineer, analyst, or developer, rsql is designed to make querying, transforming, and exploring data fast and productive.

What is rsql?

rsql is a cross-platform CLI tool that connects to many different databases and file formats, including relational databases (PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, Redshift, ScyllaDB, Snowflake, DuckDB, H2, SQLite, and more), as well as data files (CSV, JSON, Parquet, Arrow, Avro, Excel, XML, YAML, and others). It supports both local and remote data sources. The JDBC driver runs Java database drivers inside rsql and resolves Maven dependencies.

Why use rsql?

• Unified SQL interface: Query many data sources with a consistent SQL syntax and experience.
• Automation: Integrate with scripts and automation pipelines for data processing.
• Productivity: Features like smart completions, history, and formatting make interactive work efficient.
• Portability: Works on Linux, macOS, and Windows, with support for multiple CPU architectures.
• Extensibility: Easily configure output formats, themes, and behaviors to fit your workflow.

When to use rsql?

• When you need to quickly query or transform data from different sources without switching tools.
• When you want to automate data tasks in scripts or CI/CD pipelines.
• When you need a lightweight, installable SQL client for local or remote databases.
• When you want to explore, analyze, or export data in various formats.

Continue to Getting Started for a quick setup and usage guide.

Getting Started

Welcome to the rsql quick start guide! This section will help you install rsql, run your first query, and learn best practices for using the CLI efficiently.

Quick Start

1. Install rsql
   • See the Installation section for platform-specific instructions.
2. Run your first query
   • Try a simple query against a supported database or file. See First Query for examples.
3. Explore configuration
   • Customize rsql using the rsql.toml file. See the Configuration File appendix for details.
4. Set your locale
   • Use the .locale command to set your preferred language and number formatting. See Supported Locales.

Best Practices

• Leverage command history and smart completions to speed up interactive work.
• Use output formats (CSV, JSON, Markdown, etc.) to integrate with other tools or reporting workflows.
• Check the FAQ & Tips for troubleshooting and advanced usage.

Ready to get started? Continue to Installation or jump to First Query.

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

You can install rsql using the provided installer script, which will download the latest release and set it up for you.

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

Alternatively, you can use Homebrew:

brew install rsql

Windows

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

Troubleshooting Installation

• Permission denied: If you see a permission error, try running the installer with sudo (Linux/MacOS) or as Administrator (Windows).
• Command not found: Ensure the install directory is in your PATH. You may need to restart your terminal or add the install location to your shell profile.
• Antivirus/Defender blocks installer: Temporarily disable or whitelist the installer if you trust the source.
• Unsupported platform: Check the latest release page for additional builds or open an issue for your platform.
• Network issues: If the installer fails to download, check your internet connection and proxy/firewall settings.

For more help, see the FAQ or open an issue on the GitHub repository.

First Query

The following examples show how to run a simple query using the rsql CLI tool for different data sources. Replace placeholders (e.g., <user>, <host>, <database> ) with your actual connection details.

CockroachDB

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

DuckDB (in-memory or file)

# In-memory
rsql --url "duckdb://" -- "SELECT version();"
# File-based
rsql --url "duckdb:///path/to/file.duckdb" -- "SELECT COUNT(*) FROM my_table;"

H2 (in-memory or file)

rsql --url "h2://" -- "SELECT H2VERSION();"
rsql --url "h2:./example" -- "SELECT 42;"

The H2 driver downloads and caches H2 2.5.252 and its runtime dependencies from Maven Central. h2:// creates a private in-memory database; a file URL retains data between sessions. See the H2 guide for options.

JDBC

Resolve the JDBC driver and its runtime dependencies from Maven Central:

rsql --url "jdbc:postgresql://localhost/example?user=postgres&dependency=org.postgresql:postgresql:42.7.13&driver=org.postgresql.Driver" -- "SELECT version();"

Omit driver to use JDBC service discovery. See JDBC and H2 for URL options, Java runtime setup, and offline caching.

MariaDB

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

MySQL

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

Postgres (embedded or remote)

rsql --url "postgres://?embedded=true" -- "SELECT version();"
rsql --url "postgres://<user>:<password>@<host>:<port>/<database>" -- "SELECT COUNT(*) FROM my_table;"

PostgreSQL (embedded or remote)

rsql --url "postgresql://?embedded=true" -- "SELECT version();"
rsql --url "postgresql://<user>:<password>@<host>:<port>/<database>" -- "SELECT COUNT(*) FROM my_table;"

Redshift

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

Rusqlite

rsql --url "rusqlite://" -- "SELECT sqlite_version();"

ScyllaDB

rsql --url "scylladb://<user>:<password>@<host>:9042/<keyspace>" -- "SELECT release_version FROM system.local;"

Snowflake

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

Querying Data Files (CSV, Parquet, etc.)

rsql --url "csv:///path/to/data.csv" -- "SELECT * FROM data LIMIT 5;"
rsql --url "parquet:///path/to/data.parquet" -- "SELECT column1, column2 FROM data WHERE column3 > 100;"

Sqlite

rsql --url "sqlite://" -- "SELECT sqlite_version();"

Tips

• Use the --format option or .format command to change output format (e.g., CSV, JSON).
• Use .help for a list of available commands.
• For more advanced examples, see the FAQ & Tips.

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

The .bail command controls how rsql handles errors during command execution. By default, rsql continues processing after an error, which is useful for running scripts or multiple commands in a session. Enabling bail mode (on) will cause rsql to immediately exit on the first error, which is helpful for automation, CI/CD, or when you want to ensure no further actions are taken after a failure.

Usage

.bail <on|off>

When to use

• Enable bail (on) when running scripts where any error should halt execution.
• Disable bail (off) for interactive sessions or when you want to review multiple errors in one run.

Examples

Show the current bail setting:

.bail

Enable bail on first error (recommended for automation):

.bail on

Disable bail on first error (recommended for exploration):

.bail off

Troubleshooting

• If your script stops unexpectedly, check if .bail on is set.
• If errors are being ignored, ensure .bail off is not set unintentionally.

Related

• See the bail_on_error option in rsql.toml configuration.
• For error handling in scripts, see Best Practices.

Demonstration

catalogs

The .catalogs command lists all catalogs available in the connected data source. Catalogs are top-level containers for schemas and tables, and are especially relevant in enterprise databases or cloud data warehouses.

Usage

.catalogs

When to use

• Use .catalogs to discover available catalogs when connecting to complex or multi-tenant databases.
• Helpful for exploring unfamiliar data sources or verifying access permissions.

Examples

List all catalogs in the current data source:

.catalogs

Troubleshooting

• If no catalogs are listed, ensure your connection has the necessary permissions.
• Some databases may not support catalogs; in that case, this command may return an empty result.

Related

• See also: schemas and tables commands for further exploration.

Demonstration

changes

The .changes command toggles the display of the number of rows affected by SQL statements (such as INSERT, UPDATE, DELETE). This feedback is useful for verifying the impact of your queries, especially in data modification or ETL workflows.

Usage

.changes <on|off>

When to use

• Enable .changes on to always see how many rows were changed by your queries—helpful for auditing and debugging.
• Disable .changes off for a cleaner output if you do not need this information.

Examples

Show the current changes setting:

.changes

Turn on the rows changed display:

.changes on

Turn off the rows changed display:

.changes off

Troubleshooting

• If you do not see row change counts, ensure .changes on is set.
• Some drivers or read-only queries may not report row changes.

Related

• See the changes option in rsql.toml configuration.
• For output customization, see format and footer.

Demonstration

clear

The .clear command clears the terminal screen, providing a clean workspace. This is especially useful during long interactive sessions or when you want to remove clutter from previous outputs.

Usage

.clear

When to use

• Use .clear to reset your terminal view before running new queries or demos.
• Helpful for presentations or screen recordings.

Examples

Clear the screen:

.clear

Troubleshooting

• If the screen does not clear, ensure your terminal supports ANSI escape codes.
• On some platforms, the effect may vary depending on the terminal emulator.

Related

• For managing output, see format and footer.

Demonstration

color

The .color command controls whether rsql outputs color text in the terminal. Color output improves readability, especially for large result sets or when distinguishing between different types of output. By default, color is enabled.

Usage

.color <on|off>

When to use

• Enable color (on) for interactive use, demos, or when you want visually distinct output.
• Disable color (off) for scripts, logs, or when redirecting output to files where ANSI codes are undesirable.

Examples

Show the current color setting:

.color

Enable color output:

.color on

Disable color output:

.color off

Troubleshooting

• If you see strange characters in redirected output, try .color off.
• Some terminals may not support color; in that case, disabling color is recommended.

Related

• See the color option in rsql.toml configuration.
• For output customization, see format.

Demonstration

completions

The .completions command enables or disables smart command and SQL completions in rsql. Smart completions help you write commands and queries faster by suggesting keywords, table names, and more as you type. By default, completions are enabled.

Usage

.completions <on|off>

When to use

• Enable completions (on) for interactive sessions to boost productivity and reduce typos.
• Disable completions (off) if you prefer manual entry or experience issues with suggestions.

Examples

Show the current completions setting:

.completions

Enable completions:

.completions on

Disable completions:

.completions off

Troubleshooting

• If completions are not working, ensure .completions on is set and your terminal supports interactive input.
• Some drivers or remote sessions may limit available suggestions.

Related

• See the smart.completions option in rsql.toml configuration.
• For command history, see history.

Demonstration

describe

The .describe command provides detailed information about a table or view, including its columns and data types. For tables, it also displays constraints, indexes, primary keys, and foreign key relationships. Primary keys and foreign keys are displayed with an "Inferred" column that indicates whether the relationship was declared in the database schema or inferred from column naming conventions (e.g., a user_id column referencing a users table, or a NOT NULL id column as a primary key). When describing a view, only columns are displayed.

Usage

.describe [table|view]

When to use

• Use .describe to inspect table or view schemas before writing queries or performing data transformations.
• Helpful for data exploration, debugging, and documentation.
• Use to discover primary key and foreign key relationships, including inferred ones based on naming conventions.

Examples

Describe the table named users:

.describe users

Describe the view named user_emails:

.describe user_emails

Describe the current table (if context is set):

.describe

Troubleshooting

• If you receive an error, ensure the table or view name is correct, and you have access permissions.
• Some data sources may require fully qualified names (e.g., schema.table).

Related

• schemas
• tables
• views
• indexes
• primary
• foreign

Demonstration

drivers

Usage

.drivers

Description

The drivers command lists the data drivers available in the current build.

For URL formats, connection options, defaults, and examples, see the Drivers chapter.

echo

The .echo command controls whether rsql echoes executed commands (and optionally the prompt) to the output. This is useful for logging, debugging, or when you want to keep a record of all commands run in a session. By default, echo is off.

Usage

.echo <on|prompt|off>

When to use

• Enable echo (on) to log all commands for auditing or script debugging.
• Use prompt to echo both the prompt and commands, which is helpful for creating reproducible session logs.
• Disable echo (off) for a cleaner interactive experience.

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

Troubleshooting

• If your logs are missing commands, ensure .echo on or .echo prompt is set.
• For interactive use, keep echo off to avoid clutter.

Related

• See the echo option in rsql.toml configuration.
• For output redirection, see output and tee.

Demonstration

exit

The .exit command immediately terminates the rsql session. You can optionally provide an exit code, which is useful for scripting and automation to indicate success or failure to the calling process.

Usage

.exit [code]

When to use

• Use .exit to leave the CLI at any time.
• Provide a non-zero exit code (e.g., .exit 1) to signal an error in scripts or CI/CD pipelines.

Examples

Exit the shell with a status code of 0 (success):

.exit

Exit the shell with a status code of 1 (failure):

.exit 1

Troubleshooting

• If the shell does not exit as expected, check for background processes or pending operations.
• In scripts, use .exit <code> to control flow based on success or failure.

Related

• For quitting without specifying a code, see quit.
• For error handling, see bail.

Demonstration

footer

The .footer command controls whether rsql displays a footer after query results. The footer typically shows summary information such as row counts, execution time, and other metadata. By default, the footer is displayed.

Usage

.footer <on|off>

When to use

• Enable the footer (on) to see summary information after each query—useful for data analysis and performance monitoring.
• Disable the footer (off) for a cleaner output, especially when exporting results or scripting.

Examples

Show the current footer setting:

.footer

Enable the footer:

.footer on

Disable the footer:

.footer off

Troubleshooting

• If you do not see summary information, ensure .footer on is set.
• For minimal output, use .footer off in combination with .header off and .changes off.

Related

• See the footer option in rsql.toml configuration.
• For output customization, see format, header, and changes.

Demonstration

foreign

The .foreign command displays foreign key information for tables in your connected database. Foreign keys define relationships between tables and are essential for understanding data models.

Usage

.foreign [table]

When to use

• Use .foreign to list all foreign keys in the database.
• Specify a table (e.g., .foreign orders) to see foreign keys for that specific table.
• Use to understand table relationships, which is essential for writing joins and maintaining referential integrity.

Examples

Display the foreign keys for all tables:

.foreign

Display the foreign keys for the orders table:

.foreign orders

Output

The output includes:

• Table — the table name
• Foreign Key — the constraint name
• Columns — the local column(s) in the foreign key
• Referenced Table — the table being referenced
• Referenced Columns — the column(s) in the referenced table
• Inferred — whether the foreign key was declared in the schema or inferred from naming conventions (e.g., a user_id column referencing a users table with an id column)

Troubleshooting

• If no foreign keys are shown, ensure your database supports foreign key metadata and you have the necessary permissions.
• Some file-based or NoSQL data sources may not support foreign keys natively; inferred keys may still be displayed.

Related

• describe for full table structure
• primary for primary keys
• indexes for index information

Demonstration

format

The .format command sets the output format for query results in rsql. This allows you to tailor the display for readability, data export, or integration with other tools. The default format is psql, but many formats are available for different use cases.

Usage

.format [format]

Available Formats

When to use

• Use unicode, ascii, or psql for interactive exploration.
• Use csv, tsv, json, jsonl, xml, or yaml for exporting data or integrating with other tools.
• Use markdown or html for documentation or reporting.
• Use expanded for wide tables or when you want each row displayed vertically.

Examples

Show the current format mode:

.format

Set the format mode to ascii:

.format ascii

Set the format mode to json for machine-readable output:

.format json

Troubleshooting

• If output looks garbled in your terminal, try switching to ascii or plain.
• For large exports, prefer csv, tsv, or jsonl for best performance.

Related

• See the format option in rsql.toml configuration.
• For header/footer control, see header and footer.

Demonstration

header

The .header command controls whether rsql displays a header row (column names) above query results. By default, the header is displayed, making it easier to interpret data, especially for wide tables or unfamiliar queries.

Usage

.header <on|off>

When to use

• Enable the header (on) for interactive exploration, data analysis, or when sharing results with others.
• Disable the header (off) for minimal output, such as when exporting data for further processing.

Examples

Show the current header setting:

.header

Enable the header:

.header on

Disable the header:

.header off

Troubleshooting

• If you do not see column names, ensure .header on is set.
• For scripting or exporting, use .header off to avoid extra lines in output files.

Related

• See the header option in rsql.toml configuration.
• For output customization, see format, footer, and changes.

Demonstration

help

The .help command displays a list of available commands and their usage in rsql. This is your go-to resource for learning about built-in commands, their syntax, and quick tips for usage.

Usage

.help

When to use

• Use .help if you forget a command or want to discover new features.
• Helpful for onboarding new users or troubleshooting command syntax.

Examples

Show the help information:

.help

Troubleshooting

• If you do not see the expected help output, ensure you are running the latest version of rsql.
• For detailed documentation, see the Commands section or the FAQ & Tips.

Related

• For command-specific help, see the documentation for each command in Commands.

Demonstration

history

The .history command manages and displays the command history in rsql. This feature helps you recall, repeat, or edit previous commands, improving productivity in interactive sessions. You can also enable or disable history tracking as needed.

Usage

.history <on|off>

When to use

• Use .history to review or search previous commands.
• Enable history (on) to keep a record of your session for future reference.
• Disable history (off) for privacy or when working with sensitive data.

Examples

Show the current history setting and display the history:

.history

Enable history tracking:

.history on

Disable history tracking:

.history off

Troubleshooting

• If commands are not being saved, ensure .history on is set and your configuration allows history.
• For privacy, use .history off or clear the history file manually.

Related

• See the history.enabled and history.limit options in rsql.toml configuration.
• For command recall, use arrow keys or search shortcuts in your terminal.

Demonstration

indexes

The .indexes command displays index information for tables in your connected database. Indexes are critical for query performance and data integrity, so this command is useful for database tuning, troubleshooting, and schema exploration.

Usage

.indexes [table]

When to use

• Use .indexes to list all indexes in the database, helping you understand how queries are optimized.
• Specify a table (e.g., .indexes users) to see indexes relevant to that table, which is helpful for performance tuning or debugging slow queries.

Examples

Display the indexes for all tables:

.indexes

Display the indexes for the users table:

.indexes users

Troubleshooting

• If no indexes are shown, ensure your database supports index metadata and you have the necessary permissions.
• Some file-based or NoSQL data sources may not support indexes.

Related

• See also: describe for table structure, tables for table listing, and schemas for schema exploration.

Demonstration

limit

The .limit command sets the maximum number of rows displayed for query results in rsql. This is useful for controlling output size, especially when working with large datasets or when you want to preview data without overwhelming your terminal.

Usage

.limit [rows]

When to use

• Use .limit 10 to preview a small sample of your data.
• Use .limit 0 to remove the row limit and display all results (be cautious with large tables).
• Adjust the limit for exporting, reporting, or interactive exploration.

Examples

Display the current limit setting:

.limit

Set row limit to unlimited (all rows):

.limit 0

Set row limit to 10:

.limit 10

Troubleshooting

• If you see fewer rows than expected, check the current limit setting.
• For very large tables, avoid .limit 0 unless you are sure your terminal and system can handle the output.

Related

• See the limit option in rsql.toml configuration.
• For output customization, see format, header, and footer.

Demonstration

locale

The .locale command sets or displays the current locale used by rsql for formatting numbers, dates, and messages. This is useful for international users or when you want to match output to a specific language or regional format.

Usage

.locale [locale]

When to use

• Use .locale to check the current locale setting.
• Set a specific locale (e.g., .locale en-GB) to change language and number formatting.
• Useful for multi-language environments, demos, or when sharing results with users in different regions.

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 British English:

.locale en-GB

Set the locale to French:

.locale fr

Troubleshooting

• If you see untranslated or garbled text, ensure your locale is supported ( see Supported Locales).
• Some output (such as database errors) may not be localized if not supported by the driver.

Related

• See the locale option in rsql.toml configuration.
• For contributing translations, see [Supported Locales](../../appendix/supported-local

output

The .output command redirects the output of rsql commands to a file or the system clipboard, instead of the default stdout (console). This is useful for saving results, sharing data, or integrating with other tools.

Usage

.output [filename|clipboard]

When to use

• Use .output output.txt to save results to a file for later analysis or sharing.
• Use .output clipboard to copy results directly to your system clipboard (supported platforms only).
• Use .output with no arguments to reset output to the console.

Examples

Redirect output to the system clipboard:

.output clipboard

Redirect output to a file named output.txt:

.output output.txt

Reset output to the console:

.output

Troubleshooting

• If the clipboard option does not work, ensure your platform supports clipboard integration.
• If the file cannot be written, check file permissions and available disk space.

Related

• For splitting output to multiple destinations, see tee.
• For changing output format, see format.

primary

The .primary command displays primary key information for tables in your connected database. Primary keys identify unique rows in a table and are critical for data integrity.

Usage

.primary [table]

When to use

• Use .primary to list all primary keys in the database.
• Specify a table (e.g., .primary users) to see the primary key for that specific table.
• Use to understand how tables are uniquely identified, which is essential for joins and data integrity.

Examples

Display the primary keys for all tables:

.primary

Display the primary key for the users table:

.primary users

Output

The output includes:

• Table — the table name
• Primary Key — the constraint name
• Columns — the column(s) that make up the primary key
• Inferred — whether the primary key was declared in the schema or inferred from naming conventions (e.g., a NOT NULL column named id)

Troubleshooting

• If no primary keys are shown, ensure your database supports primary key metadata and you have the necessary permissions.
• Some file-based or NoSQL data sources may not support primary keys natively; inferred keys may still be displayed.

Related

• describe for full table structure
• foreign for foreign keys
• indexes for index information

Demonstration

print

The .print command outputs a message to the current output destination (console, file, or clipboard if redirected). This is useful for adding comments, separators, or debugging information in scripts and interactive sessions.

Usage

.print [string]

When to use

• Use .print to display custom messages, progress updates, or script annotations.
• Helpful for marking sections in output files or logs.

Examples

Print a message to the output:

.print "hello, world!"

Print a separator line:

.print "--------------------"

Troubleshooting

• If you do not see the message, check if output is redirected (see .output).
• Ensure your string is properly quoted if it contains spaces or special characters.

Related

• For output redirection, see output and tee.

Demonstration

quit

The .quit command immediately exits the rsql CLI session. It is functionally equivalent to .exit but does not accept an exit code. Use this command to leave the CLI at any time.

Usage

.quit

When to use

• Use .quit to end your session quickly and cleanly.
• Useful for interactive sessions or when you want to ensure all resources are released.

Examples

Exit the CLI:

.quit

Troubleshooting

• If the CLI does not exit, check for background operations or pending queries.
• For scripting or automation, prefer .exit if you need to specify an exit code.

Related

• exit for exiting with a status code

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

The .rows command toggles the display of the number of rows returned by a query in rsql. This is useful for quickly verifying the size of your result set, especially when filtering or aggregating data.

Usage

.rows <on|off>

When to use

• Enable .rows on to always see how many rows your queries return—helpful for data validation and exploration.
• Disable .rows off for a cleaner output, especially when exporting results or scripting.

Examples

Show the current rows setting:

.rows

Turn on the rows returned display:

.rows on

Turn off the rows returned display:

.rows off

Troubleshooting

• If you do not see row counts, ensure .rows on is set.
• For minimal output, use .rows off in combination with .header off and .footer off.

Related

• See the rows option in rsql.toml configuration.
• For output customization, see format, header, and footer.

Demonstration

schemas

The .schemas command lists all schemas available in the connected data source. Schemas are logical containers for tables, views, and other database objects, and are especially important in multi-tenant or enterprise databases.

Usage

.schemas

When to use

• Use .schemas to discover available schemas when connecting to complex databases.
• Helpful for exploring unfamiliar data sources, organizing queries, or verifying access permissions.

Examples

List all schemas in the current data source:

.schemas

Troubleshooting

• If no schemas are listed, ensure your connection has the necessary permissions.
• Some databases may not support schemas; in that case, this command may return an empty result.

Related

• See also: catalogs and tables for further exploration.

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 data source.

Examples

Sleep for 1 second:

.sleep

Sleep for 3 seconds:

.sleep 3

Sleep for .5 seconds:

.sleep .5

Demonstration

system

The .system command executes an operating system command from within rsql. This is useful for running shell commands, inspecting the environment, or integrating with other tools without leaving the CLI.

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.

When to use

• Use .system to run shell commands (e.g., ls, pwd, cat file.txt) without leaving rsql.
• Helpful for automation, scripting, or when you need to check files, directories, or system status during a session.

Examples

Print the current working directory:

.system pwd

List the current directory:

.system ls -l

Run a script or external tool:

.system ./myscript.sh arg1 arg2

Troubleshooting

• If a command fails, check the syntax and ensure the command exists in your system's PATH.
• Output is sent to the current output destination (see .output).
• Some commands may behave differently depending on your OS (macOS, Linux, Windows).

Related

• For output redirection, see output and tee.
• For scripting, see read and sleep.

Demonstration

tables

The .tables command lists all tables available in the current schema or data source. This is essential for data exploration, query building, and verifying your access to specific tables.

Usage

.tables

When to use

• Use .tables to discover available tables before writing queries.
• Helpful for exploring unfamiliar databases, verifying schema changes, or onboarding new users.

Examples

List all tables in the current schema:

.tables

Troubleshooting

• If no tables are listed, ensure you are connected to the correct schema and have the necessary permissions.
• Some data sources may require you to set the schema context first.

Related

• See also: schemas for schema selection and describe for table details.

Demonstration

tee

The .tee command duplicates the output of rsql commands to both the console (stdout) and a file or the system clipboard. This is useful for logging, auditing, or sharing results while still seeing them interactively.

Usage

.tee [filename|clipboard]

When to use

• Use .tee output.txt to save results to a file while also displaying them in the console.
• Use .tee clipboard to copy results to your clipboard and see them in the console (supported platforms only).
• Use .tee with no arguments to reset output to the console only.

Examples

Redirect output to the system clipboard and the console:

.tee clipboard

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

.tee output.txt

Reset output to the console only:

.tee

Troubleshooting

• If the clipboard option does not work, ensure your platform supports clipboard integration.
• If the file cannot be written, check file permissions and available disk space.

Related

• For output redirection without duplication, see output.
• For changing output format, see format.

timer

The .timer command toggles the display of the time taken to execute each query in rsql. This is useful for performance monitoring, query optimization, and benchmarking different SQL statements or data sources.

Usage

.timer <on|off>

When to use

• Enable .timer on to see how long each query takes—helpful for tuning queries or comparing database performance.
• Disable .timer off for a cleaner output if you do not need timing information.

Examples

Show the current timer setting:

.timer

Turn on the timer:

.timer on

Turn off the timer:

.timer off

Troubleshooting

• If you do not see timing information, ensure .timer on is set.
• For minimal output, use .timer off in combination with .header off, .footer off, and .rows off.

Related

• See the timer option in rsql.toml configuration.
• For output customization, see format.

Demonstration

views

The .views command lists all views available in the current schema or data source. This is useful for data exploration, understanding database structure, and identifying available views for querying.

Usage

.views

When to use

• Use .views to discover available views before writing queries.
• Helpful for exploring unfamiliar databases, verifying schema changes, or understanding the logical data model.

Examples

List all views in the current schema:

.views

Troubleshooting

• If no views are listed, ensure you are connected to the correct schema and have the necessary permissions.
• Some data sources may require you to set the schema context first.
• Not all data sources support views. For example, file-based data sources and DynamoDB do not have views.

Related

• tables for listing tables
• schemas for schema selection
• describe for view or table details

Demonstration

Drivers

Choose a driver using the scheme at the start of the connection URL. Every page below describes its URL format, options, examples, and usage notes. Run .drivers to see which drivers are available in your build.

rsql --url 'sqlite://' -- 'SELECT 42;'
rsql --url 'csv://people.csv' -- 'SELECT * FROM people LIMIT 10;'

Quote the URL in your shell, especially when it contains ?, &, or semicolons. In the formats below, angle brackets mark values to replace and square brackets mark optional parts; do not include those brackets literally. Percent-encode reserved characters in credentials, filenames, and option values.

File drivers accept relative and absolute paths. Most structured-file drivers load data into an in-memory SQL context; database drivers connect directly to a database. Transport and compression drivers delegate to a detected format driver. Their pages describe which options are forwarded.

Databases and JDBC

Structured files

Files and remote resources

Compression

Arrow IPC

The arrow driver reads Arrow IPC files and exposes their data through SQL.

URL format

arrow://<file>

Options

This driver has no format-specific URL query options. The file supplies its schema.

Examples

rsql --url 'arrow://people.arrow' -- 'SELECT * FROM people LIMIT 10;'

Usage notes

Use a relative path such as arrow://people.arrow or an absolute path such as arrow:///data/people.arrow. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

Avro

The avro driver reads Avro files and exposes their data through SQL.

URL format

avro://<file>

Options

This driver has no format-specific URL query options. The file supplies its schema.

Examples

rsql --url 'avro://people.avro' -- 'SELECT * FROM people LIMIT 10;'

Usage notes

Use a relative path such as avro://people.avro or an absolute path such as avro:///data/people.avro. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

Brotli

The brotli driver decompresses a local Brotli file and opens the contents with the matching data driver.

URL format

brotli://<file>[?<format-options>]

Options

There are no decompression-specific query options. Query parameters are forwarded to the detected data driver; for example, CSV accepts has_header, quote, and skip_rows.

Examples

rsql --url 'brotli://people.csv.br?quote=%22' -- 'SELECT * FROM people;'

Usage notes

Keep the original extension before .br so the decompressed filename identifies the data format. The corresponding format driver must be enabled. For CSV content, see CSV options. Decompressed data is staged in a temporary directory; queries do not rewrite the compressed source.

Use .tables to inspect the resulting tables.

Bzip2

The bzip2 driver decompresses a local Bzip2 file and opens the contents with the matching data driver.

URL format

bzip2://<file>[?<format-options>]

Options

There are no decompression-specific query options. Query parameters are forwarded to the detected data driver; for example, CSV accepts has_header, quote, and skip_rows.

Examples

rsql --url 'bzip2://people.csv.bz2?quote=%22' -- 'SELECT * FROM people;'

Usage notes

Keep the original extension before .bz2 so the decompressed filename identifies the data format. The corresponding format driver must be enabled. For CSV content, see CSV options. Decompressed data is staged in a temporary directory; queries do not rewrite the compressed source.

Use .tables to inspect the resulting tables.

ClickHouse

The clickhouse driver connects to ClickHouse through its HTTP interface.

URL format

clickhouse://[<user>[:<password>]@]<host>[:<port>]/[<database>][?<options>]

Options

Examples

rsql --url 'clickhouse://default@localhost:8123/default?scheme=http' -- 'SELECT version();'
rsql --url 'clickhouse://user:password@db.example.com:8443/default?scheme=https'

Usage notes

The driver defaults to host localhost and port 8123, including when using HTTPS. Set the port appropriate for your service. The path selects the database. Successful non-query statements report 0 changes. Use .tables and .describe to inspect the database.

CockroachDB

The cockroachdb driver connects to CockroachDB using the PostgreSQL protocol.

URL format

cockroachdb://<user>[:<password>]@<host>[:<port>]/<database>[?<options>]

Options

Examples

rsql --url 'cockroachdb://user:password@localhost:26257/example' -- 'SELECT 1;'

Usage notes

The connection uses the PostgreSQL wire protocol through SQLx. Specify the service port explicitly; the underlying connection defaults to port 5432. The example uses port 26257. Use .catalogs, .schemas, .tables, and .describe to inspect accessible objects.

See PostgreSQL (SQLx) for shared connection options. SQL features and metadata depend on the target service.

CrateDB

The cratedb driver connects to CrateDB using the PostgreSQL protocol.

URL format

cratedb://<user>[:<password>]@<host>[:<port>]/<database>[?<options>]

Options

Examples

rsql --url 'cratedb://user:password@localhost:5432/example' -- 'SELECT 1;'

Usage notes

The connection uses the PostgreSQL wire protocol through SQLx. Specify the service port explicitly; the underlying connection defaults to port 5432. The example uses port 5432. Use .catalogs, .schemas, .tables, and .describe to inspect accessible objects.

See PostgreSQL (SQLx) for shared connection options. SQL features and metadata depend on the target service.

CSV

The csv driver loads separated text fields into Polars SQL.

URL format

csv://<file>[?has_header=<true|false>&quote=<char>&skip_rows=<rows>]

Options

Examples

rsql --url 'csv://people.csv?quote=%22' -- 'SELECT * FROM people LIMIT 10;'

Usage notes

The field separator is fixed to comma.

Use a relative path such as csv://people.csv or an absolute path such as csv:///data/people.csv. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

Delimited text

The delimited driver loads separated text fields into Polars SQL.

URL format

delimited://<file>[?has_header=<true|false>&quote=<char>&skip_rows=<rows>]

Options

Examples

rsql --url 'delimited://people.txt?separator=%7C&quote=%22' -- 'SELECT * FROM people;'

Usage notes

Choose the field separator with separator. Character options require exactly one ASCII character after URL decoding.

Use a relative path such as delimited://people.txt or an absolute path such as delimited:///data/people.txt. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

DuckDB

The duckdb driver opens a local DuckDB database or a temporary in-memory database.

URL format

duckdb://[<file>]

Options

There are no driver-specific URL query options. Configure the database using its SQL settings or pragmas.

Examples

rsql --url 'duckdb://' -- 'SELECT 42;'
rsql --url 'duckdb://example.duckdb'

Usage notes

Omit the filename for an in-memory database, whose data lasts for the session. A file path creates or opens a persistent database; use three slashes for an absolute Unix path. No database server is required. Use .tables, .views, and .describe to inspect objects.

Database changes are written to the selected file when using a persistent database.

DynamoDB

The dynamodb driver queries DynamoDB using PartiQL.

URL format

dynamodb://[<access_key_id>:<secret_access_key>@]<host>[:<port>][?<options>]

Options

Examples

rsql --url 'dynamodb://dynamodb.us-east-1.amazonaws.com?region=us-east-1'
rsql --url 'dynamodb://test:test@localhost:8000?scheme=http&region=us-east-1'

Usage notes

Without URL credentials, the AWS SDK resolves credentials from its normal configuration chain. A custom endpoint requires scheme; its default port is 443 when no port is given. The second example connects to DynamoDB Local.

Use .tables to list tables, then query with PartiQL, for example SELECT * FROM "people". PartiQL support and affected-row reporting differ from relational SQL.

Excel

The excel driver reads Excel workbooks and exposes sheets as SQL tables.

URL format

excel://<file>[?has_header=<true|false>&skip_rows=<rows>]

Options

Examples

rsql --url 'excel://people.xlsx'
rsql --url 'excel://people.xlsx?has_header=false&skip_rows=2'

Usage notes

A workbook with one sheet uses the filename before the first dot as its table name. With multiple sheets, tables are named <file>__<sheet>; non-alphanumeric characters in sheet names become underscores. Use .tables to find the names. Without a header row, columns are named A, B, and so on.

Use a relative path such as excel://people.xlsx or an absolute path such as excel:///data/people.xlsx. Percent-encode spaces and URL delimiters in filenames.

Sheets are loaded into an in-memory Polars SQL context. Session changes do not update the workbook.

File detection

The file driver detects a local file’s type and selects a matching driver.

URL format

file://<file>[?<format-options>]

Options

There are no detection-specific query options. Options are forwarded to the detected driver. For example, see CSV, Excel, and SQLite.

Examples

rsql --url 'file://people.csv?quote=%22' -- 'SELECT * FROM people;'
rsql --url 'file:///data/example.sqlite'

Usage notes

Use relative or absolute paths. Detection requires the file to exist and a matching driver to be enabled. Choose an explicit format URL when detection cannot distinguish the content. Compressed files are delegated through the matching decompression driver. Use .tables to inspect the opened data.

FlightSQL

The flightsql driver connects to an Apache Arrow FlightSQL server.

URL format

flightsql://[<user>[:<password>]@]<host>[:<port>][?scheme=<http|https>]

Options

Examples

rsql --url 'flightsql://localhost:31337?scheme=http' -- 'SELECT 1;'
rsql --url 'flightsql://user:password@flight.example.com:31337?scheme=https'

Usage notes

A host is required; the default port is 31337. Supplying a username triggers a FlightSQL authentication handshake. The server determines supported SQL, catalogs, schemas, and metadata. Use .catalogs, .schemas, and .tables to explore available data.

Fixed-width text

The fwf driver splits text rows into fixed-width columns and queries them with Polars SQL.

URL format

fwf://<file>?widths=<widths>[&headers=<names>]

Options

Examples

rsql --url 'fwf://people.fwf?widths=5,20,3&headers=id,name,age' -- 'SELECT * FROM people;'

Usage notes

Every line is treated as data. Fields are trimmed and imported as strings; cast columns in SQL when needed. Rows shorter than the configured widths fail to load. There are no has_header or skip_rows options.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

Gzip

The gzip driver decompresses a local Gzip file and opens the contents with the matching data driver.

URL format

gzip://<file>[?<format-options>]

Options

There are no decompression-specific query options. Query parameters are forwarded to the detected data driver; for example, CSV accepts has_header, quote, and skip_rows.

Examples

rsql --url 'gzip://people.csv.gz?quote=%22' -- 'SELECT * FROM people;'

Usage notes

Keep the original extension before .gz so the decompressed filename identifies the data format. The corresponding format driver must be enabled. For CSV content, see CSV options. Decompressed data is staged in a temporary directory; queries do not rewrite the compressed source.

Use .tables to inspect the resulting tables.

H2

The h2 driver opens H2 databases through the JDBC driver. It supplies the Maven dependency com.h2database:h2:2.5.252 and selects org.h2.Driver automatically.

URL format

h2:[<database>][;<h2-settings>][?<jdbc-options>]

h2: and h2:// open a private in-memory database. Other locations follow H2's JDBC syntax. An optional // prefix is accepted for consistency with other rsql drivers.

Options

H2 settings use semicolons; JDBC and Maven options use the query string.

Other H2 semicolon settings pass through unchanged. See JDBC options for coordinate formats, URL encoding, and classpath separators.

Examples

Start an in-memory session or query the H2 version:

rsql --url 'h2://'
rsql --url 'h2://' -- 'SELECT H2VERSION();'

Run SQL in the interactive session:

CREATE TABLE person (id INTEGER PRIMARY KEY, name VARCHAR(100));
INSERT INTO person VALUES (1, 'Ada');
SELECT * FROM person;

Use a persistent file, optionally with compatibility settings:

rsql --url 'h2:./example'
rsql --url 'h2:./example;MODE=PostgreSQL'

Downloads and offline use

H2 uses JDBC's shared Maven resolution and cache. POMs, checksums, and JARs are cached under the user's OS cache directory in rsql/maven/repository; classpath artifacts are materialized in rsql/maven/artifacts. Cached release dependencies are reused across sessions.

The first connection needs network access for uncached H2 dependencies and Ristretto's default Java runtime libraries. Offline use requires both the artifacts and runtime libraries to be cached locally. Ristretto executes H2 inside rsql without an external Java process.

Usage notes

Private in-memory databases disappear when their connection closes. Use a file URL to retain data between sessions. Each rsql JDBC connection owns a separate JVM, so named in-memory databases are not shared between connections.

HTTP

The http driver downloads a resource over HTTP, detects its format, and opens it with the matching data driver.

URL format

http://<host>[:<port>]/<path>[?_headers=<headers>]

Options

Examples

rsql --url 'http://example.com/people.csv' -- 'SELECT * FROM people LIMIT 10;'
rsql --url 'http://example.com/people.json?_headers=Accept%3Dapplication%2Fjson'

Usage notes

The response content type and filename select the data driver, which must be enabled. The resource is downloaded into a temporary directory. Use .tables to inspect the imported tables and the request/response header tables.

Query options, including expanded _headers values, are also included in the outgoing request URL. Avoid placing secret header values in this URL. Format options are described on the corresponding driver page, such as JSON.

HTTPS

The https driver downloads a resource over HTTPS, detects its format, and opens it with the matching data driver.

URL format

https://<host>[:<port>]/<path>[?_headers=<headers>]

Options

Examples

rsql --url 'https://example.com/people.csv' -- 'SELECT * FROM people LIMIT 10;'
rsql --url 'https://example.com/people.json?_headers=Accept%3Dapplication%2Fjson'

Usage notes

The response content type and filename select the data driver, which must be enabled. The resource is downloaded into a temporary directory. Use .tables to inspect the imported tables and the request/response header tables.

Query options, including expanded _headers values, are also included in the outgoing request URL. Avoid placing secret header values in this URL. Format options are described on the corresponding driver page, such as JSON.

JDBC

The jdbc driver runs Java JDBC drivers inside rsql using the embedded Ristretto JVM. It resolves driver JARs and runtime dependencies from Maven Central, or loads local JARs supplied on a classpath.

URL format

jdbc:<subprotocol>:<database>[?<database-options>&dependency=<coordinate>&driver=<class>]

Use the database's standard JDBC URL. For example, PostgreSQL uses jdbc:postgresql://<host>[:<port>]/<database>. Database-specific query parameters and semicolon settings pass through to the JDBC driver.

Options

These options are removed before the URL reaches JDBC:

Maven coordinates also accept group:artifact:extension:version and group:artifact:extension:classifier:version. Dependencies are resolved in URL order; resolved artifacts precede local classpath entries. Use pinned release versions for repeatable connections. Local classpaths remain usable without any dependency option.

Use ? before the first query parameter and & between subsequent parameters. Percent-encode delimiters in option values: %20 for a space, %2B for a literal plus sign, and %26 for an ampersand. Database-specific options such as user, password, and sslmode keep their original encoding.

Examples

Resolve PostgreSQL JDBC and its runtime dependencies automatically:

rsql --url 'jdbc:postgresql://localhost/example?user=postgres&dependency=org.postgresql:postgresql:42.7.13&driver=org.postgresql.Driver' -- 'SELECT version();'

Use JDBC service discovery, or supply existing local JARs:

rsql --url 'jdbc:postgresql://localhost/example?user=postgres&dependency=org.postgresql:postgresql:42.7.13' -- 'SELECT 42;'
rsql --url 'jdbc:postgresql://localhost/example?user=postgres&classpath=/path/postgresql-42.7.13.jar&classpath=/path/dependency.jar&driver=org.postgresql.Driver'

Repeat dependency for additional published libraries. For H2, a generic JDBC connection can be written as:

rsql --url 'jdbc:h2:mem:example?dependency=com.h2database:h2:2.5.252&driver=org.h2.Driver' -- 'SELECT H2VERSION();'

The dedicated H2 driver supplies this dependency and driver class implicitly.

Downloads and offline use

ristretto_resolver caches Maven POMs, checksums, and artifacts under the user's OS cache directory in rsql/maven/repository. Resolved JARs are materialized in rsql/maven/artifacts. Cached release entries are reused across connections; the resolver handles transitive dependency mediation and checksum verification.

The first connection needs network access for uncached artifacts and Ristretto's default Java runtime libraries. Offline use requires all needed Maven artifacts and runtime libraries to be cached locally. No external Java process is launched.

Usage notes

The driver supports affected-row counts, result labels, NULLs, numeric and binary values, dates and times, UUIDs, arrays (including nested arrays), and JSON values. Numeric values exceeding rsql's decimal precision are returned as strings. Times and timestamps with offsets retain their offsets as strings. Results are collected in memory.

JSON

The json driver reads JSON data and queries it with Polars SQL.

URL format

json://<file>[?infer_schema_length=<rows>&ignore_errors=<true|false>]

Options

Examples

rsql --url 'json://people.json' -- 'SELECT * FROM people LIMIT 10;'
rsql --url 'json://people.json?infer_schema_length=0'

Usage notes

Use a JSON array of row objects.

Use a relative path such as json://people.json or an absolute path such as json:///data/people.json. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

JSON Lines

The jsonl driver reads JSON Lines data and queries it with Polars SQL.

URL format

jsonl://<file>[?infer_schema_length=<rows>&ignore_errors=<true|false>]

Options

Examples

rsql --url 'jsonl://people.jsonl' -- 'SELECT * FROM people LIMIT 10;'
rsql --url 'jsonl://people.jsonl?infer_schema_length=0'

Usage notes

Use one JSON row object per line.

Use a relative path such as jsonl://people.jsonl or an absolute path such as jsonl:///data/people.jsonl. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

LZ4

The lz4 driver decompresses a local LZ4 file and opens the contents with the matching data driver.

URL format

lz4://<file>[?<format-options>]

Options

There are no decompression-specific query options. Query parameters are forwarded to the detected data driver; for example, CSV accepts has_header, quote, and skip_rows.

Examples

rsql --url 'lz4://people.csv.lz4?quote=%22' -- 'SELECT * FROM people;'

Usage notes

Keep the original extension before .lz4 so the decompressed filename identifies the data format. The corresponding format driver must be enabled. For CSV content, see CSV options. Decompressed data is staged in a temporary directory; queries do not rewrite the compressed source.

Use .tables to inspect the resulting tables.

MariaDB

The mariadb driver connects to MariaDB using SQLx.

URL format

mariadb://<user>[:<password>]@<host>[:<port>]/<database>[?<options>]

Options

Examples

rsql --url 'mariadb://user:password@localhost:3306/example' -- 'SELECT VERSION();'
rsql --url 'mariadb://user:password@db.example.com/example?ssl-mode=VERIFY_IDENTITY&ssl-ca=/path/ca.pem'

Usage notes

The default TCP port is 3306. Percent-encode reserved characters in credentials and option values. Use .tables and .describe to inspect the selected database. MariaDB and MySQL share the same connection implementation.

MySQL

The mysql driver connects to MySQL using SQLx.

URL format

mysql://<user>[:<password>]@<host>[:<port>]/<database>[?<options>]

Options

Examples

rsql --url 'mysql://user:password@localhost:3306/example' -- 'SELECT VERSION();'
rsql --url 'mysql://user:password@db.example.com/example?ssl-mode=VERIFY_IDENTITY&ssl-ca=/path/ca.pem'

Usage notes

The default TCP port is 3306. Percent-encode reserved characters in credentials and option values. Use .tables and .describe to inspect the selected database. MariaDB and MySQL share the same connection implementation.

OpenDocument Spreadsheet

The ods driver reads OpenDocument Spreadsheet workbooks and exposes sheets as SQL tables.

URL format

ods://<file>[?has_header=<true|false>&skip_rows=<rows>]

Options

Examples

rsql --url 'ods://people.ods'
rsql --url 'ods://people.ods?has_header=false&skip_rows=2'

Usage notes

A workbook with one sheet uses the filename before the first dot as its table name. With multiple sheets, tables are named <file>__<sheet>; non-alphanumeric characters in sheet names become underscores. Use .tables to find the names. Without a header row, columns are named A, B, and so on.

Use a relative path such as ods://people.ods or an absolute path such as ods:///data/people.ods. Percent-encode spaces and URL delimiters in filenames.

Sheets are loaded into an in-memory Polars SQL context. Session changes do not update the workbook.

ORC

The orc driver reads ORC files and exposes their data through SQL.

URL format

orc://<file>

Options

This driver has no format-specific URL query options. The file supplies its schema.

Examples

rsql --url 'orc://people.orc' -- 'SELECT * FROM people LIMIT 10;'

Usage notes

Use a relative path such as orc://people.orc or an absolute path such as orc:///data/people.orc. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

Parquet

The parquet driver reads Parquet files and exposes their data through SQL.

URL format

parquet://<file>

Options

This driver has no format-specific URL query options. The file supplies its schema.

Examples

rsql --url 'parquet://people.parquet' -- 'SELECT * FROM people LIMIT 10;'

Usage notes

Use a relative path such as parquet://people.parquet or an absolute path such as parquet:///data/people.parquet. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

PostgreSQL (rust-postgres)

The postgres driver connects to PostgreSQL using the native rust-postgres client.

URL format

postgres://<user>[:<password>]@<host>[:<port>]/<database>[?<options>]

Options

Examples

rsql --url 'postgres://postgres@localhost:5432/example?sslmode=disable' -- 'SELECT version();'
rsql --url 'postgres://?embedded=true' -- 'SELECT 42;'

Usage notes

The default PostgreSQL port is 5432. Connection parameters are parsed by rust-postgres.

With embedded=true, rsql downloads and starts a managed PostgreSQL instance and creates the embedded database. It stops the server when the connection closes. The first setup needs network access unless the PostgreSQL installation is already cached. For TLS connections, use PostgreSQL (SQLx).

PostgreSQL (SQLx)

The postgresql driver connects to PostgreSQL (SQLx) using the PostgreSQL protocol.

URL format

postgresql://<user>[:<password>]@<host>[:<port>]/<database>[?<options>]

Options

Examples

rsql --url 'postgresql://user:password@localhost:5432/example' -- 'SELECT 1;'
rsql --url 'postgresql://?embedded=true' -- 'SELECT version();'

Usage notes

The connection uses the PostgreSQL wire protocol through SQLx. Specify the service port explicitly; the underlying connection defaults to port 5432. The example uses port 5432. Use .catalogs, .schemas, .tables, and .describe to inspect accessible objects.

With embedded=true, rsql downloads and starts PostgreSQL, creates a database named embedded, and stops the server when the connection closes. Embedded options apply only in this mode. The initial setup needs network access unless the installation is already cached.

Amazon Redshift

The redshift driver connects to Amazon Redshift using the PostgreSQL protocol.

URL format

redshift://<user>[:<password>]@<host>[:<port>]/<database>[?<options>]

Options

Examples

rsql --url 'redshift://user:password@cluster.example.com:5439/example?sslmode=verify-full' -- 'SELECT 1;'

Usage notes

The connection uses the PostgreSQL wire protocol through SQLx. Specify the service port explicitly; the underlying connection defaults to port 5432. The example uses port 5439. Use .catalogs, .schemas, .tables, and .describe to inspect accessible objects.

See PostgreSQL (SQLx) for shared connection options. SQL features and metadata depend on the target service.

SQLite (Rusqlite)

The rusqlite driver opens a local SQLite (Rusqlite) database or a temporary in-memory database.

URL format

rusqlite://[<file>]

Options

There are no driver-specific URL query options. Configure the database using its SQL settings or pragmas.

Examples

rsql --url 'rusqlite://' -- 'SELECT 42;'
rsql --url 'rusqlite://example.sqlite'

Usage notes

Omit the filename for an in-memory database, whose data lasts for the session. A file path creates or opens a persistent database; use three slashes for an absolute Unix path. No database server is required. Use .tables, .views, and .describe to inspect objects.

Database changes are written to the selected file when using a persistent database.

S3

The s3 driver downloads an object from Amazon S3 or an S3-compatible endpoint and opens it with the detected data driver.

URL format

s3://<bucket>/<object>[?region=<region>]
s3://[<access_key_id>:<secret_access_key>@]<host>[:<port>]/<bucket>/<object>?scheme=<http|https>

Options

Examples

rsql --url 's3://example-bucket/people.parquet?region=us-east-1' -- 'SELECT * FROM people LIMIT 10;'
rsql --url 's3://test:test@localhost:9000/bucket/people.csv?scheme=http&force_path_style=true&region=us-east-1'

Usage notes

Without scheme, the URL host is the bucket name. With scheme, the host is a custom endpoint and the first path segment is the bucket. Custom endpoints default to port 443 unless specified.

Credentials default to the AWS SDK configuration chain. The object is downloaded into a temporary directory, then opened by an enabled format driver. Query parameters are forwarded to that driver. Queries do not upload changes back to S3. See Parquet and CSV for format behavior.

ScyllaDB

The scylladb driver provides native CQL connections to ScyllaDB and Scylla Cloud.

URL format

scylladb://[<user>:<password>@]<host>[:<port>]/[<keyspace>][?<options>]

Options

Examples

rsql --url 'scylladb://localhost:9042/my_keyspace'
rsql --url 'scylladb://user:password@node1/my_keyspace?node=node2:9042&datacenter=dc1'
rsql --url 'scylladb://user:password@cloud.example.com/my_keyspace?sslmode=verify-full'

Usage notes

Port 9042, plaintext transport, and no selected keyspace are the defaults. Credentials require both a username and password. URL-encode reserved characters in credentials and paths.

Private Client Routes currently cannot be combined with TLS options. All nodes must be reachable through the configured routes.

Use CQL for queries. Bound parameters use ?; successful non-query statements report 0 changes. Metadata exposes the cluster as a catalog, keyspaces as schemas, and tables, materialized views, columns, primary keys, and indexes. This driver is available on native targets.

Snowflake

The snowflake driver sends SQL through the Snowflake SQL API.

URL format

snowflake://<user>[:<oauth-token>]@<account>.snowflakecomputing.com/[?<options>]

Options

Examples

rsql --url 'snowflake://user:oauth-token@account.snowflakecomputing.com/' -- 'SELECT CURRENT_VERSION();'
rsql --url 'snowflake://user@account.snowflakecomputing.com/?private_key_file=/path/private.pem&public_key_file=/path/public.pem'

Usage notes

The password portion of the URL is an OAuth bearer token, not a Snowflake account password. With no token, both key files are required for key-pair authentication. The connection uses HTTPS. Select database, schema, warehouse, and role through SQL as supported by the service; these are not rsql URL options.

SQLite (SQLx)

The sqlite driver opens a local SQLite (SQLx) database or a temporary in-memory database.

URL format

sqlite://[<file>]

Options

Examples

rsql --url 'sqlite://' -- 'SELECT 42;'
rsql --url 'sqlite://example.sqlite'

Usage notes

Omit the filename for an in-memory database, whose data lasts for the session. A file path creates or opens a persistent database; use three slashes for an absolute Unix path. No database server is required. Use .tables, .views, and .describe to inspect objects.

URL query options apply to file/named database URLs; a bare sqlite:// opens the default in-memory database.

SQL Server

The sqlserver driver connects to Microsoft SQL Server using Tiberius.

URL format

sqlserver://[<user>[:<password>]@]<host>[:<port>][/<database>][?<options>]

Options

Examples

rsql --url 'sqlserver://user:password@db.example.com:1433/example?encrypt=true&ApplicationName=rsql' -- 'SELECT @@VERSION;'
rsql --url 'sqlserver://localhost/example?IntegratedSecurity=true'

Usage notes

Options are case-insensitive. The default host is localhost and the default port is 1433. The server chooses the database if omitted. Boolean options accept true, false, yes, and no. Use .schemas, .tables, and .describe to inspect accessible objects.

TSV

The tsv driver loads separated text fields into Polars SQL.

URL format

tsv://<file>[?has_header=<true|false>&quote=<char>&skip_rows=<rows>]

Options

Examples

rsql --url 'tsv://people.tsv?quote=%22' -- 'SELECT * FROM people LIMIT 10;'

Usage notes

The field separator is fixed to tab.

Use a relative path such as tsv://people.tsv or an absolute path such as tsv:///data/people.tsv. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

XML

The xml driver reads XML data and queries it with Polars SQL.

URL format

xml://<file>[?infer_schema_length=<rows>&ignore_errors=<true|false>]

Options

Examples

rsql --url 'xml://people.xml' -- 'SELECT * FROM people LIMIT 10;'
rsql --url 'xml://people.xml?infer_schema_length=0'

Usage notes

The driver converts XML elements and attributes into records before loading them.

Use a relative path such as xml://people.xml or an absolute path such as xml:///data/people.xml. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

XZ

The xz driver decompresses a local XZ file and opens the contents with the matching data driver.

URL format

xz://<file>[?<format-options>]

Options

There are no decompression-specific query options. Query parameters are forwarded to the detected data driver; for example, CSV accepts has_header, quote, and skip_rows.

Examples

rsql --url 'xz://people.csv.xz?quote=%22' -- 'SELECT * FROM people;'

Usage notes

Keep the original extension before .xz so the decompressed filename identifies the data format. The corresponding format driver must be enabled. For CSV content, see CSV options. Decompressed data is staged in a temporary directory; queries do not rewrite the compressed source.

Use .tables to inspect the resulting tables.

YAML

The yaml driver reads YAML data and queries it with Polars SQL.

URL format

yaml://<file>[?infer_schema_length=<rows>&ignore_errors=<true|false>]

Options

Examples

rsql --url 'yaml://people.yaml' -- 'SELECT * FROM people LIMIT 10;'
rsql --url 'yaml://people.yaml?infer_schema_length=0'

Usage notes

The driver converts YAML data into JSON records before loading them.

Use a relative path such as yaml://people.yaml or an absolute path such as yaml:///data/people.yaml. Percent-encode spaces and URL delimiters in filenames.

The file is loaded into an in-memory Polars SQL context. Its table name is the filename before the first dot: people.csv becomes people. Use .tables and .describe people to inspect the imported data. Query results and session changes do not write back to the source file.

Zstandard

The zstd driver decompresses a local Zstandard file and opens the contents with the matching data driver.

URL format

zstd://<file>[?<format-options>]

Options

There are no decompression-specific query options. Query parameters are forwarded to the detected data driver; for example, CSV accepts has_header, quote, and skip_rows.

Examples

rsql --url 'zstd://people.csv.zst?quote=%22' -- 'SELECT * FROM people;'

Usage notes

Keep the original extension before .zst so the decompressed filename identifies the data format. The corresponding format driver must be enabled. For CSV content, see CSV options. Decompressed data is staged in a temporary directory; queries do not rewrite the compressed source.

Use .tables to inspect the resulting tables.

Appendix

FAQ & Tips & Tricks

Frequently Asked Questions

Q: rsql fails to connect to my database. What should I check?

• Ensure your connection string (URL) is correct and credentials are valid.
• Check that the database server is running and accessible from your machine.
• Verify that the required driver is installed and supported (see drivers).
• For cloud databases, ensure your IP is whitelisted and network/firewall rules allow access.

Q: How do I change the output format (CSV, JSON, etc.)?

• Use the .format command or set the format option in your rsql.toml (see configuration).

Q: How do I set or change my locale?

• Use the .locale command (see locale command) or set the locale option in your rsql.toml.

Q: Where is the configuration file stored?

• On Unix-like systems: $HOME/.rsql/rsql.toml
• On Windows: %APPDATA%\rsql\rsql.toml

Q: How do I contribute a new translation or improve an existing one?

• See Supported Locales for instructions.

Tips & Tricks

• Use command history and smart completions to speed up repetitive tasks.
• Use the .read command to execute SQL from a file.
• Use the .output command to redirect results to a file.
• For large result sets, use the limit option or .limit command to avoid overwhelming your terminal.
• Use the .help command to see available commands and their usage.

For more troubleshooting and advanced usage, see the Configuration File and Commands sections.

Configuration File (rsql.toml)

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

Why use rsql.toml?

The configuration file allows you to customize rsql's behavior, appearance, and output to fit your workflow. Use it to set defaults for output format, locale, logging, themes, and more. This is especially useful for scripting, automation, or when working in different environments (dev, staging, prod).

Configuration Options Summary

Example rsql.toml

[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

Troubleshooting Configuration

• If rsql does not pick up changes, ensure you are editing the correct rsql.toml file ( see FAQ).
• Invalid TOML syntax will cause rsql to fail to start or ignore the config. Validate your file with a TOML linter.
• For option-specific issues, see the relevant command documentation ( e.g., format, locale).

For more details on each option, see the Commands section.

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.

Locales affect the language of messages, prompts, and number formatting in rsql. You can set your preferred locale using the .locale command or by specifying the locale option in your rsql.toml configuration file. If not set, rsql will attempt to detect your system locale, defaulting to en (US English) if detection fails.

Contributing Translations

Most translations are machine-generated and may be imperfect. To contribute improvements or add a new locale:

1. Fork the rsql repository.
2. Add or update the relevant translation files in the locales/ directory.
3. Submit a pull request with your changes.
4. For guidance, see the project's contribution guidelines.

Troubleshooting Locale Issues

• If you see untranslated or garbled text, ensure your locale is supported and correctly set.
• If your locale is not listed, contribute a translation as described above.
• Some output (such as database errors) may not be localized if not supported by the driver.

Available Locales