FirebirdSQL logo

Document History

The exact file history is recorded in the firebird-documentation git repository; see https://github.com/FirebirdSQL/firebird-documentation

Revision History

1.4

4 May 2024

MR

Wrong name for SET option EXEC_DISPLAY_PATH should be EXEC_PATH_DISPLAY (#209)

1.3

2 Apr 2024

MR

Protocol names are lowercase (#205)

1.2

24 Feb 2024

  • Replaced isql -⁠help (invalid switch) with isql -⁠? (valid switch)

  • Added word-joiner in commandline switches between minus (-) and first character to ensure they aren’t broken up on word wrap

  • Include isql name in the document title, making it the same as on https://firebirdsql.org/en/reference-manuals/

1.1

17 Jan 2024

MR

  • Misc. copy-editing

  • Moved SET KEEP_TRAN_params for correct alphabetical ordering

  • Replaced Firebird 4.0 Language Reference link with Firebird 5.0 Language Reference link

  • Documented SET PER_TABle_stats introduced in Firebird 5.0.Adapted from the original text by Vlad Khorsun in docs/README.isql_enhancements.txt.

  • Documented new options for SHOW SYStem

  • Documented SHOW PUBlications

  • Replaced (most) output examples with output of Firebird 5.0

  • Removed SQL> prefix and ; terminator from syntax documentation

1.0

24 Dec 2021

MR

  • Reversed order of this document history to put the most recent change first

  • Documented SET EXEC_PATH_DISPLAY introduced in Firebird 4.0.1.Adapted from the original text by Adriano dos Santos Fernandes in docs/README.isql_enhancements.txt.

0.9

12 Jun 2021

MR

0.8

24 May 2021

MR

  • Added missing Firebird 3.0 and 4.0 features (SET MAXROWS, SET EXPLAIN, SET KEEP_TRAN_PARAMS, SHOW MAPPING, SHOW PACKAGES, SHOW SCHEMAS)

  • Used consistent code formatting in section titles of commands

  • Added command aliases to section titles

  • Updated example output of most commands with output of Firebird 4.0

  • General copy-editing

0.7

08 May 2021

MR

Documented SET LOCAL_TIMEOUT

0.6

20 Jun 2020

MR

Conversion to AsciiDoc, minor copy-editing

0.5

10 Apr 2012

ND

More tidying up.Plus:

0.4

15 Feb 2012

ND

General tidy up.Changes to formatting.Corrected some Docbook "misuse".Spelling & punctuation corrections.Lists compacted.Corrected <screen> overflow in pdf rendering.Etc.

0.3

20 Oct 2009

ND

Converted from a chapter in the Command Line Utilities manual to stand alone manual in its own right.

Changed title to Firebird Interactive SQL Utility to bring it in line with the other utility manuals.

Many other updates to bring this manual into line with the others and to incorporate Firebird 2 changes etc.

0.2

5 Jul 2008

PV

Changed title to Isql - Firebird Interactive SQL Utility to bring it in line with the other manuals.Added titleabbrev and edition info.Moved Audience and Version sections into Introduction.Removed Related Documentation section.Fixed typos, interpunction (still more to do here).Replaced most emphasises and all citetitles with more appropriate tags.Gave IDs to manual and all (sub)sections.Added manual History and License Notice.

0.1

Overview

The isql utility is a text-mode client tool located in the bin directory of the Firebird installation.It provides a commandline interface for interactive access to a Firebird database.It accepts DSQL statements along with a group of ISQL-specific commands to query and interact with the Firebird database.Some SET commands can be incorporated in DDL scripts to perform batch executions within isql.It also accepts DDL, DML and console commands.

The isql utility can be used in three modes:

  • as an interactive session;

  • directly from the commandline;

  • and as a non-interactive session, using a shell script or batch file.

Different tasks may be performed in each of the modes, as illustrated below:

  • An interactive session can be invoked from the commandline of the operating system shell, and lasts until the session is terminated, using a QUIT or EXIT command.Isql can be used interactively to:

    • Create, update, query, and drop data or metadata

    • Input a script file containing a batch of SQL statements in sequence without prompting

    • Add and modify data

    • Grant user permissions

    • Perform database administrative functions

  • Directly from the commandline, with individual options and without starting an interactive session.Commands execute, and upon completion, return control automatically to the operating system.

  • In a non-interactive session, the user employs a shell script or batch file to perform database functions.

Note

Because other applications in the Linux environment, for example, MySQL, also use isql as a utility name, you are advised to run the Firebird utility from its own directory, or provide the absolute file path if you have another relational database, besides Firebird, installed on your machine.

Note

Some affected distributions have renamed Firebird’s isql to isql-fb.There may be similar changes in other distributions.

In addition, not all distributions install Firebird to the same location.OpenSuse, for example, installs just about everything to /opt/firebird/n.n but Ubuntu and derivatives install it to a number of different locations, but the utilities are in /usr/bin.

For the remainder of this document, we assume that the utility is called isql.

License Notice

The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the “License”); you may only use this Documentation if you comply with the terms of this License.Copies of the License are available at https://www.firebirdsql.org/pdfmanual/pdl.pdf (PDF) and https://www.firebirdsql.org/manual/pdl.html (HTML).

The Original Documentation is titled Firebird Interactive SQL Utility.

The Initial Writer of the Original Documentation is: Kamala Vadlamani.

Copyright © 2006.All Rights Reserved.Initial Writer contact: kamala dot vadlamani at gmail dot com.

Contributors: Paul Vinkenoog, Norman Dunbar, Mark Rotteveel.

Portions created by Paul Vinkenoog are Copyright © 2008.All Rights Reserved.Contributor contact: paul at vinkenoog dot nl.

Portions created by Norman Dunbar are Copyright © 2009, 2011-2013.All Rights Reserved.Contributor contact: NormanDunbar at users dot sourceforge dot net.

Portions created by Mark Rotteveel are Copyright © 2021-2024.All Rights Reserved.Contributor contact: mrotteveel at users dot sourceforge dot net.

Invoking Isql

If you do not have the Firebird bin directory on your path, then either go to the bin subdirectory of your Firebird installation and type isql (Windows) or ./isql (Linux) at the command prompt, or, type the full path to the isql application to execute it.If the bin is on your path, you may start it by typing isql regardless of your operating system.

Example:

$ isql

Use CONNECT or CREATE DATABASE to specify a database
SQL> CONNECT "C:\DATABASES\FIREBIRD\MY_EMPLOYEE.FDB"
CON> user 'SYSDBA' password 'secret';
Tip

Here and elsewhere in this document, we use the ‘$’ to signify the command prompt, it is not part of the command to enter.

For example, on Windows the command prompt might look like “C:\>”, or on Linux “user@HOST:~$"”.The exact prompt depends on the OS defaults and user configuration.

The above is the simplest method of starting isql, and once activated in this way, you must begin by either creating a new database, or connecting to one.The prompt given by isql is a hint as to what you must do next.If you wish to connect to an already existing database, you may pass the database name on the commandline.You should be aware that unless you also pass the username and password as well, you may see an error message telling you that your username or password have not been defined.In this case, you need to supply the username and password, or create two environment variables as discussed below.

The following example shows how to pass the database name plus user credentials on the commandline.

$ isql -user sysdba -password secret employee
Database:  employee, User: SYSDBA
SQL>

In this example, we used a database alias for the employee database.This example comes predefined in the file databases.conf  — or aliases.conf in Firebird 2.5 and older — which normally lives in the directory that Firebird was installed in, but some Linux distributions put it in /etc/firebird/n.n where n.n is the version of the Firebird database server.There is more information on connecting to databases, using full paths or aliases in [isql-connect-database].