TdxBackendDatabaseSQLConnection Class

A non-visual component designed to fetch data from a relational database (SQL Server, PostgreSQL, SQLite, etc.).

Declaration

TdxBackendDatabaseSQLConnection = class(
    TdxBackendCustomDataConnection
)

Remarks

Data connection components allow you to bind TdxDashboard/TdxDashboardControl and TdxReport components to data.

Supported Database Engines

The VCL Backend implementation has built-in support for Microsoft SQL Server/Azure SQL and SQLite database engines.

Tip

You can use the TdxBackendDatabaseSQLConnection component to connect TdxDashboard/TdxDashboardControl and TdxReport components to these databases without additional dependencies and extra configuration.

Other Supported Database Engines

In addition, you can use the TdxBackendDatabaseSQLConnection component to connect ExpressReports and ExpressDashboards to PostgreSQL, MySQL, Oracle, and Firebird databases. These engines require corresponding database provider assemblies within the dotnet_libraries folder of the app executable repository.

Refer to the following help topic for a complete list of supported database engines, corresponding provider assemblies, connection string examples, and related instructions: VCL Reports/Dashboards: Supported Database Systems.

Main API Members

The list below outlines key members of the TdxBackendDatabaseSQLConnection class. These members allow you to configure data connection strings.

Data Connection Management

Active

Specifies if the data connection is active. Enable this property to connect the component to a SQL database using the current connection string.

DefaultEnableCustomSql

Specifies if custom SQL queries are enabled for TdxDashboard/TdxDashboardControl and TdxReport components at the application level.

Important

Enable custom SQL queries only if you ensure that you follow best practices and implement user read/write privileges at the database level using the tools available for your relational database management system.

DisplayName

Specifies the data connection’s name in both designer and Collection Editor dialogs.

ConnectionString

Specifies a connection string for one of the following supported database engines:

SQLite | Microsoft SQL Server/Azure SQL | PostgreSQL | Oracle Database | MySQL | Firebird

General-Purpose API Members

Collection | Index

Specify the parent collection component.

Code Examples: Connection Strings

The following code examples demonstrate OnClick handlers that configure a TdxBackendDatabaseSQLConnection component to access different relational databases and to display the Dashboard Designer dialog:

SQLite

Delphi

uses
  dxDashboard.Control,             // Declares the TdxDashboardControl component
  dxBackend.ConnectionString.SQL;  // Declares the TdxBackendDatabaseSQLConnection component
// ...

procedure TMyForm.cxDisplayDesignerButtonClick(Sender: TObject);
begin
  dxBackendDatabaseSQLConnection1.Active := False;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1.DisplayName := 'SQLite Database Connection';
  dxBackendDatabaseSQLConnection1.ConnectionString :=

    'XpoProvider=SQLite;' +                         // Specifies the database engine type
    'Data Source=C:\Users\Public\Documents\DevExpress VCL Demos\MegaDemos\' +
    'Product Demos\ExpressReports\Data\devav.sqlite3';

  dxBackendDatabaseSQLConnection1.Active := True;   // Connects to the "devav.sqlite3" database
  dxDashboardControl1.ShowDesigner;                 // Displays the "Dashboard Designer" dialog
end;

C++

#include "dxDashboard.Control.hpp"             // Declares the TdxDashboardControl component
#include "dxBackend.ConnectionString.SQL.hpp"  // Declares the TdxBackendDatabaseSQLConnection component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"             // Required to use dxDashboard.Control.hpp declarations
#if defined(_WIN64)  // Required to use dxBackend.ConnectionString.SQL.hpp declarations
  #pragma link "dxBackend.ConnectionString.SQL.o"
#else
  #pragma link "dxBackend.ConnectionString.SQL.obj"
#endif
// ...

void __fastcall TMyForm::cxDisplayDesignerButtonClick(TObject *Sender)
{
  dxBackendDatabaseSQLConnection1->Active = false;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1->DisplayName = "SQLite Database Connection";
  dxBackendDatabaseSQLConnection1->ConnectionString =

    L"XpoProvider=SQLite;"                         // Specifies the database engine type
    L"Data Source=C:\\Users\\Public\\Documents\\DevExpress VCL Demos\\MegaDemos\\"
    L"Product Demos\\ExpressReports\\Data\\devav.sqlite3";

  dxBackendDatabaseSQLConnection1->Active = true;  // Connects to the "devav.sqlite3" database
  dxDashboardControl1->ShowDesigner();             // Displays the "Dashboard Designer" dialog
}

Microsoft SQL Server

Delphi

uses
  dxDashboard.Control,             // Declares the TdxDashboardControl component
  dxBackend.ConnectionString.SQL;  // Declares the TdxBackendDatabaseSQLConnection component
// ...

procedure TMyForm.cxDisplayDesignerButtonClick(Sender: TObject);
begin
  dxBackendDatabaseSQLConnection1.Active := False;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1.DisplayName := 'Microsoft SQL Server Database Connection';
  dxBackendDatabaseSQLConnection1.ConnectionString :=

   'XpoProvider=MSSqlServer;' +   // Specifies the database engine type
   'Data Source=(local);' +       // Specifies the database host
   'User ID=username;' +          // Specifies a valid user name
   'Password=password;' +         // Specifies the corresponding password for the user name
   'Initial Catalog=database;' +  // Specifies the initial catalog for the target database
   'Persist Security Info=true';  // Enables the "Persist Security Info" flag

  dxBackendDatabaseSQLConnection1.Active := True;   // Connects to the test database
  dxDashboardControl1.ShowDesigner;                 // Displays the "Dashboard Designer" dialog
end;

C++

#include "dxDashboard.Control.hpp"             // Declares the TdxDashboardControl component
#include "dxBackend.ConnectionString.SQL.hpp"  // Declares the TdxBackendDatabaseSQLConnection component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"             // Required to use dxDashboard.Control.hpp declarations
#if defined(_WIN64)  // Required to use dxBackend.ConnectionString.SQL.hpp declarations
  #pragma link "dxBackend.ConnectionString.SQL.o"
#else
  #pragma link "dxBackend.ConnectionString.SQL.obj"
#endif
// ...

void __fastcall TMyForm::cxDisplayDesignerButtonClick(TObject *Sender)
{
  dxBackendDatabaseSQLConnection1->Active = false; // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1->DisplayName = "Microsoft SQL Server Database Connection";
  dxBackendDatabaseSQLConnection1->ConnectionString =

    L"XpoProvider=MSSqlServer;"     // Specifies the database engine type
    L"Data Source=(local);"         // Specifies the database host
    L"User ID=username;"            // Specifies a valid user name
    L"Password=password;"           // Specifies the corresponding password for the user name
    L"Initial Catalog=database;"    // Specifies the initial catalog for the target database
    L"Persist Security Info=true;"  // Enables the "Persist Security Info" flag

  dxBackendDatabaseSQLConnection1->Active = true;  // Connects to the test database
  dxDashboardControl1->ShowDesigner();             // Displays the "Dashboard Designer" dialog
}

Microsoft SQL Azure

Delphi

uses
  dxDashboard.Control,             // Declares the TdxDashboardControl component
  dxBackend.ConnectionString.SQL;  // Declares the TdxBackendDatabaseSQLConnection component
// ...

procedure TMyForm.cxDisplayDesignerButtonClick(Sender: TObject);
begin
  dxBackendDatabaseSQLConnection1.Active := False;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1.DisplayName := 'Microsoft Azure SQL Database Connection';
  dxBackendDatabaseSQLConnection1.ConnectionString :=

    'XpoProvider=MSSqlServer;' +         // Specifies the database engine type
    'Data Source=tcp:YourServerName.database.windows.net;' +  // Specifies the database host
    'User Id=azureuser;' +               // Specifies a valid user name
    'Password=password;' +               // Specifies the corresponding password for the user name
    'Initial Catalog=DXApplication384';  // Specifies the initial catalog for the target database

  dxBackendDatabaseSQLConnection1.Active := True;   // Connects to the test database
  dxDashboardControl1.ShowDesigner;                 // Displays the "Dashboard Designer" dialog
end;

C++

#include "dxDashboard.Control.hpp"             // Declares the TdxDashboardControl component
#include "dxBackend.ConnectionString.SQL.hpp"  // Declares the TdxBackendDatabaseSQLConnection component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"             // Required to use dxDashboard.Control.hpp declarations
#if defined(_WIN64)  // Required to use dxBackend.ConnectionString.SQL.hpp declarations
  #pragma link "dxBackend.ConnectionString.SQL.o"
#else
  #pragma link "dxBackend.ConnectionString.SQL.obj"
#endif
// ...

void __fastcall TMyForm::cxDisplayDesignerButtonClick(TObject *Sender)
{
  dxBackendDatabaseSQLConnection1->Active = false; // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1->DisplayName = "Microsoft Azure SQL Database Connection";
  dxBackendDatabaseSQLConnection1->ConnectionString =

    L"XpoProvider=MSSqlServer;"           // Specifies the database engine type
    L"Data Source=tcp:YourServerName.database.windows.net;" // Specifies the database host
    L"User Id=azureuser;"                 // Specifies a valid user name
    L"Password=password;"                 // Specifies the corresponding password for the user name
    L"Initial Catalog=DXApplication384";  // Specifies the initial catalog for the target database

  dxBackendDatabaseSQLConnection1->Active = true;  // Connects to the test database
  dxDashboardControl1->ShowDesigner();             // Displays the "Dashboard Designer" dialog
}

MySQL

Delphi

uses
  dxDashboard.Control,             // Declares the TdxDashboardControl component
  dxBackend.ConnectionString.SQL;  // Declares the TdBackendDatabaseSQLConnection component
// ...

procedure TMyForm.cxDisplayDesignerButtonClick(Sender: TObject);
begin
  dxBackendDatabaseSQLConnection1.Active := False;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1.DisplayName := 'MySQL Database Connection';
  dxBackendDatabaseSQLConnection1.ConnectionString :=

    'XpoProvider=MySql;' +                      // Specifies the database engine type
    'Server=127.0.0.1;' +                       // Specifies the database server host IP address
    'User ID=MyUserName;' +                     // Specifies a valid user name
    'Password=MyPassword;' +                    // Specifies the corresponding password for the user name
    'Database=MyDatabase;' +                    // Specifies the target database name
    'Persist Security Info=true;Charset=utf8';  // Specifies additional attributes

  dxBackendDatabaseSQLConnection1.Active := True; // Connects to the test database
  dxDashboardControl1.ShowDesigner;               // Displays the "Dashboard Designer" dialog
end;

C++

#include "dxDashboard.Control.hpp"             // Declares the TdxDashboardControl component
#include "dxBackend.ConnectionString.SQL.hpp"  // Declares the TdxBackendDatabaseSQLConnection component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"             // Required to use dxDashboard.Control.hpp declarations
#if defined(_WIN64)  // Required to use dxBackend.ConnectionString.SQL.hpp declarations
  #pragma link "dxBackend.ConnectionString.SQL.o"
#else
  #pragma link "dxBackend.ConnectionString.SQL.obj"
#endif
// ...

void __fastcall TMyForm::cxDisplayDesignerButtonClick(TObject *Sender)
{
  dxBackendDatabaseSQLConnection1->Active = false;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1->DisplayName = "Oracle Database Connection";
  dxBackendDatabaseSQLConnection1->ConnectionString =

    L"XpoProvider=MySql;"                        // Specifies the database engine type
    L"Server=127.0.0.1;"                         // Specifies the database server host IP address
    L"User ID=MyUserName;"                       // Specifies a valid user name
    L"Password=MyPassword;"                      // Specifies the corresponding password for the user name
    L"Database=MyDatabase;"                      // Specifies the target database name
    L"Persist Security Info=true;Charset=utf8";  // Specifies additional attributes

  dxBackendDatabaseSQLConnection1->Active = true;  // Connects to the test database
  dxDashboardControl1->ShowDesigner();             // Displays the "Dashboard Designer" dialog
}

Oracle

Delphi

uses
  dxDashboard.Control,             // Declares the TdxDashboardControl component
  dxBackend.ConnectionString.SQL;  // Declares the TdBackendDatabaseSQLConnection component
// ...

procedure TMyForm.cxDisplayDesignerButtonClick(Sender: TObject);
begin
  dxBackendDatabaseSQLConnection1.Active := False;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1.DisplayName := 'Oracle Database Connection';
  dxBackendDatabaseSQLConnection1.ConnectionString :=

    'XpoProvider=Oracle;' +  // Specifies the database engine type
    'Data Source=TORCL;' +   // Specifies the target database
    'User ID=MyUserName;' +  // Specifies a valid user name
    'Password=MyPassword';   // Specifies the corresponding password for the user name

  dxBackendDatabaseSQLConnection1.Active := True; // Connects to the test database
  dxDashboardControl1.ShowDesigner;               // Displays the "Dashboard Designer" dialog
end;

C++

#include "dxDashboard.Control.hpp"             // Declares the TdxDashboardControl component
#include "dxBackend.ConnectionString.SQL.hpp"  // Declares the TdxBackendDatabaseSQLConnection component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"             // Required to use dxDashboard.Control.hpp declarations
#if defined(_WIN64)  // Required to use dxBackend.ConnectionString.SQL.hpp declarations
  #pragma link "dxBackend.ConnectionString.SQL.o"
#else
  #pragma link "dxBackend.ConnectionString.SQL.obj"
#endif
// ...

void __fastcall TMyForm::cxDisplayDesignerButtonClick(TObject *Sender)
{
  dxBackendDatabaseSQLConnection1->Active = false;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1->DisplayName = "Oracle Database Connection";
  dxBackendDatabaseSQLConnection1->ConnectionString =

    L"XpoProvider=Oracle;"    // Specifies the database engine type
    L"Data Source=TORCL;"     // Specifies the target database
    L"User ID=MyUserName;"    // Specifies a valid user name
    L"Password=MyPassword";   // Specifies the corresponding password for the user name

  dxBackendDatabaseSQLConnection1->Active = true;  // Connects to the test database
  dxDashboardControl1->ShowDesigner();             // Displays the "Dashboard Designer" dialog
}

PostgreSQL

Delphi

uses
  dxDashboard.Control,             // Declares the TdxDashboardControl component
  dxBackend.ConnectionString.SQL;  // Declares the TdxBackendDatabaseSQLConnection component
// ...

procedure TMyForm.cxDisplayDesignerButtonClick(Sender: TObject);
begin
  dxBackendDatabaseSQLConnection1.Active := False;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1.DisplayName := 'PostgreSQL Database Connection';
  dxBackendDatabaseSQLConnection1.ConnectionString :=

    'XpoProvider=Postgres;' +     // Specifies the database engine type
    'Server=127.0.0.1;' +         // Specifies the database host IP address
    'User ID=myuser;' +           // Specifies a valid user name
    'Password=123;' +             // Specifies the corresponding password for the user name
    'Database=dashboard_test;' +  // Specifies the target database name
    'Encoding=UNICODE';           // Sets UTF-8 as the required encoding

  dxBackendDatabaseSQLConnection1.Active := True;   // Connects to the test database
  dxDashboardControl1.ShowDesigner;                 // Displays the "Dashboard Designer" dialog
end;

C++

#include "dxDashboard.Control.hpp"             // Declares the TdxDashboardControl component
#include "dxBackend.ConnectionString.SQL.hpp"  // Declares the TdxBackendDatabaseSQLConnection component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"             // Required to use dxDashboard.Control.hpp declarations
#if defined(_WIN64)  // Required to use dxBackend.ConnectionString.SQL.hpp declarations
  #pragma link "dxBackend.ConnectionString.SQL.o"
#else
  #pragma link "dxBackend.ConnectionString.SQL.obj"
#endif
// ...

void __fastcall TMyForm::cxDisplayDesignerButtonClick(TObject *Sender)
{
  dxBackendDatabaseSQLConnection1->Active = false; // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1->DisplayName = "PostgreSQL Database Connection";
  dxBackendDatabaseSQLConnection1->ConnectionString =

    L"XpoProvider=Postgres;"     // Specifies the database engine type
    L"Server=127.0.0.1;"         // Specifies the database host IP address
    L"User ID=myuser;"           // Specifies a valid user name
    L"Password=123;"             // Specifies the corresponding password for the user name
    L"Database=dashboard_test;"  // Specifies the target database name
    L"Encoding=UNICODE";         // Sets UTF-8 as the required encoding

  dxBackendDatabaseSQLConnection1->Active = true;   // Connects to the test database
  dxDashboardControl1->ShowDesigner();              // Displays the "Dashboard Designer" dialog
}

Firebird

Delphi

uses
  dxDashboard.Control,             // Declares the TdxDashboardControl component
  dxBackend.ConnectionString.SQL;  // Declares the TdxBackendDatabaseSQLConnection component
// ...

procedure TMyForm.cxDisplayDesignerButtonClick(Sender: TObject);
begin
  dxBackendDatabaseSQLConnection1.Active := False;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1.DisplayName := 'Firebird Database Connection';
  dxBackendDatabaseSQLConnection1.ConnectionString :=

    'XpoProvider=Firebird;' +     // Specifies the database engine type
    'Datasource=localhost;' +     // Specifies the database location (IP 127.0.0.1)
    'User=SYSDBA;' +              // Specifies a valid user name
    'Password=password;' +        // Specifies the corresponding password for the user names
    'Database=C:\Program Files\Firebird\Firebird_5_0\examples\empbuild\EMPLOYEE.FDB;' +
    'ServerType=0;Charset=NONE';  // Specifies additional parameters

  dxBackendDatabaseSQLConnection1.Active := True;   // Connects to the EMPLOYEE.FDB database
  dxDashboardControl1.ShowDesigner;                 // Displays the "Dashboard Designer" dialog
end;

C++

#include "dxDashboard.Control.hpp"             // Declares the TdxDashboardControl component
#include "dxBackend.ConnectionString.SQL.hpp"  // Declares the TdxBackendDatabaseSQLConnection component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"             // Required to use dxDashboard.Control.hpp declarations
#if defined(_WIN64) // Required to use dxBackend.ConnectionString.SQL.hpp declarations
  #pragma link "dxBackend.ConnectionString.SQL.o"
#else
  #pragma link "dxBackend.ConnectionString.SQL.obj"
#endif
// ...

void __fastcall TMyForm::cxDisplayDesignerButtonClick(TObject *Sender)
{
  dxBackendDatabaseSQLConnection1->Active = false;  // Terminates the current connection (if one exists)
  // Specify a user-friendly data connection name (for end-user dialogs) and a valid connection string:
  dxBackendDatabaseSQLConnection1->DisplayName = "Firebird Database Connection";
  dxBackendDatabaseSQLConnection1->ConnectionString =

    L"XpoProvider=Firebird;"      // Specifies the database engine type
    L"Datasource=localhost;"      // Specifies the database location (IP 127.0.0.1)
    L"User=SYSDBA;"               // Specifies a valid user name
    L"Password=password;"         // Specifies the corresponding password for the user name
    L"Database=C:\\Program Files\\Firebird\\Firebird_5_0\\examples\\empbuild\\EMPLOYEE.FDB;"
    L"ServerType=0;Charset=NONE"; // Specifies additional parameters

  dxBackendDatabaseSQLConnection1->Active = true;  // Connects to the EMPLOYEE.FDB database
  dxDashboardControl1->ShowDesigner();             // Displays the "Dashboard Designer" dialog
}

Indirect TdxBackendDatabaseSQLConnection Class References

The following public API members reference the TdxBackendDatabaseSQLConnection class as a TdxBackendCustomDataConnection object:

TdxBackendDataConnectionCollection.Add

Creates a data connection of the required type and ads the connection to the collection.

TdxBackendDataConnectionCollection.Items

Provides indexed access to all data connection components stored in the collection.

TdxBackendDataConnectionManager.Items

Provides indexed access to stored data connection components.

Other Backend Data Connection Components

TdxBackendInMemoryJSONConnection

A component designed for interaction with data stored in memory.

TdxBackendDataSetJSONConnection

A component designed to fetch data from one or multiple datasets (TDataSet descendant instances).

Related Compiled Demos

To see TdxDashboardControl and TdxReport components in action, run BI Dashboards Designer/Viewer and Report Designer/Viewer demos in the VCL Demo Center installed with compiled DevExpress VCL demos. Click different items in the sidebar on the left to switch between demo features.

Download: Compiled VCL Demos

Tip

You can find full source code for installed compiled Report and Dashboard demos in the following folders:

• %PUBLIC%\Documents\DevExpress VCL Demos\MegaDemos\Product Demos\ExpressReports\
• %PUBLIC%\Documents\DevExpress VCL Demos\MegaDemos\Product Demos\ExpressDashboards\

Inheritance

TObject

TPersistent

TComponent

TcxCustomComponent

TcxComponentCollectionItem

TdxBackendCustomDataConnection

TdxBackendDatabaseSQLConnection