diff --git a/technology/applications/Applications.md b/technology/applications/Applications.md index 0cec095..36d6fe3 100644 --- a/technology/applications/Applications.md +++ b/technology/applications/Applications.md @@ -1,6 +1,6 @@ --- obj: meta/collection -rev: 2024-07-14 +rev: 2024-12-10 --- # Applications @@ -262,6 +262,7 @@ rev: 2024-07-14 - [Docker](../tools/Docker.md) - [Podman](../tools/Podman.md) - [serie](./cli/serie.md) +- [usql](./cli/usql.md) ## Media - [yt-dlp](./media/yt-dlp.md) diff --git a/technology/applications/cli/usql.md b/technology/applications/cli/usql.md new file mode 100644 index 0000000..c648374 --- /dev/null +++ b/technology/applications/cli/usql.md @@ -0,0 +1,229 @@ +--- +obj: application +repo: https://github.com/xo/usql +rev: 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 + +```sh +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`. + +```yml +# 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` |