isql(1)

💖 isql(1) — unixODBC manual pages 💖

okay bestie, sit DOWN, because we're about to talk about isql and iusql, the unixODBC interactive SQL command-line tools, and honestly? they're iconic. this page is from the unixODBC manual pages, section 1, and i'm about to give you the whole lore, no skips, no skimming. 🫶

---

✨ NAME ✨

isql, iusql — unixODBC interactive SQL command-line tools. that's it, that's the name, we move.

---

🌸 SYNOPSIS 🌸

isql DSN [USER [PASSWORD]] [options]

iusql DSN [USER [PASSWORD]] [options]

iusql "ConnectionString" [options]

three whole ways to slide into your database. pick your fighter. 💅

---

🦋 DESCRIPTION 🦋

isql and iusql are command-line tools allowing users to execute SQL interactively or in batches. so like, type SQL at it, or feed it a whole file, your call, main character energy either way. ✨

The tools provide several useful features, including an option to generate output wrapped in an HTML table. yes, HTML table. we contain multitudes.

iusql is the same as isql but includes built-in Unicode support. Some data sources only work with iusql. An important difference between the two tools is that isql connects using SQLConnect and iusql connects using SQLDriverConnect. that second part is the tea that actually matters, lowkey. 🍓

---

🎀 ARGUMENTS 🎀

• DSN — The Data Source Name (DSN) used to connect to the SQL database. unixODBC looks for the specified DSN in /etc/odbc.ini and $HOME/.odbc.ini, with the latter taking precedence. (your home file wins, periodt.)

When searching the configuration files, unixODBC looks for a bare name. If the DSN begins with a semicolon, it is treated as a connection string. The connection string can contain a DSN and/or other semicolon-separated parameters. semicolon at the front = vibe shift, it's a connection string now.

• USER — Specifies the database user or role under which the connection should be made.

This parameter overrides any UID specified in the data source configuration files. your config said one thing, you said another, you win. 👑

• PASSWORD — Password required to access the database for the specified USER.

This parameter overrides any PASSWORD specified in the data source configuration files.

When using iusql, passwords containing semicolons should be escaped with braces (curly brackets) and terminated with a semicolon. Refer to the Examples section below for syntax. yes, braces, curly brackets, and a semicolon at the end. it's giving chaos but it works. 🙈

• "ConnectionString" — A connection string starting with DSN=, DRIVER= or FILEDSN= will be passed unchanged to SQLDriverConnect. This option allows for the use of more complex syntax in a connection string than would otherwise be possible by just using DSN, UID and PWD.

It also (and this was the main reason for its inclusion) allows passwords to contain semicolons without having to add complex escape syntax to the existing code. they literally added a whole feature just so semicolons in passwords could chill. relatable tbh. 💀

---

💅 OPTIONS 💅

• -b — Run 'isql' in non-interactive batch mode. In this mode, 'isql' processes from standard input, expecting one SQL command per line.
• -dDELIMITER — Delimit columns with the specified delimiter.
• -xHEX — Delimit columns with the character represented in hexadecimal by HEX. The hexadecimal code must be in the format 0xNN (e.g. 0x09 for the TAB character).
• -w — Format the result as an HTML table.
• -c — Output the names of the columns on the first row. This option can only be used with the -d or -x options.
• -mNUM — Limit the column display width to NUM characters.
• -lLOCALE — Set the character locale to LOCALE.
• -q — Wrap the character fields in double quotes.
• -3 — Use calls from ODBC version 3.
• -n — Process multiple lines of SQL, terminated with the GO command.
• -e — Use SQLExecDirect instead of Prepare.
• -k — Use SQLDriverConnect.
• -v — Enable verbose mode, fully describing all errors. This option is useful for debugging. when something's broken, -v is your bestie fr fr.
• -i — Enable noverbose mode, the help text gone but does not disable prompts like the -b option.
• --version — Display the program version.
• -LNUM — Set the maximum number of characters displayed from a character field to NUM. The default value is 300 characters.

---

🌈 COMMANDS 🌈

This section briefly describes some isql and iusql run-time commands.

• help — List all tables in the database.
• help table — List all columns in the table.
• help help — List all help options.

yes bestie, help help. she contains knowledge about herself. self-aware queen. 👑

---

🔥 EXAMPLES 🔥

A bare DSN

$ iusql WebDB MyID MyPWD -w -b < My.sql

Connects to the WebDB DSN as user MyID with password MyPWD, then executes the commands in the My.sql file and returns the results wrapped in an HTML table.

Each line in My.sql must only contain one SQL command, except for the last line, which must be blank (unless the -n option is specified). so the last line has to be a vibe void, an empty little moment. don't forget it. 😭

A DSN in a connection string

Note the leading semicolon on the connection string.

$ iusql ";DSN=WebDB" MyID MyPWD -w -b < My.sql

Options in the DSN may be overridden in the connection string:

$ iusql ";DSN=WebDB;Driver=PostgreSQL ODBC;UID=MyID;PASSWORD=secret;Debug=1;CommLog=1" -v

A string DSN

A string DSN may be provided in its entirety, with no file DSN reference at all:

$ iusql ";Driver=PostgreSQL Unicode;UID=MyID;PASSWORD=secret" -v

no file, no reference, just the whole thing, raw, unfiltered. slay. ✨

A password containing a semicolon (iusql)

$ iusql WebDB MyID '{My;PWD};'

$ iusql 'DSN=WebDB;UID=MyID;PWD={My;PWD};'

brace it, semicolon it, done. 🎀

---

🧚 TROUBLESHOOTING 🧚

Cryptic error messages

Re-run isql or iusql with the -v flag to get more information from errors, and/or enable Trace mode in odbcinst.ini.

Missing driver definition

Check that the driver name specified by the Driver entry in the odbc.ini data-source definition is present in odbcinst.ini and exactly matches the odbcinst.ini [section name]. exactly. character for character. no vibes-based matching.

Unloadable or incompatible driver

If the ODBC driver is properly specified for the data source, it is possible that the driver is not loadable. Check for mix-ups between Unicode and ANSI drivers, and verify the driver paths in the odbcinst.ini [section name].

Unicode data sources with ANSI clients

Some data sources are Unicode-only and require the use of iusql. If isql reports

[IM002][unixODBC][Driver Manager]Data source name not found and no default driver specified
[ISQL]ERROR: Could not SQLConnect

but the data source and driver required are listed by

odbcinst -q -d

and

odbcinst -q -s

then try iusql. like, that's the move. switch tools, bestie. 💖

---

🌸 FILES 🌸

• /etc/odbc.ini — Configuration file containing system-wide Data Source Name (DSN) definitions. See odbc.ini(5) for more information.
• $HOME/.odbc.ini — Configuration file containing user-specific Data Source Name (DSN) definitions. See odbc.ini(5) for more information.

---

👑 SEE ALSO 👑

unixODBC(7), odbcinst(1), odbc.ini(5)

"The unixODBC Administrator Manual (HTML)"

---

🫶 AUTHORS 🫶

The authors of unixODBC are Peter Harvey <pharvey@codebydesign.com> and Nick Gorham <nick@lurcher.org>.

For a full list of contributors, refer to the AUTHORS file.

---

⭐ COPYRIGHT ⭐

unixODBC is licensed under the GNU Lesser General Public License. For details about the license, see the COPYING file.

---

and that's the whole page, bestie!! this was version 2.3.12, dated Thu 14 Jan 2021, and it's the isql(1) manual page from unixODBC — mwah, no notes, go run some SQL 💖✨