ConnectionDefinition
What is ConnectionDefinition?
Before creating a connection in FireDac, it is necessary to create a so-called ConnectionDefinition - a connection definition. This is a set of parameters - server, user, password, and other parameters that are subsequently used to establish a connection.
In FireDac, there are at least three types of ConnectionDefinition. Detailed information about this is written in the documentation.
Persistent ConnectionDefinition
Configured from FDManager and stored in an ini file. Defined once, then can be used by all connections and applications. The file containing the definitions is located at:
C:\Users\Public\Documents\Embarcadero\Studio\FireDAC\FDConnectionDefs.ini
The danger here is that the data is relatively open and can be changed. After updating the ConnectionDefinition through FDExplorer or FDAdministrator, it is necessary to either reactivate FDManager or restart the IDE.
Private ConnectionDefinition
Similar to persistent, but the data is not stored in an external file and therefore can only be used multiple times in one application.
Temporary ConnectionDefinition
It is not stored in an external file and is not managed through FDManager.
FDConnectionDefs.ini
If you open the file
C:\Users\Public\Documents\Embarcadero\Studio\FireDAC\FDConnectionDefs.ini
you will see approximately the following structure:
[FDConnectionDefs.ini]
Encoding=UTF8
[DBDEMOS]
DriverID=MSAcc
Database=C:\Users\Public\Documents\Embarcadero\Studio\17.0\Samples\data\dbdemos.mdb
[EMPLOYEE]
DriverID=IB
Protocol=TCPIP
Database=localhost:C:\ProgramData\Embarcadero\InterBase\gds_db\examples\database\employee.gdb
User_Name=sysdba
Password=masterkey
CharacterSet=
ExtendedMetadata=True
[Access_Demo]
DriverID=MSAcc
Database=C:\Users\Public\Documents\Embarcadero\Studio\17.0\Samples\data\FDDemo.mdb
[AccessDemoPooled]
DriverID=MSAcc
Database=C:\Users\Public\Documents\Embarcadero\Studio\17.0\Samples\data\FDDemo.mdb
Pooled=True
[SQLite_Demo]
DriverID=SQLite
Database=C:\Users\Public\Documents\Embarcadero\Studio\17.0\Samples\data\FDDemo.sdb
LockingMode=Normal
[SQLiteDemoPooled]
DriverID=SQLite
Database=C:\Users\Public\Documents\Embarcadero\Studio\17.0\Samples\data\FDDemo.sdb
LockingMode=Normal
Pooled=True
[MSSQL_Demo]
DriverID=MSSQL
Server=127.0.0.1
Database=Northwind
User_Name=sa
Password=
MetaDefSchema=dbo
MetaDefCatalog=Northwind
ExtendedMetadata=True
[MySQL_Connection]
Database=test_db
User_Name=root
Password=masterkey
DriverID=MySQL
[MySQL_Demo]
DriverID=MySQL
Database=addemo
User_Name=root
[ConnectionDef1]
Database=array_db
User_Name=root
DriverID=MySQL
[ConnectionDef2]
Database=array_db
User_Name=root
DriverID=MySQL
[MySQLarraydb]
Database=array_db
User_Name=root
Password=masterkey
DriverID=MySQL
Yes, essentially, the sections contain sets of parameters that the Delphi IDE and our application use to establish connections.
Here are several ways to modify the FDConnectionDefs.ini file:
Manual Editing: If you understand the parameters, you can simply open the file and enter or modify the parameters for your ConnectionDefinition.
Using Data Explorer: In Delphi, you can open the Data Explorer (File | Data Explorer | FireDac | MySQL Server) and right-click to add a connection. Although this method is not described in the official documentation, it works perfectly well.
Using FDExplorer or FDAdministrator: You can also use the FDExplorer or FDAdministrator tools to edit the ConnectionDefinition.
Ultimately, the choice of method depends on your preferences. It's important to save the connection parameters for later use.
How to help the application find the FDConnectionDefs.ini file?
It's very simple. You need to add the FDManager component to the application and set the FDManager.ConnectionDefFileName property to the path of our FDConnectionDefs.ini file.
Generally, regarding this matter, the documentation provides the following information:
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\da-soft\FireDAC\ConnectionDefFile. By default it is $(ADHome)\DB\ADConnectionDefs.ini.
Note: At design time, FireDAC ignores the value of the ADManager.ConnectionDefFileName, and looks for a file in a Delphi Bin folder or as specified in the registry. If the file is not found, an exception is raised.
In other words, the best approach is to directly specify to the application where the file is located using FDManager.ConnectionDefFileName. If you don't do this, the application will search for this file in the EXE folder, and then attempt to locate it through the registry.
Additionally, it's necessary to set the FDManager.ConnectionDefFileAutoLoad property to True. Otherwise, you'll have to explicitly call the FDManager.LoadConnectionDefFile method before the first use of FDConnection, for example, before FDConnection:=true.
Practice: Creating ConnectionDefs and FDConnections
Creating Persistent ConnectionDefinition
Let's create a VCL project. Add one button to the form and the following components:
In the uses section, let's write:
uses
FireDAC.Comp.Client, FireDAC.Stan.Intf;
Next, let's write a helper procedure:
procedure TForm1.AddConnectionDef(Sender: TObject);
var myDef:IFDStanConnectionDef; i:integer;
begin
// Check if there is already a ConnDef with the same namefor i := 0 to FDManager1.ConnectionDefs.Count-1 do
begin
if FDManager1.ConnectionDefs[i].Name='MySQLPersistentdef'
then exit;
end;
// Next, we add it if ConnDef with the name MySQLPersistentdef is absentmyDef:=FDManager1.ConnectionDefs.AddConnectionDef;
myDef.Name:='MySQLPersistentdef';
myDef.Params.DriverID:='MySQL';
myDef.Params.Database:='test_db';
myDef.Params.UserName:='root';
myDef.Params.Password:='masterkey';
// Next, another technique for adding parametersmyDef.Params.Add('Server=127.0.0.1'); // << I couldn't find 'Server' in the properties, so I added it like this
// Marking myDef as Persistent, without this it would be Private
myDef.MarkPersistent;
// Saving the changes in the FDConnectionDefs.ini file
myDef.Apply;
end;
Next, let's handle the button bConnection like this:
procedure TForm1.bConnectClick(Sender: TObject);
begin
Self.AddConnectionDef(Self);
FDConnection1.ConnectionDefName:='MySQLPersistentdef';
FDConnection1.Connected:=true;
if FDConnection1.Connected then showmessage('Connected')
else showmessage('could not connect');
end;
Also, my application requested the FDPhysMySQLDriverLink1 component. In the VendorLib property, I directly specified the location of the libmysql.dll file.
Result
Creating a Private Connection Definition
In this case, you can repeat the previous example but omit the line
// Marking myDef as Persistent, without this it would be Private
myDef.MarkPersistent;
Creating a Temporary Connection Definition
Here it's quite straightforward. If it's design time, you need to add FDConnection to the form, double-click on it, fill in the parameters, and then click the 'Connected' checkbox in the Object Inspector.
If it's run-time, you can do it like this:
FDConnection1.DriverName := 'MySQL';
FDConnection1.Params.Add('Server=127.0.0.1');
FDConnection1.Params.Add('Database=test_db');
FDConnection1.Params.Add('User_name=root');
FDConnection1.Params.Add('Password=masterkey');
FDConnection1.Connected := True;
We've covered the main points, the rest is a matter of technique and experimentation. Good luck with your development!