Setup Connection
Open in CMSThe first step in configuring the SQL Database Reader is deciding where Qlar reads your data from, and then giving it what it needs to do so.
Navigate to Tools β Plugins in the agent sidebar, open the SQL Database Reader plugin, and start at the Access step.
Choose your data source
The Access step asks two things at once: what your data is β a database or files β and where it is processed β reached or stored by Qlar, or kept on your own network by the on-premise gateway. That gives four cards in two groups:
| Reached or stored by Qlar | Stays on your network (gateway) | |
|---|---|---|
| Database | Direct connection β Qlar connects to your database | Through your gateway β the gateway runs the queries next to your database |
| Files | Upload a workbook β Qlar keeps a copy of one .xlsx | Parquet on your server β the gateway queries a folder of Parquet files where it is |
| Direct connection | Through your gateway | Upload a workbook | Parquet on your server | |
|---|---|---|---|---|
| Database port reachable from Qlar | Required | Not required | No database | No database |
| Credentials held by Qlar | Yes | No β they stay on your machine | None needed | None needed |
| Data processed | On your database | On your database | By Qlar, on a copy of the file | On your server, by the gateway |
| What you configure next | The fields below | Which gateway to use | The file to upload | Which gateway to use |
Pick Direct connection if your database can accept connections from Qlar and you are comfortable with Qlar holding the credentials. The rest of this page applies to you.
Pick Through your gateway if opening a database port or handing over credentials is not acceptable in your environment β see On-Premise Data Gateway. Everything after this step, from table selection onwards, is identical either way.
Pick Upload a workbook if the data lives in a spreadsheet rather than a database β see Excel File Source.
Pick Parquet on your server if the data is a folder of Parquet files that should not leave your network β see Parquet Files.
You can change the source later, but switching means setting the data source up again.
Supported Database Providers
| Provider | Key | Default Port |
|---|---|---|
| Microsoft SQL Server | sqlserver | 1433 |
| PostgreSQL | postgresql | 5432 |
| MySQL | mysql | 3306 |
| Oracle | oracle | 1521 |
Connection Fields
| Field | Description |
|---|---|
| Provider | The type of database you are connecting to. |
| Server | Hostname or IP address of the database server. Include the port if non-default, e.g. db.example.com:1433. |
| Database | The name of the target database. |
| Authentication | SQL Server only: SQL Login (the default) or Service Principal (Microsoft Entra ID). See Microsoft Entra ID service principal. |
| User | The database username used for authentication. With a service principal this field is labelled Client ID. |
| Password | The password for the database user. With a service principal this field is labelled Client Secret. Qlar stores it so the plugin can reconnect on its own. If credentials leaving your environment is not acceptable, use the on-premise gateway instead, where they never reach Qlar at all. |
Microsoft Entra ID service principal (SQL Server)
Azure SQL Database, Azure Synapse and Microsoft Fabric SQL endpoints (warehouse or lakehouse) can be read with a Microsoft Entra ID app registration instead of a SQL login. Choose SQL Server as the provider, then set Authentication to Service Principal (Microsoft Entra ID).
| Field | What to enter |
|---|---|
| Server | The SQL endpoint host, e.g. xxxx.datawarehouse.fabric.microsoft.com or myserver.database.windows.net. In Fabric, open the warehouse or the lakehouse's SQL analytics endpoint and use Copy SQL connection string. |
| Database | The warehouse, lakehouse or database name. |
| Client ID | The app registration's Application (client) ID. If the app lives in a different tenant from the database, enter clientId@tenantId. |
| Client Secret | A client secret value of that app registration. |
Signing in is not enough: the service principal also needs read access to the data, otherwise the connection test succeeds but no tables are listed. Grant it before testing:
- Microsoft Fabric β a workspace Admin either shares the warehouse or lakehouse with the app and ticks Read all SQL endpoint data, or adds the app to the workspace with the Viewer role. Sharing the single item is the narrower option.
- Azure SQL / Synapse β create a contained user from the external provider (
CREATE USER [app-name] FROM EXTERNAL PROVIDER) and add it todb_datareader, or grantSELECTon the schemas the agent needs.
The connection is always encrypted and validates the server certificate.
Fabric and Azure SQL often keep tables outside the dbo schema, so SQL Server tables are listed as schema.table, for example SLV.customer or GLD.dim_branch.
Service principal authentication is available for direct SQL Server connections only. PostgreSQL, MySQL and Oracle use a database user and password.
Testing the Connection
Before saving, click Test Connection. The plugin will attempt to open a connection and run a lightweight query to verify connectivity. The test has a 30-second timeout.
A successful test returns:
- Connected: Yes
- Response time: Milliseconds taken to connect
- Database version: The version string reported by the server
If the test fails, the response includes an error message to help you diagnose the problem.
Common test failures
| Error | Likely cause |
|---|---|
| Connection timeout | Firewall is blocking the port or the server is unreachable from the plugin host. |
| Authentication failed | Username or password is incorrect. |
ClientSecretCredential authentication failed | The client ID, tenant or client secret is wrong, or the secret has expired. |
| Login failed for the service principal | The app authenticated but has no access to that workspace or database yet. |
| Connection succeeds but no tables are listed | The service principal can sign in but cannot read the data. Grant read access as described in Microsoft Entra ID service principal, then load the tables again. |
| Database not found | The Database field does not match an existing database name on that server. |
| SSL/TLS error | The server requires certificate-based authentication. |
Loading Tables from the Connection
After a successful connection test, click Load Tables. The plugin reads the schema of the connected database and returns a list of all tables with their columns, data types, and constraints.
PostgreSQL and SQL Server tables are listed with their schema (schema.table), so same-named tables in different schemas stay apart.
What gets loaded per column:
- Column name and data type
- Nullable flag
- Whether the column is a primary key
- Foreign key relationships detected from database constraints
This step is required before you can proceed to configure tables and columns.
Security Notes
- Use a dedicated read-only database user. Never use an admin account.
- Restrict the database user's access to only the tables the agent needs.
- Where possible, configure the database server to accept connections only from the plugin host's IP address.
- If your security policy does not allow a database port to be reachable from outside your network, the on-premise gateway removes that requirement entirely.