sql1
Execute a command on a database determined by a dburl
Usage
sql [options]
dburl
[commands]
sql [options]
dburl
<
commandfile
Overview
GNU sql aims to give a simple, unified interface for accessing databases through all the different databases' command line clients. So far the focus has been on giving a common way to specify login information (protocol, username, password, hostname, and port number), size (database and table size), and running queries.
The database is addressed using a DBURL. If commands are left out you will get that database's interactive shell.
GNU sql is often used in combination with GNU parallel.
- dburl
-
A DBURL has the following syntax: [sql:]vendor:// [[user][:password]@][host][:port]/[database][?sqlquery]
See the section DBURL below.
- commands
-
The SQL commands to run. Each argument will have a newline appended.
Example: "SELECT * FROM foo;" "SELECT * FROM bar;"
If the arguments contain '\n' or '\x0a' this will be replaced with a newline:
Example: "SELECT * FROM foo;\n SELECT * FROM bar;"
If no commands are given SQL is read from the keyboard or STDIN.
Example: echo 'SELECT * FROM foo;' | sql mysql:///
-
--csv -
CSV output.
-
--db-size
-
--dbsize -
Size of database. Show the size of the database on disk. For Oracle this requires access to read the table dba_data_files - the user system has that.
-
--help
-
-h -
Print a summary of the options to GNU
sqland exit.
-
--html -
HTML output. Turn on HTML tabular output.
-
--json
-
--pretty -
Pretty JSON output.
-
--list-databases
-
--listdbs
-
--show-databases
-
--showdbs -
List the databases (table spaces) in the database.
-
--listproc
-
--proclist
-
--show-processlist -
Show the list of running queries.
-
--list-tables
-
--show-tables
-
--table-list -
List the tables in the database.
-
--noheaders
-
--no-headers
-
-n -
Remove headers and footers and print only tuples. Bug in Oracle: it still prints number of rows found.
-
-p pass-through -
The string following -p will be given to the database connection program as arguments. Multiple -p's will be joined with space. Example: pass '-U' and the user name to the program:
-p "-U scott" can also be written -p -U -p scott.
-
--precision <rfc3339|h|m|s|ms|u|ns> -
Precision of timestamps.
Specifiy the format of the output timestamps: rfc3339, h, m, s, ms, u or ns.
-
-r -
Try 3 times. Short version of --retries 3.
-
--retries ntimes -
Try ntimes times. If the client program returns with an error, retry the command. Default is --retries 1.
-
--sep string
-
-s string -
Field separator. Use string as separator between columns.
-
--skip-first-line -
Do not use the first line of input (used by GNU
sqlitself when called with--shebang).
-
--table-size
-
--tablesize -
Size of tables. Show the size of the tables in the database.
-
--verbose
-
-v -
Print which command is sent.
-
--version
-
-V -
Print the version GNU
sqland exit.
-
--shebang
-
-Y -
GNU
sqlcan be called as a shebang (#!) command as the first line of a script. Like this:#!/usr/bin/sql -Y mysql:///SELECT * FROM foo;For this to work
--shebangor-Ymust be set as the first option.
Dburl
A DBURL has the following syntax: [sql:]vendor:// [[user][:password]@][host][:port]/[database][?sqlquery]
To quote special characters use %-encoding specified in http://tools.ietf.org/html/rfc3986#section-2.1 (E.g. a password containing '/' would contain '%2F').
csv:///%2Ftmp%2Fparallel-bug-56096/mytable csv:////tmp/parallel-bug-56096/mytable mysql://me@/me/ mysql:////
sqlite3:///%2Frun%2Fshm%2Fparallel.db sqlite3:///%2Frun%2Fshm%2Fparallel.db/table sqlite:///%2Ftmp%2Ffile.sqlite?SELECT csv:///%2Ftmp%2Fparallel-CSV/OK csv:///%2Fmust%2Ffail/fail sqlite3:///%2Frun%2Fshm%2Fparallel.db
Examples:
mysql://scott:[email protected]/mydbinfluxdb://scott:[email protected]/foosql:oracle://scott:[email protected]/xepostgresql://scott:[email protected]/pgdbpg:///postgresqlssl://[email protected]:3333/pgdbsql:sqlite2:////tmp/db.sqlite?SELECT * FROM foo;sqlite3:///../db.sqlite3?SELECT%20*%20FROM%20foo;
Currently supported vendors:
- •
-
MySQL (mysql) with SSL (mysqls, mysqlssl)
- •
-
Oracle (oracle, ora)
- •
-
PostgreSQL (postgresql, pg, pgsql, postgres) with SSL (postgresqlssl, pgs, pgsqlssl, postgresssl, pgssl, postgresqls, pgsqls, postgress)
- •
-
SQLite2 (sqlite, sqlite2)
- •
-
SQLite3 (sqlite3)
- •
-
InfluxDB 1.x (influx, influxdb) with SSL (influxdbssl, influxdbs, influxs, influxssl)
Aliases must start with ':' and are read from /etc/sql/aliases and ~/.sql/aliases. The user's own ~/.sql/aliases should only be readable by the user.
Example of aliases:
:myalias1 pg://scott:[email protected]/pgdb:myalias2 ora://scott:[email protected]/xe# Short form of mysql://`whoami`:nopassword@localhost:3306/`whoami`:myalias3 mysql:///# Short form of mysql://`whoami`:nopassword@localhost:33333/mydb:myalias4 mysql://:33333/mydb# Alias for an alias:m :myalias4# the sortest alias possible: sqlite2:////tmp/db.sqlite# Including an SQL query:query sqlite:////tmp/db.sqlite?SELECT * FROM foo;
Examples
Get an interactive prompt
The most basic use of GNU sql is to get an interactive prompt:
sql sql:oracle://scott:[email protected]/xe
If you have setup an alias you can do:
sql :myora
Run a query
To run a query directly from the command line:
sql :myalias "SELECT * FROM foo;"
Oracle requires newlines after each statement. This can be done like this:
sql :myora "SELECT * FROM foo;" "SELECT * FROM bar;"
Or this:
sql :myora "SELECT * FROM foo;\nSELECT * FROM bar;"
Copy a PostgreSQL database
To copy a PostgreSQL database use pg_dump to generate the dump and GNU sql to import it:
pg_dump pg_database | sql pg://scott:[email protected]/pgdb
Empty all tables in a MySQL database
Using GNU parallel it is easy to empty all tables without dropping them:
sql -n mysql:/// 'show tables' | parallel sql mysql:/// DELETE FROM {};
Drop all tables in a PostgreSQL database
To drop all tables in a PostgreSQL database do:
sql -n pg:/// '\dt' | parallel --colsep '\|' -r sql pg:/// DROP TABLE {2};
Run as a script
Instead of doing:
sql mysql:/// < sqlfile
you can combine the sqlfile with the DBURL to make a UNIX-script. Create a script called demosql:
#!/usr/bin/sql -Y mysql:///
SELECT * FROM foo;
Then do:
chmod +x demosql; ./demosql
Use --colsep to process multiple columns
Use GNU parallel's --colsep to separate columns:
sql -s '\t' :myalias 'SELECT * FROM foo;' | parallel --colsep '\t' do_stuff {4} {1}
Retry if the connection fails
If the access to the database fails occasionally --retries can help make sure the query succeeds:
sql --retries 5 :myalias 'SELECT * FROM really_big_foo;'
Get info about the running database system
Show how big the database is:
sql --db-size :myalias
List the tables:
sql --list-tables :myalias
List the size of the tables:
sql --table-size :myalias
List the running processes:
sql --show-processlist :myalias
Dependencies
GNU sql uses Perl. If mysql is installed, MySQL dburls will work. If psql is installed, PostgreSQL dburls will work. If sqlite is installed, SQLite2 dburls will work. If sqlite3 is installed, SQLite3 dburls will work. If sqlplus is installed, Oracle dburls will work. If rlwrap is installed, GNU sql will have a command history for Oracle.
Files
~/.sql/aliases - user's own aliases with DBURLs
/etc/sql/aliases - common aliases with DBURLs
Releases
8 releases since Debian 7 (Wheezy); the text changed 6 times.
--csv since Debian 13 (Trixie);
--json since Debian 13 (Trixie);
--precision since Debian 12 (Bookworm);
--pretty since Debian 13 (Trixie);
--verbose since Debian 9 (Stretch);
-v since Debian 9 (Stretch).