knowledge/technology/applications/cli/usql.md

obj	repo	rev
application	https://github.com/xo/usql	2024-12-10

usql

usql is a universal command-line interface for PostgreSQL, MySQL, Oracle Database, SQLite3, Microsoft SQL Server, and many other databases including NoSQL and non-relational databases!

usql provides a simple way to work with SQL and NoSQL databases via a command-line inspired by PostgreSQL's psql. usql supports most of the core psql features, such as variables, backticks, backslash commands and has additional features that psql does not, such as multiple database support, copying between databases, syntax highlighting, context-based completion, and terminal graphics.

Usage

usql [options]... [DSN]

DSN can be any database connection string like sqlite:///path/to/my/file or postgres://user:pass@host:port/db.

Options

Option	Description
-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
-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

Commands

Command	Description
General:
\q	quit usql
\quit	alias for \q
\drivers	show database drivers available to usql
Connection:
\c DSN	connect to database url
\c DRIVER PARAMS...	connect to database with driver and parameters
\cset [NAME [DSN]]	set named connection, or list all if no parameters
\cset NAME DRIVER PARAMS...	define named connection for database driver
\Z	close database connection
\password [USERNAME]	change the password for a user
\conninfo	display information about the current database connection
Operating System:
\cd [DIR]	change the current working directory
\getenv VARNAME ENVVAR	fetch environment variable
\setenv NAME [VALUE]	set or unset environment variable
\! [COMMAND]	execute command in shell or start interactive shell
\timing [on/off]	toggle timing of commands
Variables:
\prompt [-TYPE] VAR [PROMPT]	prompt user to set variable
\set [NAME [VALUE]]	set internal variable, or list all if no parameters
\unset NAME	unset (delete) internal variable
Query Execute:
\g [(OPTIONS)] [FILE] or ;	execute query (and send results to file or pipe)
\G [(OPTIONS)] [FILE]	as \g, but forces vertical output mode
\gx [(OPTIONS)] [FILE]	as \g, but forces expanded output mode
\gexec	execute query and execute each value of the result
\gset [PREFIX]	execute query and store results in usql variables
Query Buffer:
\e [FILE] [LINE]	edit the query buffer (or file) with external editor
\p	show the contents of the query buffer
\raw	show the raw (non-interpolated) contents of the query buffer
\r	reset (clear) the query buffer
Input/Output:
\copy SRC DST QUERY TABLE	copy query from source url to table on destination url
\copy SRC DST QUERY TABLE(A,...)	copy query from source url to columns of table on destination url
\echo [-n] [STRING]	write string to standard output (-n for no newline)
\qecho [-n] [STRING]	write string to \o output stream (-n for no newline)
\warn [-n] [STRING]	write string to standard error (-n for no newline)
\o [FILE]	send all query results to file or pipe
Informational:
\d[S+] [NAME]	list tables, views, and sequences or describe 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
Formatting:
\pset [NAME [VALUE]]	Set table output option
\a	Toggle between unaligned and aligned output mode
\C [STRING]	Set table title, or unset if none
\f [STRING]	Show or set field separator for unaligned query output
\H	Toggle HTML output mode
\T [STRING]	Set HTML tag attributes, or unset if none \t [on/off] Show only rows \x [on/off/auto] Toggle expanded output Transaction: \\begin Begin a transaction \\begin [-read-only] [ISOLATION] Begin a transaction with isolation level \\commit Commit current transaction \\rollback Rollback (abort) current transaction Configuration During its initialization phase, usql reads a standard YAML configuration file config.yaml. On Windows this is %AppData%/usql/config.yaml, on macOS this is $HOME/Library/Application Support/usql/config.yaml, and on Linux and other Unix systems this is normally $HOME/.config/usql/config.yaml. # named connections # name can be used instead of database url connections: my_couchbase_conn: couchbase://Administrator:P4ssw0rd@localhost my_clickhouse_conn: clickhouse://clickhouse:P4ssw0rd@localhost css: cassandra://cassandra:cassandra@localhost fsl: flightsql://flight_username:P4ssw0rd@localhost gdr: protocol: godror username: system password: P4ssw0rd hostname: localhost port: 1521 database: free ign: ignite://ignite:ignite@localhost mss: sqlserver://sa:Adm1nP@ssw0rd@localhost mym: mysql://root:P4ssw0rd@localhost myz: mymysql://root:P4ssw0rd@localhost ora: oracle://system:P4ssw0rd@localhost/free ore: oracle://system:P4ssw0rd@localhost:1522/db1 pgs: postgres://postgres:P4ssw0rd@localhost pgx: pgx://postgres:P4ssw0rd@localhost vrt: proto: vertica user: vertica pass: vertica host: localhost sll: file: /path/to/mydb.sqlite3 mdc: modernsqlite:test.db dkd: test.duckdb zzz: ["databricks", "token:dapi*****@adb-*************.azuredatabricks.net:443/sql/protocolv1/o/*********/*******"] zz2: proto: mysql user: "my username" pass: "my password!" host: localhost opts: opt1: "😀" # init script init: | \echo welcome to the jungle `date` \set SYNTAX_HL_STYLE paraiso-dark \set PROMPT1 '\033[32m%S%M%/%R%#\033[0m ' \set bar test \set foo test -- \set SHOW_HOST_INFORMATION false -- \set SYNTAX_HL false \set 型示師 '本門台初埼本門台初埼' # charts path charts_path: charts # defined queries queries: q1: Time Formatting Some databases support time/date columns that support formatting. By default, usql formats time/date columns as RFC3339Nano, and can be set using \pset time FORMAT: $ usql pg:// Connected with driver postgres (PostgreSQL 13.2 (Debian 13.2-1.pgdg100+1)) Type "help" for help. pg:postgres@=> \pset time RFC3339Nano pg:postgres@=> select now(); now ----------------------------- 2021-05-01T22:21:44.710385Z (1 row) pg:postgres@=> \pset time Kitchen Time display is "Kitchen" ("3:04PM"). pg:postgres@=> select now(); now --------- 10:22PM (1 row) usql's time format supports any Go supported time format, or can be any standard Go const name, such as Kitchen above. See below for an overview of the available time constants. Time Constants The following are the time constant names available in usql, corresponding time format value, and example display output: Constant Format Display 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