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, Snowflake, DuckDB, LibSQL, 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.

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;"

LibSQL (in-memory)

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 (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();"

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, including its columns, data types, and constraints. This is useful for understanding the structure of your data, especially when working with unfamiliar tables or preparing queries.

Usage

.describe [table]

When to use

• Use .describe to inspect table schemas before writing queries or performing data transformations.
• Helpful for data exploration, debugging, and documentation.

Examples

Describe the table named users:

.describe users

Describe the current table (if context is set):

.describe

Troubleshooting

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

Related

• See also: tables, schemas, and indexes.

Demonstration

drivers

Usage

.drivers

Description

The drivers command displays the available data drivers.

Examples

Show the available drivers:

.drivers

Demonstration

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

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.

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

• See also: 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

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