Firebird Documentation IndexFirebird ODBC/JDBC Driver ManualConnecting to Firebird from Applications → Connection Parameters
Firebird Home Firebird Home Prev: Connecting to Firebird from ApplicationsFirebird Documentation IndexUp: Connecting to Firebird from ApplicationsNext: Developing with the Firebird ODBC/JDBC Driver

Connection Parameters

Table of Contents

Read Sequence of the Keys
Connection Examples

The connection parameters for the driver comprise a list of strings in the form KEYWORD=value, separated by semicolons. The following table enumerates the keywords with their verbose meanings and, where it is not obvious, their possible values.

Table 4.1. Keywords for Connection Attributes

Keyword Description More Information
UID or USER Database account, i.e.. username ...
PWD or PASSWORD Password ...
ROLE Role ...
DSN Data source name ...
DRIVER Driver name e.g., the string Firebird/InterBase(r) driver. Defaults to the driver defined in the DSN.
DBNAME or DATABASE Database Full path to the database *as seen by the server*, including IP address | server name[/port] for a remote connection. Defaults to the database defined in the DSN.
CLIENT Local path to the required fbclient library May be needed if the connection is to be via an embedded server library located in an application folder.
CHARSET or CHARACTERSET Client-side default character set Should be the same as the default character set of the database, if possible; or one that is known to be codepage-compatible.
READONLY Read-only Set transactions in this connection to be read-only. The default is read/write.
NOWAIT No wait Set transactions in this connection to have NO WAIT lock resolution. The default is WAIT.
LOCKTIMEOUT Set the lock timeout on WAIT transaction Pass the number of seconds to elapse after encountering a lock conflict until a transaction is to return an error. Not valid if the transaction is set for NO WAIT resolution.
DIALECT Set SQL dialect Only 1 or 3 is valid. Normally this would have been set in the DSN. It must match the dialect of the database.
QUOTED Set on quoted identifiers If set in the DSN, the setting should be correct, i.e., already ON or OFF.
SENSITIVE Set on case-sensitive identifiers If set in the DSN, the setting should be correct, i.e., already ON or OFF.
AUTOQUOTED Set on auto-quoting identifiers If set in the DSN, the setting should be correct, i.e., already ON or OFF.
USESCHEMA Set on “use schema If set in the DSN, the setting should be correct.
SAFETHREAD Safe threading ...
FILEDSN File DSN Path to a file where the attribute strings from a previous connection are stored. If this string is present, the contents of the file will take priority over the main DSN.
SAVEDSN Save DSN Path to a file where the attribute strings from this connection, if successful, are to be stored. The password will be saved in encrypted format.


Read Sequence of the Keys

The ODBC function SQLDriverConnect gives priority to the attributes defined in the connection string, only fetching those stored in the DSN, or in a cited FILEDSN, to fill in any gaps.

Connection Examples

Some examples of connection strings for applications that use the ODBC function SQLDriverConnect:

Open("DSN=myDb;")
        

Here, the function is expected to read everything it needs from the DSN. User name and password are not supplied in the string. If they are not present in the DSN, either

  1. it will use the environment variables ISC_PASSWORD and ISC_USER if they are are set; otherwise
  2. it will prompt the user for the login credentials

Open("DSN=myDb; UID=MCSSITE; PWD=mcssite;")
        

The function should have what it needs to make this connection, provided the user name and password are authenticated by the server.

Open("DSN=myDb; UID=MCSSITE; PWD=mcssite; DBNAME=172.17.2.10:/usr/local/db/myDb.fdb;")

Open("DSN=myDb; UID=MCSSITE; PWD=mcssite; DBNAME=myserver:/usr/local/db/myDb.fdb;")
        

The DBNAME key points to the server IP address in the first example, with the path to the database file in the POSIX format. The second example is making the same connection, using the server's host name instead of the IP address.

Three examples including the DRIVER attribute in the string:

Open("DRIVER=Firebird/InterBase(r) driver; DBNAME=172.17.2.10:/usr/local/db/myDb.fdb;")

Open("DRIVER=Firebird/InterBase(r) driver; UID=MCSSITE; PWD=mcssite; DBNAME=172.17.2.10:/usr/local/db/myDb.fdb;")

Open("DRIVER=Firebird/InterBase(r) driver; UID=MCSSITE; PWD=mcssite; DBNAME=dummy;")
        

In the last example, a local connection using a database alias in place of the database file path. Of course, the alias must be present in aliases.conf in the root directory of the Firebird server (or, for Firebird 3 and up, in databases.conf).

Using the server IP address and specifying an alternative port, with the target database on a POSIX server; and the same using the server's host name instead:

172.17.2.10/3051:/usr/local/db/myDb.fdb

myserver/3051:/usr/local/db/myDb.fdb
        

Using the server IP address, with the target database on a Windows server; and the same using the server's host name instead:

172.17.2.10:c:\db\myDb.fdb

myserver:c:\db\myDb.fdb
        

Using the server IP address and specifying an alternative port, with the target database on a Windows server; and the same using the server's host name instead:

172.17.2.10/3051:c:\db\myDb.fdb

myserver/3051:c:\db\myDb.fdb
        

Using TCP/IP local loopback, using the L/L IP address on a POSIX server; and the same using the L/L host name localhost:

127.0.0.1:/usr/local/db/myDb.fdb

localhost:/usr/local/db/myDb.fdb
        

The same things on a Windows server:

127.0.0.1:c:\db\myDb.fdb

localhost:c:\db\myDb.fdb
        

DBNAME for Embedded Connections

The DBNAME value for embedded connections and for the “Windows Local” (XNET) style of connection uses just the file path or alias, without host name, IP address or any port number.

Note

From Windows 3 on, the way we conceptualise non-network connections on all platforms is more unified than for the earlier versions. However, from the point of view of the ODBC/JDBC driver, the expression of the DBNAME value has not changed, regardless of the platform on which we are making our embedded connection.

Local connection on a Windows server using first the file path and next an alias:

DBNAME=C:\db\myDb.fdb

DBNAME=C:dummy
          

On a POSIX server:

DBNAME=/usr/local/db/myDb.fdb

DBNAME=dummy
          

DBNAME Using Aliases

It is strongly recommended to define and use aliases to simplify life for you and your users. It makes your DBNAME values completely neutral to the filesystem and so much less cumbersome. In our last pairs of examples, the same alias was used on both Windows and POSIX. The one on the Windows server would be defined thus:

  dummy = C:\db\myDb.fdb
          

while, on the Linux server, it would be defined thus:

  dummy = /usr/local/db/myDb.fdb
          

Prev: Connecting to Firebird from ApplicationsFirebird Documentation IndexUp: Connecting to Firebird from ApplicationsNext: Developing with the Firebird ODBC/JDBC Driver
Firebird Documentation IndexFirebird ODBC/JDBC Driver ManualConnecting to Firebird from Applications → Connection Parameters