Defining Connection (FireDAC)

From RAD Studio
Jump to: navigation, search

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.

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.

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 C:\Users\Public\Documents\Embarcadero\Studio\FireDAC\FDConnectionDefs.ini.
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

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:

Defining.png

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

Samples