Objective
Validate connectivity before operators rely on the Data Source in Templates or Reports. For example, test after creating
production-postgres, after a password rotation, or before generating a monthly report that depends on a recently changed schema.
When to use
Use this task:
- immediately after adding an external Data Source.
- when checking an existing internal Data Source before using it in a Template or filter.
- after editing host, credentials, schema, or SSL settings.
- before generating Reports that depend on the connection.
- when no tables appear in the schema browser.
- when Report generation fails because of connection or schema errors.
Before you start
Confirm:
- the Data Source exists on the Data Sources page.
- the expected host, port, database name, username, schema, and SSL settings are configured.
- the database should be reachable from Reporter.
- the database user has permission to read the required tables.
A successful test confirms access at that moment. It does not guarantee future Reports will succeed if credentials, network rules, or database permissions change later.
Step by step
1
Open Data Sources
Go to Data Sources.
2
Find the connection
Locate the card for the Data Source you need to test.
3
Run the test
Click Test Connection.
4
Wait for the result
The status changes to Connecting while Reporter tests the connection.
5
Read the result
Reporter returns the connection outcome, a client-safe message, and the measured latency. A successful probe returns
connected. A failed probe returns failed.6
Retrieve the schema separately
After a successful probe, use the separate schema operation to retrieve schemas, tables, and fields.
Field guide
Test action and result fields
Schema fields available separately
Expected result
Reporter returned
connected for the probe. Retrieve the schema separately before using its fields in Template Builder and report filters.
Common errors and care points
Connection succeeds but no tables appear
Connection succeeds but no tables appear
Check schema names and database permissions. The database user may connect but not have access to the tables needed for reporting.
Connection fails after editing credentials
Connection fails after editing credentials
Reopen the Data Source and confirm username, password, host, port, and SSL settings.
Testing once and assuming it stays valid
Testing once and assuming it stays valid
Network rules, rotated passwords, and database permissions can change. Re-test when generation errors appear.
Next steps
- Use Template Builder after schemas and fields are visible.
- Use Generate a Report after the Data Source is healthy.
- Use Edit a Data Source if the test fails because settings are wrong.