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.
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:
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
ekUserPwdExpirederror 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
TFDGUIxLoginDialogcomponent to a form. No additional setup is required. This dialog will be a default Login dialog for an application.
- Drop the
TFDGUIxLoginDialogcomponent 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.
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.