FirebirdSQL logo

Connection strings

If you want to connect to a database or create one you have to supply, amongst other things, a connection string to the client application (or, if you are a programmer, to the routines you are calling).A connection string uniquely identifies the location of the database on your computer, local network, or even the Internet.

Local connection strings

An explicit local connection string consists of the path + filename specification in the native format of the filesystem used on the server machine, for example

  • on a Linux or other Unix-like server:

    /opt/firebird/examples/empbuild/employee.fdb
  • on a Windows server:

    C:\Biology\Data\Primates\Apes\populations.fdb

Many clients also allow relative path strings (e.g. “..\examples\empbuild\employee.fdb”), but you should use these with caution, as it’s not always obvious how they will be expanded.Getting an error message is annoying enough, but applying changes to another database than you thought you were connected to may be disastrous.

Instead of a file path, the local connection string may also be a database alias that is defined in databases.conf, as mentioned earlier.The format of the alias depends only on how it’s defined in the configuration file, not on the server filesystem.Examples are:

  • zappa

  • blackjack.fdb

  • poker

Upon receiving a local connection string, the Firebird client will first attempt to make a direct, embedded connection to the database file, bypassing authentication but respecting the SQL privileges and restrictions of the supplied user and/or role name.That is, if the Engine13 provider is enabled in firebird.conf or databases.conf — which it is by default.If the database file exists, but the connection fails because the client process doesn’t have the required access privileges to the file, a client-server connection is attempted (by the Loopback provider), in this order:

  1. On Windows: using XNET (shared memory) on the local machine;

  2. Using TCP/IP via localhost.

You can force Firebird to use a certain protocol (and skip the embedded connection attempt) by prepending the protocol in URL style:

  • inet://zappa (TCP/IP connection using an alias on the local machine)

  • inet:///opt/firebird/examples/citylife.fdb (TCP/IP connection using an absolute path on the local POSIX machine — notice the extra slash for the root dir)

  • inet://C:\Work\Databases\Drills.fdb (TCP/IP connection using an absolute path on the local Windows machine)

  • xnet://security.db (XNET connection using an alias on the local Windows machine)

  • xnet://C:\Programmas\Firebird\Firebird_3_0\security3.fdb (XNET connection using the full path on the local Windows machine)

Tip

If your XNET connections fail, it may be because the local protocol isn’t working properly on your machine.If you’re running Windows with terminal services enabled, this can often be fixed by setting IpcName to Global\FIREBIRD in the configuration file firebird.conf (don’t forget to uncomment the parameter and restart the server).

If setting IpcName doesn’t help, and you can’t get the local protocol enabled, you can usually work around the problem by using inet://, or putting “localhost:” before your database paths or aliases, thus turning them into TCP/IP connection strings (discussed below).

TCP/IP connection strings

Firebird has two forms of TCP/IP connection strings:

  1. {inet|inet4|inet6}://[<host>[:<port>]/]<path-or-alias>

  2. <host>[/port]:<path-or-alias>

With:

<host>

a server name or IP address (for IPv6 addresses, enclose them in [ and ])

<port>

port number or service name

<path-or-alias>

either the absolute path + filename on the server machine, or an alias defined on the server machine

Examples:

  • On Linux/Unix:

    pongo:/opt/firebird/examples/empbuild/employee.fdb
    inet://pongo//opt/firebird/examples/empbuild/employee.fdb
    bongo/3052:fury
    inet://bongo:3052/fury
    112.179.0.1:/var/Firebird/databases/butterflies.fdb
    inet://112.179.0.1//var/Firebird/databases/butterflies.fdb
    localhost:blackjack.fdb
    inet://localhost/blackjack.fdb
  • On Windows:

    siamang:C:\Biology\Data\Primates\Apes\populations.fdb
    inet://siamang/C:\Biology\Data\Primates\Apes\populations.fdb
    sofa:D:\Misc\Friends\Rich\Lenders.fdb
    inet://sofa/D:\Misc\Friends\Rich\Lenders.fdb
    inca/fb_db:D:\Traffic\Roads.fdb
    inet://inca:fb_db/D:\Traffic\Roads.fdb
    127.0.0.1:Borrowers
    inet://127.0.0.1/Borrowers

Notice how the aliased connection strings don’t give any clue about the server OS.And they don’t have to, either: you talk to a Linux Firebird server just like you talk to a Windows Firebird server.In fact, specifying an explicit database path is one of the rare occasions where you have to be aware of the difference.

XNET connection strings

The syntax for XNET URLs is:

xnet://<path-or-alias>

Since XNET is a purely local protocol, you can’t include a hostname or port.