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.
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:
|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
Note: If you add a new persistent connection definition using FDExplorer or FDAdministrator while the RAD Studio IDE is running, it is not visible to the FireDAC design time code. To refresh the persistent connection definitions list, you need to reactivate FDManager or restart the RAD Studio IDE.
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
Note: At design time, FireDAC ignores the value of the FDManager.ConnectionDefFileName, and looks for a file in a RAD Studio Bin folder or as specified in the registry. If the file is not found, an exception is raised.
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
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.Intf; var oDef: IFDStanConnectionDef; begin oDef := FDManager.ConnectionDefs.AddConnectionDef; oDef.Name := 'MSSQL_Connection'; oDef.DriverID := 'MSSQL'; oDef.Server := '127.0.0.1'; oDef.Database := 'Northwind'; oDef.OSAuthent := True; oDef.MarkPersistent; oDef.Apply; ..................... FDConnection1.ConnectionDefName := 'MSSQL_Connection'; FDConnection1.Connected := True;
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
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.
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;