Connect to Firebird (FireDAC)

From RAD Studio
Jump to: navigation, search

Go Up to Database Connectivity (FireDAC)

This topic describes how to connect to Firebird database.

Supported Versions

The FireDAC native driver supports the Firebird server and the version of the embedded editions 1.5 and later. It does not officially support Jaffil.

To connect to InterBase, use the FireDAC InterBase driver.

Client Software

Windows Client Software

FireDAC requires the following x86 or x64 client software to be installed on the workstation:

  • The FBCLIENT.DLL library to connect to the Firebird server. You can take it from a server (download) installation Bin folder.
  • The FBEMBED.DLL library to work with the database using the Firebird Embedded server (details).
Note: It is critical to use the appropriate DLL for the DBMS client library. Do not use GDS32.DLL with Firebird or FBCLIENT.DLL with InterBase.
Note: Firebird 4.0 client may need some ICU files if you want to work with datatypes like TIMESTAMP WITH TIME ZONE and TIME WITH TIME ZONE. For further information click here.
Warning: Firebird 4.0 requires installing Microsoft Runtime ++ 2017 with the same bitness as the FBCLIENT.DLL file.

You can put the required files in:

  • a folder listed in your PATH environment variable (for example, <Windows>\SYSTEM32)
  • your application EXE folder

Alternatively, you may put the required files in any other folder, and specify their path in FDDrivers.ini:

[FB]
VendorLib=<folder>\fbclient.dll

If the Firebird client library has not been installed properly, an exception is raised when you try to connect:

[FireDAC][Phys][FB]-314. Cannot load vendor library [fbclient.dll]. The specified module could not be found. Check [fbclient.dll], which is located in one of the PATH directories or in the application EXE directory.

macOS Client Software

FireDAC requires:

the libfbclient.dylib x86 client library to connect to the Firebird server. You can take it from a server (download) installation /Library/Frameworks/Firebird.framework/Versions/A/Resources/lib/

There are two indispensable libraries:

  • /Library/Frameworks/Firebird.framework/Versions/A/Resources/lib/libfbclient.dylib
  • /Library/Frameworks/Firebird.framework/Versions/A/Resources/lib/libtommath.dylib

Linux Client Software

FireDAC requires the Firebird client library. To install it:

  1. On Ubuntu Server 16.04 LTS, run:
    sudo apt-get install libfbclient2
    sudo ln -s /usr/lib/x86_64-linux-gnu/libfbclient.so.2 /usr/lib/x86_64-linux-gnu/libfbclient.so
    
  2. On Red Hat Enterprise Linux 7, run:
    sudo yum install firebird-libfbclient
    sudo ln -s /usr/lib64/libfbclient.so.2 /usr/lib64/libfbclient.so
    

Driver Linkage

To link the driver:

Connection Definition Parameters

To connect to the Firebird DBMS, most applications require that you specify the DriverID, Protocol, Server, Database, User_Name, Password, and CharacterSet connection definition parameters (see Defining Connection (FireDAC) for details).

DriverID=FB

Parameter Description Example value
Database

The database name to attach. The value can be:

  • database file path.
  • full database path, including server address.

For an embedded database, a path can include path variables.

  • C:\ib\ADDEMO_IB2007.IB
  • 127.0.0.1:C:\ib\ADDEMO_IB2007.IB
  • \\MySrv\C:\ib\ADDEMO_IB2007.IB
OSAuthent

Controls authentication mode:

  • Yes -- use Windows authentication.
  • No -- use DBMS authentication. It is the default value.

For details, see the doc\README.trusted_authentication.txt.

Yes
User_Name The user name. sysdba
Password The user password. masterkey
CharacterSet Specifies the character set to use.
We strongly recommend you to explicitly set the CharacterSet parameter to one of the following values:
  • UTF8, if your application needs to support Unicode. For details, see Unicode Usage (FireDAC).
  • WIN1250 for Central Europe.
  • WIN1251 for Cyrillic.
  • WIN1252 for Western Europe, America.
  • and so on.
WIN1252
ExtendedMetadata

Controls the extended description of the query result sets:

  • True -- FireDAC is getting column domain names additional to the other column attributes. If a column belongs to a domain with a name such as %BOOL%, it is described as dtBoolean. Also, if a table has an INSERT trigger that reads a single sequence and assigns its value to a single column, then this column is described as an auto-incrementing one. Setting this option to True slightly slows down a dataset opening.
  • False -- FireDAC uses the restricted information about the query columns. It is the default value.
False
Port

The TCP/IP port on which the Interbase server is listening. By default, it is equal to 3050. When it is differrent, then you should set the "Port" parameter to the required value.

3051
Protocol

The protocol used to connect to the DB server. This parameter can take one of the following values:

  • Local -- connects to a locally running server, to an embedded server, or to a server using an alias.
  • NetBEUI -- connects using the Microsoft NetBIOS protocol.
  • SPX -- connects using the Novel SPX protocol.
  • TCPIP -- connects using the TCP/IP protocol.

If the Protocol parameter is specified, FireDAC builds full database paths, using the appropriate Protocol format and Server and Database parameter values.

TCPIP
Server Server address to connect to. The Server parameter value is used only if the Protocol parameter is specified. To specify a TCP/IP port number use the <host>/<port> notation.
  • 127.0.0.1
  • my_host/3055
SQLDialect The SQL Dialect to use for connecting. Three is the default value. 1
RoleName The default role name. Admin
OpenMode

Specifies how to open a database. The following modes are supported:

  • Open -- opens an existing database file specified in the Database parameter. If the specified database does not exist, the application throws an exception. It is the default value.
  • Create -- creates a new database. If the specified database exists, the application throws an exception.
  • OpenOrCreate -- opens an existing database or creates a new database if the specified database does not exist.
Open
DropDatabase

Controls the deletion of an existing database:

  • Yes -- drop the database file specified in the Database parameter, immediately after disconnecting from the server.
  • No -- do not drop. It is the default value.
Yes
PageSize The page size used for the newly created database if CreateDatabase = Yes. 1024 is the default value. 4096
IBAdvanced The ';' separated list of additional parameters. You can find the full list of supported parameters in the FireDAC.Phys.IBWrapper unit (see the DPBInfos constant array). You can find the description of each Code listed there in the Interbase/Firebird manuals.
GUIDEndian It defines how the GUID value is represented on the client. Little

Local Connections

A local connection string consists of the path and the filename specification in the native format of the filesystem used on the server machine. Local connection string can also be a database alias that is defined in database.configuration. The alias format depends on how it is defined in the configuration file. Examples:

  • zappa
  • blackjack.fdb
  • poker

Upon receiving a local connection string, the FireBird client attempts to direct embedded connection in the database file.

Use Cases

  • Connect to a database running on a remote server via TCP/IP protocol:
DriverID=FB
Database=C:\fb\ADDEMO_FB21.FDB
Protocol=TCPIP
Server=FBSrv
User_Name=sysdba
Password=masterkey
CharacterSet=win1252
ExtendedMetadata=True
  • Connect to a database running on a remote server via TCP/IP protocol:
DriverID=FB
Database=FBSrv:C:\fb\ADDEMO_FB21.FDB
User_Name=sysdba
Password=masterkey
CharacterSet=utf8
  • Connect to a database running on a remote server via TCP/IP protocol and activate compression:
DriverID=FB
Database=FBSrv:C:\fb\ADDEMO_FB21.FDB
User_Name=sysdba
Password=masterkey
IBAdvanced=Config=WireCompression=true
  • Connect to a local database:
DriverID=FB
Database=C:\fb\ADDEMO_FB21.FDB
User_Name=sysdba
Password=masterkey
CharacterSet=win1251
  • Connect to a Firebird Embedded database:

Drop the TFDPhysFBDriverLink component to the form and set its VendorLib to <your path<\fbembed.dll or use a virtual driver definition.

DriverID=FB
Database=C:\fb\ADDEMO_FB21.FDB
User_Name=sysdba
CharacterSet=utf8

See Also

Samples