SQL(1)

✨ SQL(1) — parallel ✨

okay so bestie, buckle up: this is the manual for sql from the parallel family of tools, and it's genuinely iconic. it's a whole unified way to talk to every database from one command. let's get into it 💅

---

🌸 NAME 🌸

sql — execute a command on a database determined by a dburl 🫶

---

🎀 SYNOPSIS 🎀

sql [options] dburl [commands]

sql [options] dburl < commandfile

#!/usr/bin/sql --shebang [options] dburl

---

🦋 DESCRIPTION 🦋

so like, the whole ~vision~ of GNU sql is: one simple, unified interface for getting into databases through all the different databases' own command line clients. no cap. the focus so far has been on three things:

• giving you 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. and if you leave the commands out? you get dropped straight into that database's interactive shell. main character energy ✨

GNU sql is often used in combination with GNU parallel. (they're besties, obviously 💖)

• 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:///

---

and now, the flags. all of them. every single one. i would never gatekeep 😭

• --csv — CSV output.
• --db-size, --dbsize — size of database. shows 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 sql and exit.
• --html — HTML output. turns 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. 💀 (not us, not our fault)
• -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. specify 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 sql itself when called with --shebang).
• --table-size, --tablesize — size of tables. shows the size of the tables in the database.
• --verbose, -v — print which command is sent.
• --version, -V — print the version GNU sql and exit.
• --shebang, -Y — GNU sql can 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 --shebang or -Y must be set as the first option. fr fr, first. don't test it. 🫶

---

🌈 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:tiger@my.example.com/mydb
influxdb://scott:tiger@influxdb.example.com/foo
sql:oracle://scott:tiger@ora.example.com/xe
postgresql://scott:tiger@pg.example.com/pgdb
pg:///
postgresqlssl://scott@pg.example.com:3333/pgdb
sql:sqlite2:////tmp/db.sqlite?SELECT * FROM foo;
sqlite3:///../db.sqlite3?SELECT%20*%20FROM%20foo;

currently supported vendors (the roster 👑):

• 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. 🔒 (yes that means chmod. do it.)

example of aliases:

:myalias1 pg://scott:tiger@pg.example.com/pgdb
:myalias2 ora://scott:tiger@ora.example.com/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;

(it says "sortest" and we love them for it 🎀)

---

💖 EXAMPLES 💖

Get an interactive prompt

the most basic use of GNU sql is to get an interactive prompt:

sql sql:oracle://scott:tiger@ora.example.com/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:tiger@pg.example.com/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

---

🍓 REPORTING BUGS 🍓

GNU sql is part of GNU parallel. report bugs to <bug-parallel@gnu.org>. be nice, they're doing their best 🫶

---

🌟 AUTHOR 🌟

when using GNU sql for a publication please cite:

O. Tange (2011): GNU SQL - A Command Line Tool for Accessing Different
Databases Using DBURLs, ;login: The USENIX Magazine, April 2011:29-32.

Copyright (C) 2008-2010 Ole Tange http://ole.tange.dk

Copyright (C) 2010-2026 Ole Tange, http://ole.tange.dk and Free Software Foundation, Inc.

---

👑 LICENSE 👑

this program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or at your option any later version.

this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see the GNU General Public License for more details. (yes that's shouty in the original, we're keeping the shout 😤)

you should have received a copy of the GNU General Public License along with this program. if not, see <http://www.gnu.org/licenses/>.

Documentation license I

permission is granted to copy, distribute and/or modify this documentation under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. a copy of the license is included in the file LICENSES/GFDL-1.3-or-later.txt.

Documentation license II

you are free:

• to Share — to copy, distribute and transmit the work
• to Remix — to adapt the work

under the following conditions:

Attribution

you must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).

Share Alike

if you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license.

With the understanding that:

• Waiver — any of the above conditions can be waived if you get permission from the copyright holder.
• Public Domain — where the work or any of its elements is in the public domain under applicable law, that status is in no way affected by the license.
• Other Rights — in no way are any of the following rights affected by the license:
  • your fair dealing or fair use rights, or other applicable copyright exceptions and limitations;
  • the author's moral rights;
  • rights other persons may have either in the work itself or in how the work is used, such as publicity or privacy rights.
• Notice — for any reuse or distribution, you must make clear to others the license terms of this work.

a copy of the full license is included in the file as cc-by-sa.txt.

✨ DEPENDENCIES ✨

okay so real talk — GNU sql is a Perl girlie at heart, like it literally runs on Perl, that's the whole foundation bestie 💅 so make sure Perl is there or nothing's happening periodt.

The rest is all "if you have it, it works" energy — no pressure, but here's the vibe check on which client gets you which dburl flavor:

• 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. 🎀

lowkey the rlwrap one is such a glow-up for Oracle users — command history is NOT optional in this household, we do not retype queries like it's 1998 😭

---

🎀 FILES 🎀

Two little alias spots, iykyk — one's yours, one's the system's:

• ~/.sql/aliases — user's own aliases with DBURLs 💖
• /etc/sql/aliases — common aliases with DBURLs 🌈

your home one is your personal diary of shortcuts, the /etc one is the shared group chat. both hold DBURLs, both are iconic.

---

🌟 SEE ALSO 🌟

the whole friend group fr fr — go say hi:

• mysql(1)
• psql(1)
• rlwrap(1)
• sqlite(1)
• sqlite3(1)
• sqlplus(1)
• influx(1)

---

and that's the page bestie!! 🫶 this edition is version 20260922, dated 2026-09-22, and it's the SQL(1) manual — screenshot it, bookmark it, tattoo it on your forearm, whatever you gotta do 💜✨ you're gonna slay those dburls, no cap 🔥👑