Establishing Connection (FireDAC)

Go Up to Working with Connections (FireDAC)

Describes how to open and close a connection to a DBMS using FireDAC. FireDAC provides the TFDConnection component to help you open a connection to a database.

General

After a connection definition is created, the connection to a database can be established. In general, there are two ways of doing this:

• explicitly, by setting TFDCustomConnection.Connected to True or calling one of the Open methods.
• implicitly, by performing any action that requires talking to a DBMS. For example, by setting the linked TFDQuery Active property to True. Note that ResourceOptions.AutoConnect must be True, otherwise an exception is raised.

FireDAC provides several TFDCustomConnection.Open methods additional to the Connected property. These methods allows you to use a FireDAC connection string, which is a string in the form of param=value[;...param=value]. For example:

FDConnection1.Open('DriverID=SQLite;Database=c:\test.sdb;Password=12345');

The BeforeConnect event is fired before the connection is opened. After the connection is established the AfterConnect event is fired.

Handling Connection Errors

If the connection establishment fails, then an application may analyze the failure using one of the approaches:

• using TFDCustomConnection.OnError event handler. This is more appropriate when a connection is opened implicitly.
• using the try ... except ... end syntax. This is the best approach with an explicit connection establishment. For example:

uses
  FireDAC.Stan.Consts, FireDAC.Stan.Error;
...
try
  FDConnection1.Connected := True;
except
  on E: EFDException do
    if E.FDCode = er_FD_ClntDbLoginAborted then
      ; // user pressed Cancel button in Login dialog
  on E: EFDDBEngineException do
    case E.Kind of
    ekUserPwdInvalid: ; // user name or password are incorrect
    ekUserPwdExpired: ; // user password is expired
    ekServerGone: ;     // DBMS is not accessible due to some reason
    else                // other issues
    end;
end;

Note: The Login dialog automatically handles the type of error ekUserPwdInvalid, by suggesting the user to input the login credentials again. To disable this handling, set TFDGUIxLoginDialog.LoginRetries to -1. The ekUserPwdExpired error is also automatically handled, by suggesting the user to input the password again.

Also, if the connection recovery is set up, then the type of error ekServerGone brings a connection to an initially offline state. Alternatively, the TFDCustomConnection.Ping method can be used to avoid the ekServerGone error and make the connection active, when a DBMS is available.

For more details, see "Handling Errors".

Using the Login Dialog

The GUI application may use the TFDGUIxLoginDialog component to allow the end users to enter the database credentials. The login dialog may be bound in one of the following ways:

• Drop the TFDGUIxLoginDialog component to a form. No additional setup is required. This dialog will be a default Login dialog for an application.
• Drop the TFDGUIxLoginDialog component to a form and set TFDCustomConnection.LoginDialog to this dialog. The dialog will be used privately by this connection.

The Login dialog is automatically invoked by the TFDCustomConnection, when LoginPrompt = True:

Using the TFDGUIxLoginDialog.VisibleItems property, you can specify which connection definition parameters to show the end user and how to name them. The last option allows you to localize the Login dialog. For example, German speaking SQL Server developers may specify:

with FDGUIxLoginDialog1.VisibleItems do begin
  Clear;
  Add('Server');
  Add('User_name=Benutzer');
  Add('Password=Kennwort');
  Add('OSAuthent');
end;
FDConnection1.LoginDialog := FDGUIxLoginDialog1;
FDConnection1.Connected := True;

When a DBMS supports password expiration, the password is expired and TFDGUIxLoginDialog.ChangeExpiredPassword is True, the dialog asks for a new password.

Closing Connection

The connection can be closed in one of the following ways:

• explicitly, by setting TFDCustomConnection.Connected to False.
• implicitly, when the connection object has no more active commands and datasets and the ResourceOptions.KeepConnection is False.

FireDAC finishes the active transactions, if any, before the connection is closed. Use TxOptions.DisconnectAction to control the performed action.

Also, the TFDCustomConnection.BeforeDisconnect event is fired before this. After the connection is closed, the AfterDisconnect event is fired.

See Also

• Handling Errors
• Defining Connection
• Offlining Connection