Setup Connection

Open in CMS

The 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 QlarStays on your network (gateway)
DatabaseDirect connection β€” Qlar connects to your databaseThrough your gateway β€” the gateway runs the queries next to your database
FilesUpload a workbook β€” Qlar keeps a copy of one .xlsxParquet on your server β€” the gateway queries a folder of Parquet files where it is
Direct connectionThrough your gatewayUpload a workbookParquet on your server
Database port reachable from QlarRequiredNot requiredNo databaseNo database
Credentials held by QlarYesNo β€” they stay on your machineNone neededNone needed
Data processedOn your databaseOn your databaseBy Qlar, on a copy of the fileOn your server, by the gateway
What you configure nextThe fields belowWhich gateway to useThe file to uploadWhich 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

ProviderKeyDefault Port
Microsoft SQL Serversqlserver1433
PostgreSQLpostgresql5432
MySQLmysql3306
Oracleoracle1521

Connection Fields

FieldDescription
ProviderThe type of database you are connecting to.
ServerHostname or IP address of the database server. Include the port if non-default, e.g. db.example.com:1433.
DatabaseThe name of the target database.
AuthenticationSQL Server only: SQL Login (the default) or Service Principal (Microsoft Entra ID). See Microsoft Entra ID service principal.
UserThe database username used for authentication. With a service principal this field is labelled Client ID.
PasswordThe 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).

FieldWhat to enter
ServerThe 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.
DatabaseThe warehouse, lakehouse or database name.
Client IDThe app registration's Application (client) ID. If the app lives in a different tenant from the database, enter clientId@tenantId.
Client SecretA 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 to db_datareader, or grant SELECT on 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

ErrorLikely cause
Connection timeoutFirewall is blocking the port or the server is unreachable from the plugin host.
Authentication failedUsername or password is incorrect.
ClientSecretCredential authentication failedThe client ID, tenant or client secret is wrong, or the secret has expired.
Login failed for the service principalThe app authenticated but has no access to that workspace or database yet.
Connection succeeds but no tables are listedThe 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 foundThe Database field does not match an existing database name on that server.
SSL/TLS errorThe 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.