Defining Connection (FireDAC)
Go Up to Working with Connections (FireDAC)
Describes how to store and use FireDAC connection parameters and what a connection definition means. To specify connection parameters, an application must use a connection definition. The connection definition is a set of parameters. A connection may also be pooled.
Contents
General
A connection definition is a set of parameters that defines how to connect an application to a DBMS using a specific FireDAC driver. It is the equivalent of a BDE alias, ADO UDL (stored OLEDB connection string), or ODBC Data Source Name (DSN). For the list of supported database management systems and corresponding parameters, see FireDAC Database Connectivity.
FireDAC supports 3 connection definition kinds:
Type | Description | Pros | Cons |
---|---|---|---|
Persistent | Has a unique name, is managed by the FDManager, and is stored in a connection definition file. | May be defined once and reused across many applications. May be pooled. | The parameters (server address, DB name, and so on) are publicly visible and may be changed incidentally.
FDManager has to be reactivated or the Delphi IDE has to be restarted to make a newly added definition visible at design time. |
Private | Has a unique name, is managed by the FDManager, but is NOT stored in a connection definition file. | Connection definition parameters are not visible "outside" the application. May be pooled. | The application needs to create a private connection definition after each program restarts and cannot share it with the other programs.
Cannot be created at design time. |
Temporary | Has no name, is not stored in a connection definition file, and is not managed by the FDManager. | The simplest way to create a connection definition is to fill in the TFDConnection.Params property.
Can be created at design time using the TFDConnection component editor. |
Similar to private. Also cannot be referenced by name and cannot be pooled. |
Connection Definition File
The persistent connection definitions are stored in an external file - the connection definition file. This file has the standard INI text file format. It can be edited by FDExplorer or FDAdministrator utilities at first, manually, or by code. By default the file is C:\Users\Public\Documents\Embarcadero\Studio\FireDAC\FDConnectionDefs.ini
.
Sample content of this file:
[Oracle_Demo]
DriverID=Ora
Database=ORA_920_APP
User_Name=ADDemo
Password=a
MetaDefSchema=ADDemo
;MonitorBy=Remote
[MSSQL_Demo]
DriverID=MSSQL
Server=127.0.0.1
Database=Northwind
User_Name=sa
Password=
MetaDefSchema=dbo
MetaDefCatalog=Northwind
MonitorBy=Remote
An application can specify a connection definition file name in the FDManager.ConnectionDefFileName property. FireDAC searches for a connection definition file in the following places:
- If ConnectionDefFileName is specified:
- search for a file name without a path, then look for it in an application EXE folder.
- otherwise just use a specified file name.
- If ConnectionDefFileName is not specified:
- look for FDConnectionDefs.ini in an application EXE folder.
- If the file above is not found, look for a file specified in the registry key HKCU\Software\Embarcadero\FireDAC\ConnectionDefFile. By default it is
C:\Users\Public\Documents\Embarcadero\Studio\FireDAC\FDConnectionDefs.ini
.
If FDManager.ConnectionDefFileAutoLoad is True, a connection definition file loads automatically. Otherwise, it must be loaded explicitly by calling the FDManager.LoadConnectionDefFile method before the first usage of the connection definitions. For example, before setting TFDConnection.Connected to True.
Creating a Persistent Connection Definition
A persistent connection definition can be created using FDExplorer or FDAdministrator. Here is how you can do that in code. Also see the demo Connection Definitions.
The following code snippet creates a connection definition named "MSSQL_Connection", which has all parameters required to connect to the Microsoft SQL Server running locally, using the OS authentication (SSPI):
uses
FireDAC.Comp.Client, FireDAC.Stan.Def, FireDAC.Stan.Intf,
// Required uses for creating a persistent connection with MSSQL (to fdconnectiondefs.ini)
FireDAC.Phys.MSSQL,
FireDAC.Phys.MSSQLDef;
const
cNameConnDef = 'MSSQL_Connection';
procedure TForm1.PersistentConnectionClick(Sender: TObject);
var
oDef: IFDStanConnectionDef;
oParams: TFDPhysMSSQLConnectionDefParams; // MSSQL connection params
begin
// Adding new persistent connection to fdconnectiondefs.ini
FDManager.ConnectionDefs.AddConnectionDef;
oDef := FDManager.ConnectionDefs.AddConnectionDef;
oDef.Name := cNameConnDef;
oParams := TFDPhysMSSQLConnectionDefParams(oDef.Params);
oParams.DriverID := 'MSSQL'
oParams.Database := 'Northwind';
oParams.UserName := '.............';
oParams.Password := '.............';
oParams.Server := '127.0.0.1';
oParams.OSAuthent := false;
oParams.MARS := false;
oDef.MarkPersistent;
oDef.Apply;
end;
.....................
procedure TForm1.ConnectionClick(Sender: TObject);
FDConnection1.ConnectionDefName := cNameConnDef;
FDConnection1.Connected := True;
end;
FDManager is a global instance of the FireDAC connection manager. Its property FDManager.ConnectionDefs: IFDStanConnectionDefs is a collection of the persistent and private connection definitions. The AddConnectionDef method adds a new connection definition. The MarkPersistent method marks a connection definition as persistent. The Apply method saves a connection definition to a connection definition file. Without the MarkPersistent call, the connection definition is private.
Creating a Private Connection Definition
A private connection definition can be created only in code. The code is similar to the one above, but without the MarkPersistent call.
Also, you can use a technique similar to BDE:
var
oParams: TStrings;
begin
oParams := TStringList.Create;
oParams.Add('Server=127.0.0.1');
oParams.Add('Database=Northwind');
oParams.Add('OSAuthent=Yes');
FDManager.AddConnectionDef('MSSQL_Connection', 'MSSQL', oParams);
.....................
FDConnection1.ConnectionDefName := 'MSSQL_Connection';
FDConnection1.Connected := True;
Creating a Temporary Connection Definition
At Design-Time
A temporary connection definition can be created at design time using the FireDAC Connection Editor. In order to do this, double-click a TFDConnection to invoke the editor:
Or by clicking the TFDConnection icon in the Design mode and selecting the driver from the DriverName property from the Object Inspector. After that, expand the Params property and setup the required properties. The last step is to set the Connected property to True.
Also, the FDExplorer can be invoked at design-time using the pop-up menu for the TFDConnection component to explore the content of a database and execute ad-hoc queries.
At Run-Time
To create a temporary connection at run time in code fill the TFDConnection.Params property. This is the simplest and the most convenient way to create a connection definition.
FDConnection1.DriverName := 'MSSQL';
FDConnection1.Params.Add('Server=127.0.0.1');
FDConnection1.Params.Add('Database=Northwind');
FDConnection1.Params.Add('User_name=sa');
FDConnection1.Connected := True;
Another way to create a temporary connection definition at run time is to cast the TFDConnection.Params property to a DBMS specific class. This is the safest way to create a connection definition, because the IDE Code Insight and compiler syntax checking may be used to check the correctness.
uses
FireDAC.Phys.IBDef, FireDAC.Phys.IBWrapper;
......
FDConnection1.DriverName := 'IB';
with FDConnection1.Params as TFDPhysIBConnectionDefParams do begin
Protocol := ipTCPIP;
Server := '127.0.0.1';
Database := 'c:\IB\employee.gdb';
UserName := 'sysdba';
Password := 'masterkey';
end;
FDConnection1.Connected := True;
Another option is to specify a connection string at run time by filling the TFDConnection.ConnectionString property. A connection string may be a convenient way to specify connection definition parameters for certain types of applications. For example:
FDConnection1.ConnectionString := 'DriverID=MSSQL;Server=127.0.0.1;Database=Northwind;User_name=sa';
FDConnection1.Connected := True;
Editing a Connection Definition
An application may need an ability to create and edit a connection definition at run time using standard FireDAC Connection Editor dialog. To edit a temporary connection definition stored in TFDConnection, use the code:
uses
FireDAC.VCLUI.ConnEdit;
...
if TfrmFDGUIxFormsConnEdit.Execute(FDConnection1, '') then
FDConnection1.Connected := True;
To edit a connection definition represented as a FireDAC connection string, use the code:
uses
FireDAC.VCLUI.ConnEdit;
...
var
sConnStr: String;
...
sConnStr := FDConnection1.ResultConnectionDef.BuildString();
if TfrmFDGUIxFormsConnEdit.Execute(sConnStr, '') then begin
FDConnection1.ResultConnectionDef.ParseString(sConnStr);
FDConnection1.Connected := True;
end;
See Also
- FDAdministrator utility
- FDExplorer utility
- FireDAC Database Connectivity
- Multithreading
- Path Variables
Samples
- FireDAC Connection Definitions sample
- FireDAC Create Connection sample
- FireDAC InterBase sample
- FireDAC MS Access sample
- FireDAC MS SQL sample
- FireDAC MySQL sample
- FireDAC SQLite sample