### Build usql with Custom Drivers

Source: https://github.com/xo/usql/blob/master/README.md

Installs usql with additional drivers by specifying build tags. This example includes Avatica and ODBC drivers.

```go
# build/install with base, Avatica, and ODBC drivers
$ go install -tags 'avatica odbc' github.com/xo/usql@master
```

--------------------------------

### Build usql with Specific Drivers (Example)

Source: https://github.com/xo/usql/blob/master/README.md

An example of building usql from source, excluding certain base drivers and including others like Cassandra and moderncsqlite.

```go
# build excluding the base drivers, and including cassandra and moderncsqlite
$ go build -tags 'no_postgres no_oracle no_sqlserver no_sqlite3 cassandra moderncsqlite'
```

--------------------------------

### Install usql via Go

Source: https://github.com/xo/usql/blob/master/README.md

Installs the usql CLI tool using the Go programming language's installation command. Supports installing the latest version or a version with specific build tags.

```go
# Install latest usql version with base drivers
$ go install github.com/xo/usql@latest
```

```go
# Install usql with most drivers (see build tags info)
$ go install -tags most github.com/xo/usql@latest
```

--------------------------------

### Build usql with Base Drivers

Source: https://github.com/xo/usql/blob/master/README.md

Installs usql using `go install`, including the default set of drivers (PostgreSQL, MySQL, SQLite3, Microsoft SQL Server, Oracle, CSVQ).

```go
# build/install with base drivers (PostgreSQL, MySQL, SQLite3, Microsoft SQL Server,
# Oracle, CSVQ)
$ go install github.com/xo/usql@master
```

--------------------------------

### Install usql via AUR

Source: https://github.com/xo/usql/blob/master/README.md

Installs usql from the Arch User Repository (AUR) using the yay helper or by building from source with makepkg.

```shell
# Install usql with most drivers using yay
$ yay -S usql
```

```shell
# Build and install using makepkg
$ git clone https://aur.archlinux.org/usql.git && cd usql
$ makepkg -si
```

--------------------------------

### Build usql with Most/All Drivers

Source: https://github.com/xo/usql/blob/master/README.md

Installs usql including a broad set of drivers. The `most` tag includes common drivers (excluding CGO and problematic ones), while `all` includes all available drivers.

```go
# build/install with most drivers (excludes CGO drivers and problematic drivers)
$ go install -tags most github.com/xo/usql@master

# build/install all drivers (includes CGO drivers and problematic drivers)
$ go install -tags all github.com/xo/usql@master
```

--------------------------------

### Install usql via Scoop (Windows)

Source: https://github.com/xo/usql/blob/master/README.md

Installs the usql CLI tool on Windows using the Scoop package manager. This includes setting the execution policy if necessary.

```powershell
# Optional: Needed to run a remote script the first time
> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install scoop if not already installed
> irm get.scoop.sh | iex

# Install usql with scoop
> scoop install usql
```

--------------------------------

### usql Command-Line Connection Examples

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates how to connect to databases using the usql command-line interface with different DSN formats and options.

```sh
# connect to a vitess database:
$ usql vt://user:pass@host:3306/mydatabase
```

```sh
$ usql
(not connected)=> \c vitess://user:pass@host:3306/mydatabase
```

```sh
$ usql
(not connected)=> \copy csvq://. pg://localhost/ 'select * ....' 'myTable'
```

```sh
# connect to a postgres database
$ usql postgres://booktest@localhost/booktest
```

```sh
# connect to an oracle database
$ usql oracle://user:pass@host/oracle.sid
```

```sh
# connect to a postgres database and run the commands contained in script.sql
$ usql pg://localhost/ -f script.sql
```

--------------------------------

### Connect to Oracle using usql

Source: https://github.com/xo/usql/blob/master/README.md

Examples for establishing connections to Oracle databases using common aliases and specifying host and port.

```sh
$ usql or://user:pass@host/sid
$ usql oracle://user:pass@host:port/sid
$ usql or://
```

--------------------------------

### Download and Install DSDriver

Source: https://github.com/xo/usql/blob/master/contrib/db2/README.md

Downloads the IBM Data Server Driver package and installs it using the provided installation script. Assumes the driver package is downloaded to the user's Downloads directory.

```shell
$ ls ~/Downloads/ibm_data_server_driver_package_linuxx64_v11.5.tar.gz
/home/ken/Downloads/ibm_data_server_driver_package_linuxx64_v11.5.tar.gz
$ sudo ./install-dsdriver.sh
```

--------------------------------

### Run DB2 Container

Source: https://github.com/xo/usql/blob/master/contrib/db2/README.md

Starts a DB2 container using Podman, initiating the DB2 service and preparing it for connection.

```shell
$ ../podman-run.sh db2 -u
```

--------------------------------

### Install usql via Homebrew

Source: https://github.com/xo/usql/blob/master/README.md

Installs the usql CLI tool using the Homebrew package manager on macOS and Linux. It can also be installed with ODBC support using a specific flag.

```shell
# Install usql with most drivers
$ brew install xo/xo/usql
```

```shell
# Add xo tap
$ brew tap xo/xo

# Install usql with odbc support
$ brew install --with-odbc usql
```

--------------------------------

### macOS Installation Troubleshooting

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates a common error encountered on macOS due to missing library dependencies (like libicuuc) and the command to resolve it using Homebrew.

```shell
$ usql
dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicuuc.68.dylib
  Referenced from: /Users/user/.local/bin/usql
  Reason: image not found
Abort trap: 6
```

```shell
$ brew install icu4c
```

```shell
$ usql
(not connected)=>
```

--------------------------------

### Run Specific usql Docker Version

Source: https://github.com/xo/usql/blob/master/README.md

Example of running a specific version of the usql Docker image.

```sh
$ docker run --rm -it docker.io/usql/usql:0.19.3
```

--------------------------------

### Connect to SQL Server using usql

Source: https://github.com/xo/usql/blob/master/README.md

Provides examples for connecting to SQL Server databases, including different aliases and specifying instance names. Also shows connecting via Windows domain authentication.

```sh
$ usql sqlserver://user:pass@host/instancename/dbname
$ usql ms://user:pass@host/dbname
$ usql ms://user:pass@host/instancename/dbname
$ usql mssql://user:pass@host:port/dbname
$ usql ms://
$ runas /user:ACME\wiley /netonly "usql mssql://host/dbname/"
```

--------------------------------

### Install unixODBC

Source: https://github.com/xo/usql/blob/master/contrib/db2/README.md

Installs the unixODBC package and development files required for ODBC connectivity on Debian/Ubuntu-based systems and Arch Linux.

```shell
$ sudo aptitude install unixodbc unixodbc-bin unixodbc-dev
$ yay -S unixodbc
```

--------------------------------

### Build usql Excluding Drivers

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates how to exclude specific drivers during the build process using `no_<driver>` tags. This example excludes Avatica, Couchbase, and PostgreSQL.

```go
# build/install most drivers, excluding Avatica, Couchbase, and PostgreSQL
$ go install -tags 'most no_avatica no_couchbase no_postgres' github.com/xo/usql@master
```

--------------------------------

### Execute SQL Queries and Meta-Commands in usql

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates connecting to a SQLite database, creating a table, inserting data, and selecting records. It also shows the use of \p to print the current query and \g to execute it. The example includes switching to a PostgreSQL connection and handling authentication errors.

```sh
$ usql sqlite://example.sqlite3
Connected with driver sqlite3 (SQLite3 3.17.0)
Type "help" for help.

sq:example.sqlite3=> create table test (test_id int, name string);
CREATE TABLE
sq:example.sqlite3=> insert into test (test_id, name) values (1, 'hello');
INSERT 1
sq:example.sqlite3=> select * from test;
  test_id | name
+---------+-------+
        1 | hello
(1 rows)

sq:example.sqlite3=> select * from test
sq:example.sqlite3-> \p
select * from test
sq:example.sqlite3-> \g
  test_id | name
+---------+-------+
        1 | hello
(1 rows)

sq:example.sqlite3=> \c postgres://booktest@localhost
error: pq: 28P01: password authentication failed for user "booktest"
Enter password:
Connected with driver postgres (PostgreSQL 9.6.6)
pg:booktest@localhost=> select * from authors;
  author_id |      name
+-----------+----------------+
          1 | Unknown Master
          2 | blah
          3 | foobar
(3 rows)

pg:booktest@localhost=>
```

--------------------------------

### Run Activation Script

Source: https://github.com/xo/usql/blob/master/contrib/ignite/README.md

This script activates the database. It is run after starting the database.

```sh
$ ./activate.sh

```

--------------------------------

### usql Context Completion Examples

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates context completion in the usql interactive shell using the <Tab> key. This feature aids in completing SQL queries and backslash commands.

```sh
$ usql
(not connected)=> select * f<Tab>
fetch            from             full outer join
```

```sh
$ usql my://
Connected with driver mysql (10.8.3-MariaDB-1:10.8.3+maria~jammy)
Type "help" for help.

my:root@=> \g<Tab>
\g     \gexec \gset  \gx
```

--------------------------------

### Connect to ADOdb OLE DB using usql

Source: https://github.com/xo/usql/blob/master/README.md

Examples for connecting to OLE DB data sources on Windows using the ADOdb driver, including specifying the provider and connection properties.

```sh
$ usql adodb://Microsoft.Jet.OLEDB.4.0/myfile.mdb
$ usql "adodb://Microsoft.ACE.OLEDB.12.0/?Extended+Properties=\"Text;HDR=NO;FMT=Delimited\""
```

--------------------------------

### Connect to PostgreSQL using usql

Source: https://github.com/xo/usql/blob/master/README.md

Examples for connecting to PostgreSQL databases using various aliases and connection string formats. Includes default connection via Unix domain socket and connecting with SSL disabled.

```sh
$ usql pg://user:pass@host/dbname
$ usql pgsql://user:pass@host/dbname
$ usql postgres://user:pass@host:port/dbname
$ usql pg://
$ usql /var/run/postgresql
$ usql pg://user:pass@host/dbname?sslmode=disable
```

--------------------------------

### usql \copy Importing Data from CSV

Source: https://github.com/xo/usql/blob/master/README.md

Shows a comprehensive example of importing data from CSV files into a SQLite database using the \copy command with the csvq driver. It includes setting variables, connecting to databases, creating tables, and copying data.

```shell
$ cat authors.csv
author_id,name
1,Isaac Asimov
2,Stephen King
$ cat books.csv
book_id,author_id,title
1,1,I Robot
2,2,Carrie
3,2,Cujo
$ usql
(not connected)=> -- setting variables to make connections easier
(not connected)=> \set SOURCE_DSN csvq://.
(not connected)=> \set DESTINATION_DSN sqlite3:booktest.db
(not connected)=> -- connecting to the destination and creating the schema
(not connected)=> \c :DESTINATION_DSN
Connected with driver sqlite3 (SQLite3 3.38.5)
(sq:booktest.db)=> create table authors (author_id integer, name text);
CREATE TABLE
(sq:booktest.db)=> create table books (book_id integer not null primary key autoincrement, author_id integer, title text);
CREATE TABLE
(sq:booktest.db)=> -- adding an extra row to books prior to copying
(sq:booktest.db)=> insert into books (author_id, title) values (1, 'Foundation');
INSERT 1
(sq:booktest.db)=> -- disconnecting to demonstrate that \copy opens new database connections
(sq:booktest.db)=> \disconnect
(not connected)=> -- copying data from SOURCE -> DESTINATION
(not connected)=> \copy :SOURCE_DSN :DESTINATION_DSN 'select * from authors' authors
COPY 2
(not connected)=> \copy :SOURCE_DSN :DESTINATION_DSN 'select author_id, title from books' 'books(author_id, title)'
COPY 3
(not connected)=> \c :DESTINATION_DSN
Connected with driver sqlite3 (SQLite3 3.38.5)
(sq:booktest.db)=> select * from authors;
 author_id |     name
-----------+--------------
         1 | Isaac Asimov
         2 | Stephen King
(2 rows)

sq:booktest.db=> select * from books;
 book_id | author_id |   title
---------+-----------+------------
       1 |         1 | Foundation
       2 |         1 | I Robot
       3 |         2 | Carrie
       4 |         2 | Cujo
(4 rows)
```

--------------------------------

### usql Time Formatting Constants

Source: https://github.com/xo/usql/blob/master/README.md

A reference of available time format constants supported by usql, derived from Go's time formatting package. Each constant maps to a specific format string and provides an example display.

```APIDOC
Time Constants Overview:

Constant    | Format                          | Display Example
------------|---------------------------------|-----------------
ANSIC       | Mon Jan _2 15:04:05 2006         | Wed Aug  3 20:12:48 2022
UnixDate    | Mon Jan _2 15:04:05 MST 2006     | Wed Aug  3 20:12:48 UTC 2022
RubyDate    | Mon Jan 02 15:04:05 -0700 2006    | Wed Aug 03 20:12:48 +0000 2022
RFC822      | 02 Jan 06 15:04 MST             | 03 Aug 22 20:12 UTC
RFC822Z     | 02 Jan 06 15:04 -0700           | 03 Aug 22 20:12 +0000
RFC850      | Monday, 02-Jan-06 15:04:05 MST  | Wednesday, 03-Aug-22 20:12:48 UTC
RFC1123     | Mon, 02 Jan 2006 15:04:05 MST   | Wed, 03 Aug 2022 20:12:48 UTC
RFC1123Z    | Mon, 02 Jan 2006 15:04:05 -0700 | Wed, 03 Aug 2022 20:12:48 +0000
RFC3339     | 2006-01-02T15:04:05Z07:00       | 2022-08-03T20:12:48Z
RFC3339Nano | 2006-01-02T15:04:05.999999999Z07:00 | 2022-08-03T20:12:48.693257Z
Kitchen     | 3:04PM                          | 8:12PM
Stamp       | Jan _2 15:04:05                  | Aug  3 20:12:48
StampMilli  | Jan _2 15:04:05.000             | Aug  3 20:12:48.693
StampMicro  | Jan _2 15:04:05.000000          | Aug  3 20:12:48.693257
StampNano   | Jan _2 15:04:05.000000000       | Aug  3 20:12:48.693257000

Note: Display examples generated using timestamp 2022-08-03T20:12:48.693257Z.
```

--------------------------------

### Configure usql Runtime Configuration (RC) File

Source: https://github.com/xo/usql/blob/master/README.md

Customize usql startup behavior by defining settings and commands in the .usqlrc file. This file is executed automatically on startup.

```sh
$ cat $HOME/.usqlrc
\echo WELCOME TO THE JUNGLE `date`
\set SYNTAX_HL_STYLE paraiso-dark
\set PROMPT1 "\033[32m%S%m%/%R%#\033[0m"
```

```sh
$ usql --no-init pg://
```

```APIDOC
\set SYNTAX_HL_STYLE <style_name>
  Sets the syntax highlighting style.
  Example: \set SYNTAX_HL_STYLE paraiso-dark
```

```APIDOC
\set PROMPT1 <prompt_string>
  Sets the primary prompt string.
  Example: \set PROMPT1 "\033[32m%S%m%/%R%#\033[0m"
```

--------------------------------

### Connect to Cassandra using usql

Source: https://github.com/xo/usql/blob/master/README.md

Shows how to connect to Cassandra databases using its aliases and specifying keyspace.

```sh
$ usql ca://user:pass@host/keyspace
$ usql cassandra://host/keyspace
$ usql cql://host/
$ usql ca://
```

--------------------------------

### Run usql with Docker (PostgreSQL)

Source: https://github.com/xo/usql/blob/master/README.md

Shows how to run a PostgreSQL container and then connect to it using the usql Docker image, leveraging host networking for simplicity.

```sh
# run postgres locally
$ docker run --detach --rm --name=postgres --publish=5432:5432 --env=POSTGRES_PASSWORD=P4ssw0rd docker.io/usql/postgres

# connect to local postgres instance
$ docker run --rm --network host -it docker.io/usql/usql:latest postgres://postgres:P4ssw0rd@localhost
Connected with driver postgres (PostgreSQL 16.3 (Debian 16.3-1.pgdg120+1))
Type "help" for help.

pg:postgres@localhost=> \q
```

--------------------------------

### Verify DB2 Connection

Source: https://github.com/xo/usql/blob/master/contrib/db2/README.md

Executes a validation script to confirm that the DB2 client can successfully connect to the DB2 server.

```shell
$ ./db2cli-validate.sh
```

--------------------------------

### Connect using named connections and ODBC

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates connecting to databases using a named connection defined in a configuration file and connecting via ODBC drivers, showing how to specify driver details.

```sh
$ usql my_named_connection
$ usql odbc+DB2://user:pass@localhost/dbname
$ usql odbc+PostgreSQL+ANSI://user:pass@localhost/dbname?TraceFile=/path/to/trace.log
```

--------------------------------

### Run usql with Docker (SQLite)

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates running the usql container interactively, mounting a local directory for data, and connecting to a SQLite database.

```sh
$ docker run --rm -it --volume $(pwd)/data:/data docker.io/usql/usql:latest sqlite3://data/test.db
Trying to pull docker.io/usql/usql:latest...
Getting image source signatures
Copying blob af48168d69d8 done   | 
Copying blob efc2b5ad9eec skipped: already exists
Copying config 917ceb411d done   | 
Writing manifest to image destination
Connected with driver sqlite3 (SQLite3 3.45.1)
Type "help" for help.

sq:data/test.db=> \q
```

--------------------------------

### usql Driver Information Command

Source: https://github.com/xo/usql/blob/master/README.md

Shows how to use the internal `\drivers` command within usql to list the database drivers that were included in the current build.

```APIDOC
\drivers
  - Lists available database drivers and their aliases.
  - Example Output:
    Available Drivers:
      cql [ca, scy, scylla, datastax, cassandra]
      memsql (mysql) [me]
      moderncsqlite [mq, sq, file, sqlite, sqlite3, modernsqlite]
      mysql [my, maria, aurora, mariadb, percona]
      tidb (mysql) [ti]
      vitess (mysql) [vt]
  - The output details the internal driver name, primary URL scheme, available aliases, and the underlying driver for wire-compatible drivers.
```

--------------------------------

### Connect to SQLite using usql

Source: https://github.com/xo/usql/blob/master/README.md

Illustrates connecting to SQLite databases, including specifying existing files and creating new databases when the file does not exist.

```sh
$ usql dbname.sqlite3
$ usql sq://path/to/dbname.sqlite3
$ usql sqlite3://path/to/dbname.sqlite3
$ usql file:/path/to/dbname.sqlite3
```

--------------------------------

### Connecting to a Database using a Named Connection

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates how to use a pre-defined named connection from the configuration file to connect to a database via the usql CLI.

```sh
$ usql my_godror_conn
Connected with driver godror (Oracle Database 23.0.0.0.0)
Type "help" for help.

gr:system@localhost/free=>
```

--------------------------------

### Copy ODBC and CLI Configurations

Source: https://github.com/xo/usql/blob/master/contrib/db2/README.md

Appends the custom ODBC configuration to the system's odbcinst.ini file and copies the DB2 CLI configuration files to the driver's configuration directory.

```shell
$ cat odbcinst.ini | sudo tee -a /etc/odbcinst.ini
$ sudo cp {db2cli.ini,db2dsdriver.cfg} /opt/db2/clidriver/cfg/
```

--------------------------------

### Sequence Definition: public.film_film_id_seq

Source: https://github.com/xo/usql/blob/master/drivers/testdata/pgsql.descTable.expected.txt

Defines the 'film_film_id_seq' sequence, which is used to generate unique identifiers for films. It is a bigint sequence starting from 1, incrementing by 1, and does not cycle. This sequence is typically used for primary key generation.

```APIDOC
Sequence: public.film_film_id_seq

Type: bigint
Start: 1
Min: 1
Max: 9223372036854775807
Increment: 1
Cycles: NO
```

--------------------------------

### Help Meta Commands

Source: https://github.com/xo/usql/blob/master/README.md

Commands to display help information for usql's meta commands, command-line options, and special variables.

```APIDOC
Help Commands:
  \? [commands]
    - Show help on usql's meta (backslash) commands.
  \? options
    - Show help on usql command-line options.
  \? variables
    - Show help on special usql variables.
```

--------------------------------

### Connect to MySQL using usql

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates connecting to MySQL databases using its aliases and standard URL formats. Includes connecting via a Unix domain socket file.

```sh
$ usql my://user:pass@host/dbname
$ usql mysql://user:pass@host:port/dbname
$ usql my://
$ usql /var/run/mysqld/mysqld.sock
```

--------------------------------

### Database Sequence: public.film_film_id_seq

Source: https://github.com/xo/usql/blob/master/drivers/testdata/pgsql.descTable.golden.txt

Defines the properties of the 'film_film_id_seq' sequence used for generating film IDs. It specifies the data type, starting value, minimum and maximum bounds, increment step, cycle behavior, and cache size.

```APIDOC
Sequence "public.film_film_id_seq"
  Type  | Start | Minimum |       Maximum       | Increment | Cycles? | Cache 
--------+-------+---------+---------------------+-----------+---------+-------
 bigint |     1 |       1 | 9223372036854775807 |         1 | no      |     1
```

--------------------------------

### General Meta Commands

Source: https://github.com/xo/usql/blob/master/README.md

Commands for general usql operation, including quitting, viewing copyright information, and listing available drivers.

```APIDOC
General Commands:
  \q, \quit
    - Quit usql.
  \copyright
    - Show usage and distribution terms for usql.
  \drivers
    - Show database drivers available to usql.
```

--------------------------------

### Informational Meta Commands

Source: https://github.com/xo/usql/blob/master/README.md

Commands to list and describe database objects like tables, views, functions, schemas, and databases.

```APIDOC
Informational Commands:
  \d[S+] [NAME]
    - List tables, views, and sequences, or describe a table, view, sequence, or index.
  \da[S+] [PATTERN]
    - List aggregates.
  \df[S+] [PATTERN]
    - List functions.
  \di[S+] [PATTERN]
    - List indexes.
  \dm[S+] [PATTERN]
    - List materialized views.
  \dn[S+] [PATTERN]
    - List schemas.
  \dp[S] [PATTERN]
    - List table, view, and sequence access privileges.
  \ds[S+] [PATTERN]
    - List sequences.
  \dt[S+] [PATTERN]
    - List tables.
  \dv[S+] [PATTERN]
    - List views.
  \l[+]
    - List databases.
  \ss[+] [TABLE|QUERY] [k]
    - Show stats for a table or a query.
```

--------------------------------

### usql \copy Reusing Connections with Variables

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates best practices for scripting \copy operations by setting connection variables using \set and managing passwords in a separate file ($HOME/.usqlpass) for easier reuse and security.

```shell
$ cat $HOME/.usqlpass
postgres:*:*:*:postgres:P4ssw0rd
godror:*:*:*:system:P4ssw0rd
$ usql
Type "help" for help.

(not connected)=> \set pglocal postgres://postgres@localhost:49153?sslmode=disable
(not connected)=> \set orlocal godror://system@localhost:1521/orasid
(not connected)=> \copy :pglocal :orlocal 'select staff_id, first_name from staff' 'staff(staff_id, first_name)'
COPY 18
```

--------------------------------

### usql Command-line Options

Source: https://github.com/xo/usql/blob/master/README.md

Lists and explains the supported command-line flags for the usql universal command-line interface. These options control execution, file handling, output formatting, and configuration.

```sh
usql, the universal command-line interface for SQL databases

Usage:
  usql [flags]... [DSN]

Arguments:
  DSN   database url or connection name

Flags:
  -c, --command COMMAND                     run only single command (SQL or internal) and exit
  -f, --file FILE                           execute commands from file and exit
  -w, --no-password                         never prompt for password
  -X, --no-init                             do not execute initialization scripts (aliases: --no-rc --no-psqlrc --no-usqlrc)
  -o, --out FILE                            output file
  -W, --password                            force password prompt (should happen automatically)
  -1, --single-transaction                  execute as a single transaction (if non-interactive)
  -v, --set NAME=VALUE                      set variable NAME to VALUE (see \set command, aliases: --var --variable)
  -N, --cset NAME=DSN                       set named connection NAME to DSN (see \cset command)
  -P, --pset VAR=ARG                        set printing option VAR to ARG (see \pset command)
  -F, --field-separator FIELD-SEPARATOR     field separator for unaligned and CSV output (default "|" and ",")
  -R, --record-separator RECORD-SEPARATOR   record separator for unaligned and CSV output (default \n)
  -T, --table-attr TABLE-ATTR               set HTML table tag attributes (e.g., width, border)
  -A, --no-align                            unaligned table output mode
  -H, --html                                HTML table output mode
  -t, --tuples-only                         print rows only
  -x, --expanded                            turn on expanded table output
  -z, --field-separator-zero                set field separator for unaligned and CSV output to zero byte
  -0, --record-separator-zero               set record separator for unaligned and CSV output to zero byte
  -J, --json                                JSON output mode
  -C, --csv                                 CSV output mode
  -G, --vertical                            vertical output mode
  -q, --quiet                               run quietly (no messages, only query output)
      --config string                       config file
  -V, --version                             output version information, then exit
  -?, --help                                show this help, then exit
```

--------------------------------

### usql CLI Connection and Copy Commands

Source: https://github.com/xo/usql/blob/master/README.md

Details on using usql's command-line interface for establishing database connections and performing data copy operations. Includes interactive mode commands.

```APIDOC
usql CLI Commands:

Connect to a database:
  usql <dsn>
    Connects to the specified database using its Data Source Name (DSN) or URL.
    Example: $ usql postgres://user:pass@host:5432/dbname

Interactive Connection:
  (not connected)=> \c <dsn>
    Establishes a connection to a database from within the usql interactive shell.
    Example: (not connected)=> \c vitess://user:pass@host:3306/mydatabase

Copy Data:
  \copy <source_dsn> <destination_dsn> '<query>' <table_name>
    Copies data from a source database (specified by source_dsn) to a destination table in another database (specified by destination_dsn) based on a provided SQL query.
    Example: $ usql
             (not connected)=> \copy csvq://. pg://localhost/ 'select * ....' 'myTable'

Run Script:
  usql <dsn> -f <script_file>
    Connects to the specified database and executes SQL commands from a given script file.
    Example: $ usql pg://localhost/ -f script.sql
```

--------------------------------

### usql \copy with Variables and Quoting

Source: https://github.com/xo/usql/blob/master/README.md

Demonstrates how to use shell variables for database connection strings (DSNs) and the necessity of quoting query and table names that contain spaces when using the \copy command.

```shell
$ usql
(not connected)=> echo :SOURCE_DSN :DESTINATION_DSN
pg://postgres:P4ssw0rd@localhost/ mysql://localhost
(not connected)=> \copy :SOURCE_DSN :DESTINATION_DSN 'select * from mySourceTable' 'myDestination(colA, colB)'
COPY 2
```

--------------------------------

### List Variable Help with \? variables

Source: https://github.com/xo/usql/blob/master/README.md

The \? variables command provides help information and lists all special variables recognized by usql, including those that modify runtime behavior like syntax highlighting.

```APIDOC
\? variables
  - Displays help information and lists all recognized usql variables.
  - Example:
    (not connected)=> \? variables
```

--------------------------------

### Variable and Formatting Meta Commands

Source: https://github.com/xo/usql/blob/master/README.md

Commands for setting and unsetting usql variables, configuring output formatting, and controlling display modes.

```APIDOC
Variables and Formatting Commands:
  \set [NAME [VALUE]]
    - Set a usql application variable, or show all variables if no parameters.
  \unset NAME
    - Unset (delete) a usql application variable.
  \pset [NAME [VALUE]]
    - Set a table print formatting option, or show all options if no parameters.
  \a
    - Toggle between unaligned and aligned output mode.
  \C [TITLE]
    - Set the table title, or unset if none.
  \f [SEPARATOR]
    - Show or set the field separator for unaligned query output.
  \H
    - Toggle HTML output mode.
  \T [ATTRIBUTES]
    - Set HTML <table> tag attributes, or unset if none.
  \t [on|off]
    - Show only rows (toggle table headers).
```

--------------------------------

### Adding a New Driver to usql

Source: https://github.com/xo/usql/blob/master/CONTRIBUTING.md

Steps required to integrate a new database driver into the usql project. This involves schema registration, Go package creation, code generation, dependency management, testing, and documentation updates.

```go
package drivers

import (
	_ "github.com/xo/usql/drivers/your_driver"
)

func init() {
	// drivers.Register() is called internally by the imported package
}
```

```shell
internal/gen.sh
```

```shell
go get <new_driver_module>
go mod tidy
```

--------------------------------

### usql Configuration File Structure

Source: https://github.com/xo/usql/blob/master/README.md

Defines the structure and usage of the usql YAML configuration file, including how to define named connections and initialization scripts.

```yaml
connections:
  my_couchbase_conn: couchbase://Administrator:P4ssw0rd@localhost
  my_clickhouse_conn: clickhouse://clickhouse:P4ssw0rd@localhost
  my_godror_conn:
    protocol: godror
    username: system
    password: P4ssw0rd
    hostname: localhost
    port: 1521
    database: free

init: |
  \echo welcome to the jungle `date`
  \set SYNTAX_HL_STYLE paraiso-dark
  \set PROMPT1 '\033[32m%S%M/%R%#\033[0m '
```

--------------------------------

### usql Scheme: Alibaba Tablestore

Source: https://github.com/xo/usql/blob/master/README.md

Defines the connection scheme and aliases for Alibaba Tablestore in usql. It uses the 'ots' scheme and supports aliases like 'ot' and 'tablestore'. The underlying driver is github.com/aliyun/aliyun-tablestore-go-sql-driver.

```APIDOC
Database: Alibaba Tablestore
Scheme: ots
Aliases: ot, tablestore
Driver: github.com/aliyun/aliyun-tablestore-go-sql-driver
```

--------------------------------

### Query Execution Meta Commands

Source: https://github.com/xo/usql/blob/master/README.md

Commands for executing SQL queries, controlling output format, and managing query parameters.

```APIDOC
Query Execute Commands:
  \g [(OPTIONS)] [FILE] or ;
    - Execute query and send results to file or pipe.
  \go
    - Alias for \g.
  \G [(OPTIONS)] [FILE]
    - Execute query forcing vertical output mode.
  \ego
    - Alias for \G.
  \gx [(OPTIONS)] [FILE]
    - Execute query forcing expanded output mode.
  \gexec
    - Execute query and execute each value of the result.
  \gset [PREFIX]
    - Execute query and store results in usql variables.
  \bind [PARAM]...
    - Set query parameters.
  \timing [on|off]
    - Toggle timing of commands.
```

--------------------------------

### Connection Meta Commands

Source: https://github.com/xo/usql/blob/master/README.md

Commands for managing database connections, including connecting, disconnecting, and changing passwords.

```APIDOC
Connection Commands:
  \c DSN or \c NAME
    - Connect to a DSN or named database connection.
  \c DRIVER PARAMS...
    - Connect to a database using a driver and parameters.
  \connect
    - Alias for \c.
  \Z, \disconnect
    - Close (disconnect) the current database connection.
  \password [USER], \passwd
    - Change the password for a user.
  \conninfo
    - Display information about the current database connection.
```

--------------------------------

### usql Syntax Highlighting Configuration

Source: https://github.com/xo/usql/blob/master/README.md

Configure syntax highlighting in the usql interactive shell. These variables control the enabling, formatting, background overriding, and style of syntax highlighting.

```APIDOC
SYNTAX_HL:
  Description: Enables syntax highlighting.
  Default: `true`
  Values: `true` or `false`

SYNTAX_HL_FORMAT:
  Description: Sets the Chroma formatter name for syntax highlighting.
  Default: _dependent on terminal support_
  Values: Chroma formatter name

SYNTAX_HL_OVERRIDE_BG:
  Description: Enables overriding the background color of Chroma styles.
  Default: `true`
  Values: `true` or `false`

SYNTAX_HL_STYLE:
  Description: Sets the Chroma style name for syntax highlighting.
  Default: `monokai`
  Values: Chroma style name
```

```usql
\set SYNTAX_HL_STYLE dracula
\unset SYNTAX_HL_OVERRIDE_BG
```

--------------------------------

### Configure usql Password File

Source: https://github.com/xo/usql/blob/master/README.md

Manage database passwords using the .usqlpass file in the home directory. Ensure correct permissions for security.

```sh
chmod 0600 ~/.usqlpass
```

```APIDOC
.usqlpass file format:
  protocol:host:port:dbname:user:pass
  Example:
  postgres:*:*:*:booktest:booktest
```

--------------------------------

### usql \copy Command Syntax and Parameters

Source: https://github.com/xo/usql/blob/master/README.md

Defines the two primary parameter forms for the \copy command, outlining the roles of source (SRC) and destination (DST) database URLs, the query to execute, and the destination table name. It also details the optional column list format.

```APIDOC
\copy SRC DST QUERY TABLE
\copy SRC DST QUERY TABLE(COL1, COL2, ..., COLN)

Parameters:
- SRC: Source database URL where the QUERY will be executed.
- DST: Destination database URL where the destination TABLE resides.
- QUERY: The query to execute on the SRC connection. Its results will be copied to TABLE.
- TABLE: The destination table name, optionally followed by a column list (COL1, COL2, ..., COLN).
```

--------------------------------

### usql Scheme: Exasol

Source: https://github.com/xo/usql/blob/master/README.md

Defines the connection scheme and aliases for Exasol databases in usql. It uses the 'exasol' scheme and supports aliases like 'ex' and 'exa'. The underlying driver is github.com/exasol/exasol-driver-go.

```APIDOC
Database: Exasol
Scheme: exasol
Aliases: ex, exa
Driver: github.com/exasol/exasol-driver-go
```

--------------------------------

### usql Chart Meta Command

Source: https://github.com/xo/usql/blob/master/README.md

Displays a chart directly in the terminal using the \chart meta command. Requires a terminal that supports graphics protocols like Kitty, iTerm, or Sixel.

```APIDOC
\chart
  Displays a chart in the terminal.
  Requires terminal graphics support.
  See section on \chart meta command for details.
```

--------------------------------

### usql Scheme: Alibaba MaxCompute

Source: https://github.com/xo/usql/blob/master/README.md

Defines the connection scheme and aliases for Alibaba MaxCompute in usql. It uses the 'maxcompute' scheme and supports the alias 'mc'. The underlying driver is sqlflow.org/gomaxcompute.

```APIDOC
Database: Alibaba MaxCompute
Scheme: maxcompute
Aliases: mc
Driver: sqlflow.org/gomaxcompute
```

--------------------------------

### Manage Display Formatting Variables with \pset

Source: https://github.com/xo/usql/blob/master/README.md

Display formatting variables control how query results are presented. They are managed using the \pset command, and their current settings can be viewed by running \pset without arguments.

```APIDOC
\pset [variable [value]]
  - Sets a display formatting variable. If no value is provided, it displays all formatting variables.
  - Example:
    (not connected)=> \pset time Kitchen
    Time display is "Kitchen" ("3:04PM").
    (not connected)=> \a
    Output format is unaligned.
    (not connected)=> \pset
    time                     Kitchen
```

--------------------------------

### Display Query Buffer with \p and \raw

Source: https://github.com/xo/usql/blob/master/README.md

The \p command displays the current query buffer with interpolated values. The \raw command displays the query buffer without any interpolation, showing the raw template.

```APIDOC
\p
  - Prints the current query buffer with interpolated values.

\raw
  - Prints the raw query buffer without interpolation.
  - Example:
    pg:booktest@localhost-> \p
    select * from authors where "name" = 'bar'
    pg:booktest@localhost-> \raw
    select * from :TBLNAME where :"COLNAME" = :'FOO'
```