.TH isql 1 "Thu 14 Jan 2021" "version 2.3.12" "unixODBC manual pages"

.SH NAME
isql, iusql - unixODBC interactive SQL command-line tools

.SH SYNOPSIS
\fBisql\fR \fIDSN\fR [\fIUSER\fR [\fIPASSWORD\fR]] [\fIoptions\fR] 

\fBiusql\fR \fIDSN\fR [\fIUSER\fR [\fIPASSWORD\fR]] [\fIoptions\fR] 

\fBiusql\fR \fI"ConnectionString"\fR [\fIoptions\fR] 

.SH DESCRIPTION
\fBisql\fR and \fBiusql\fR are command-line tools allowing users to execute SQL
interactively or in batches.

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

\fBiusql\fR is the same as \fBisql\fR but includes built-in Unicode support.
Some data sources only work with \fBiusql\fR. An important difference between the
two tools is that \fBisql\fR connects using SQLConnect and \fBiusql\fR connects
using SQLDriverConnect.

.SH ARGUMENTS

.IP \fBDSN\fR
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.

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.

.IP \fBUSER\fR
Specifies the database user or role under which the connection should be made.

This parameter overrides any \fBUID\fR specified in the data source
configuration files.

.IP \fBPASSWORD\fR
Password required to access the database for the specified \fBUSER\fR.

This parameter overrides any \fBPASSWORD\fR specified in the data source
configuration files.

When using \fBiusql\fR, passwords containing semicolons should be escaped with
braces (curly brackets) and terminated with a semicolon. Refer to the Examples
section below for syntax.

.IP \fB"ConnectionString"\fR
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.

.SH OPTIONS

.IP \fB\-b\fR
Run 'isql' in non-interactive batch mode. In this mode, 'isql' processes from
standard input, expecting one SQL command per line.

.IP \fB\-d\fIDELIMITER\fR
Delimit columns with the specified \fIdelimiter\fR.

.IP \fB\-x\fIHEX\fR
Delimit columns with the character represented in hexadecimal by \fIHEX\fR. The
hexadecimal code must be in the format 0xNN (e.g. 0x09 for the TAB character).

.IP \fB\-w\fR
Format the result as an HTML table.

.IP \fB\-c\fR
Output the names of the columns on the first row. This option can only be used
with the \fB\-d\fR or \fB\-x\fR options.

.IP \fB\-m\fINUM\fR
Limit the column display width to \fINUM\fR characters.

.IP \fB\-l\fILOCALE\fR
Set the character locale to \fILOCALE\fR.

.IP \fB\-q\fR
Wrap the character fields in double quotes.

.IP \fB\-3\fR
Use calls from ODBC version 3.

.IP \fB\-n\fR
Process multiple lines of SQL, terminated with the GO command.

.IP \fB\-e\fR
Use SQLExecDirect instead of Prepare.

.IP \fB\-k\fR
Use SQLDriverConnect.

.IP \fB\-v\fR
Enable verbose mode, fully describing all errors. This option is useful for debugging.

.IP \fB\-\-version\fR
Display the program version.

.IP \fB\-L\fINUM\fR
Set the maximum number of characters displayed from a character field to \fINUM\fR.
The default value is 300 characters.

.SH COMMANDS
This section briefly describes some \fBisql\fR and \fBiusql\fR run-time commands.

.B help
.RS
List all tables in the database.
.RE

.B help \fItable\fR
.RS
List all columns in the \fItable\fR.
.RE

.B help help
.RS
List all help options.
.RE

.SH EXAMPLES

.IP "A bare DSN:"

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

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 \fB\-n\fR option is specified).

.IP "A DSN in a connection string:"

Note the leading semicolon on the connection string.

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

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

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

.IP "A string DSN:"

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

.nf
$ iusql ";Driver=PostgreSQL Unicode;UID=MyID;PASSWORD=secret" \-v
.fi

.IP "A password containing a semicolon (\fBiusql\fR):"

.nf
$ iusql WebDB MyID '{My;PWD};'
.fi

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

.SH TROUBLESHOOTING

.IP "Cryptic error messages"

Re-run \fBisql\fR or \fBiusql\fR with the \fB\-v\fR flag to get more information
from errors, and/or enable \fBTrace\fR mode in \fBodbcinst.ini\fR.

.IP "Missing driver definition"

Check that the driver name specified by the \fBDriver\fR entry in the
\fBodbc.ini\fR data-source definition is present in \fBodbcinst.ini\fR and
exactly matches the odbcinst.ini \fI[section name]\fR.

.IP "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 \fI[section name]\fR.

.IP "Unicode data sources with ANSI clients"

Some data sources are Unicode-only and require the use of \fBiusql\fR.
If \fBisql\fR reports
.nf
  [IM002][unixODBC][Driver Manager]Data source name not found and no default driver specified
  [ISQL]ERROR: Could not SQLConnect
.fi
but the data source and driver required are listed by
.nf
  odbcinst \-q \-d
.fi
and 
.nf
  odbcinst \-q \-s
.fi
then try \fBiusql\fR.

.SH FILES

.I /etc/odbc.ini
.RS
Configuration file containing system-wide Data Source Name (DSN)
definitions. See
.BR odbc.ini (5)
for more information.
.RE

.I $HOME/.odbc.ini
.RS
Configuration file containing user-specific Data Source Name (DSN)
definitions. See
.BR odbc.ini (5)
for more information.
.RE

.SH SEE ALSO
.BR unixODBC (7),
.BR odbcinst (1),
.BR odbc.ini (5)

"The \fIunixODBC\fB Administrator Manual (HTML)\fR"

.SH AUTHORS
The authors of unixODBC are Peter Harvey <\fIpharvey@codebydesign.com\fR> and
Nick Gorham <\fInick@lurcher.org\fR>.

For a full list of contributors, refer to the \fIAUTHORS\fR file.

.SH COPYRIGHT
unixODBC is licensed under the GNU Lesser General Public License. For details
about the license, see the \fICOPYING\fR file.