Configuring Drivers (FireDAC)
Go Up to Working with Connections (FireDAC)
Describes how to configure the FireDAC DBMS drivers, including how to specify a DBMS client library. To link a FireDAC driver to an application, specify the DBMS client to the driver and other optional parameters. An application may use the TFDPhysXxxDriverLink components and/or an external configuration file.
Contents
General
To adjust the behaviour of a driver, you can use a driver configuration file or the TFDPhysXxxDriverLink components. Most of the driver configuration file discussion also applies to the TFDPhysXxxDriverLink components.
Driver Configuration File
A driver configuration file is a standard INI text file. It can only be edited manually. Basically, the driver configuration file allows you to:
- Adjust parameters of a base driver (section name = base driver ID).
- Introduce a new virtual driver, which is a set of the base driver parameters saved under a new name (section name = new virtual driver ID).
FireDAC searches for the driver configuration file in the following places:
- FDDrivers.ini in the application EXE folder.
- If the file above is not found, it looks for the file specified in the registry key HKCU\Software\Embarcadero\FireDAC\DriverFile. By default, this is
C:\Users\Public\Documents\Embarcadero\Studio\FireDAC\FDDrivers.ini.
At design time, FireDAC uses the file in the RAD Studio Bin folder or as specified in the registry.
Base and Virtual Drivers
If the section name in the driver configuration file is the base driver ID (for example, "ASA" or "Ora"), the base driver uses the parameter values specified in the corresponding section.
If the section name is not an ID of any of the base drivers (for example, "Ora815" or "MySQL510_Embedded"), FireDAC registers a new virtual driver. The virtual driver uses the implementation of the base driver specified by the BaseDriverID parameter and the specified parameter values. A virtual driver ID can then be used as the value of the DriverID connection definition parameter. A virtual driver allows the application to:
- Work with different versions of the DBMS client software in different connections, established in the same application run, for example to connect to InterBase and Firebird.
- Choose an explicit version of the DBMS client software, for example to use one of the many LIBMYSQL.DLLs installed on the workstation.
- Set up drivers that require parameters to be specified, for example MySQL Embedded server.
Driver Configuration Parameters
The following parameters can be specified:
| Parameter | Description | Applied to Drivers |
|---|---|---|
| VendorHome[ | Win32 | Win64 | MacOS32 | MacOS64 | UIX32 | UIX64] | The Oracle Home name. | Ora |
| The base installation path. For example: C:\ib\ib2007. | IB | |
| The base installation path for a normal server. For example: C:\MySQL\MySQL5-1-7. Or the path to LIBMYSQLD.DLL for an embedded server. For example C:\MyAPP\MySQL. | MySQL | |
| VendorLib[ | Win32 | Win64 | MacOS32 | MacOS64 | UIX32 | UIX64] | The DBMS client software API DLL name. For example: libmysql510.dll. |
|
| ODBCDriver | ODBC driver name. For example: Adaptive Server Anywhere 8.0. | All ODBC based |
| ODBCAdvanced | ODBC driver additional parameters.
The string consists of ODBC driver parameters separated by ?;?. For possible values, check the vendor documentation. |
All ODBC based |
| EmbeddedArgs | MySQL embedded server arguments.
The string consists of MySQL server arguments separated by ?;?. For possible values, check the vendor documentation. For example: --datadir=./data;--language=./;--skip-innodb. |
MySQL |
| EmbeddedGroups | MySQL embedded server configuration file groups. | MySQL |
| NLSLang | Oracle NLS_LANG environment variable value. | Ora |
| TNSAdmin | Oracle TNS_ADMIN environment variable value. | Ora |
For non-ODBC based drivers, if the VendorLib is specified, FireDAC uses the specified DLL. If the VendorHome is specified, the DLL with default name from the Bin subfolder is used. If none is specified, a DLL with a default name from:
- the primary Oracle Home for the Ora driver.
- the leftmost folder in the PATH environment variable, containing the DLL, for other drivers
are used. Additionally you may specify a suffix, designating a platform.
For ODBC based drivers, if the ODBCDriver is specified, FireDAC uses the specified driver. If it is not specified, a default driver name is used.
Sample Driver Configuration File Content
[ASA]
; ASA base driver will use specified ODBC driver
ODBCDriver=Adaptive Server Anywhere 8.0
[Ora815]
; Ora815 virtual driver will use specified Oracle Home
BaseDriverID=Ora
VendorHomeWin32=OraHome815
VendorHomeWin64=OraHome815_64
[MySQL327]
; MySQL327 virtual driver will use specified LIBMYSQL.DLL
BaseDriverID=MySQL
VendorLib=c:\LIBMYSQL327.DLL
[MySQL510_Embedded]
; MySQL510_Embedded virtual driver will use specified MySQL embedded library and arguments
BaseDriverID=MySQL
VendorLib=c:\LIBMYSQLD.DLL
EmbeddedArgs=--datadir=./data;--language=./;--skip-innodb;--skip-networking
[MSSQL_2000]
; MSSQL_2000 virtual driver will use specified ODBC driver
BaseDriverID=MSSQL
ODBCDriver=SQL SERVER
ODBCAdvanced=
[FB21]
; FB21 virtual driver will use specified Firebird client library
BaseDriverID=FB
VendorLibWin32=C:\ib\fb21\bin\fbclient.dll
VendorLibWin64=C:\ib\fb21_64\bin\fbclient.dll
[FB21_Embedded]
; FB21_Embedded virtual driver will use specified Firebird client library
BaseDriverID=FB
VendorLib=C:\ib\fb21_embed\bin\fbembed.dll
Configuring Drivers in Code
You can also configure FireDAC drivers in the application code at run time. To do this, drop the appropriate TFDPhysXXXDriverLink components to your form. It has the same named properties as the parameters in the driver configuration file. The link component properties must be set before opening a first connection to a DBMS through this driver. The following code sample shows how to configure the Firebird driver at run time:
interface
uses
..., FireDAC.Phys.FB;
type
TForm1 = class(TForm)
......
FDPhysFBDriverLink1: TFDPhysFBDriverLink;
FDConnection1: TFDConnection;
procedure FormCreate(Sender: TObject);
......
end;
implementation
{$R *.dfm}
procedure TForm1.FormCreate(Sender: TObject);
begin
FDPhysFBDriverLink1.VendorLib := 'C:\ib\fb21_embed\bin\fbembed.dll';
FDConnection1.ConnectionDefName := 'FB_Demo';
FDConnection1.Connected := True;
end;
When a connection using a driver has been established and an application needs to switch to the other DBMS client:
- close all connections on this driver.
- call the driver link Release method.
- change the required link properties.
The next connection using this driver uses the new link properties. The following code sample shows how to change the Firebird driver configuration at run time:
FDConnection1.Close;
FDPhysFBDriverLink1.Release;
FDPhysFBDriverLink1.VendorLib := 'C:\fbclient.dll';
FDConnection1.Open;
Note: Although it is possible to use link components to configure drivers at design time, we do not recommend it, because it is difficult to load a module with a link component before any other module with the FireDAC components is loaded. Therefore, the link component configures the driver properly.