Setup Connection
The first step in configuring the SQL Database Reader is providing the connection credentials for your database. The plugin uses these credentials every time it executes a query.
Navigate to Actions → Plugins in the agent sidebar, open the SQL Database Reader plugin, and go to the Connection section.
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. |
| User | The database username used for authentication. |
| Password | The password for the database user. Stored encrypted and never returned in API responses. |
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. |
| 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.
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.