Datasources

A datasource is a connection the agent can query. Reporting supports four relational databases and flat files.

Type	Driver	Notes
oracle	oracledb	Thin mode by default; thick mode for 11g and older
postgres	pg	SSL supported
mysql	mysql2	MySQL and MariaDB
mssql	tedious	SQL Server
file	DuckDB	CSV and TSV

The split between control plane and agent

Every datasource is defined twice, and this is deliberate:

• In the webapp, you create the datasource and give it a slug — plus the non-secret shape of the connection so the UI can describe it.
• In config/agent.yaml on the agent host, you supply the same slug with the real host, port, user, and password.

The slug is the join. Credentials never travel to the control plane.

Configuration by type

Oracle

Oracle accepts three connection forms. Use whichever matches your environment.

datasources:
  # By service name
  production-erp:
    type: oracle
    host: 10.0.1.50
    port: 1521
    serviceName: ERPDB.example.com
    user: report_reader
    password: ${ORACLE_PASS}

  # By SID
  legacy-erp:
    type: oracle
    host: 10.0.1.51
    port: 1521
    sid: ERPDB
    user: report_reader
    password: ${ORACLE_PASS}

  # By full connect string
  rac-cluster:
    type: oracle
    connectString: "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=10.0.1.50)(PORT=1521))(CONNECT_DATA=(SID=ERPDB)))"
    user: report_reader
    password: ${ORACLE_PASS}

Older Oracle servers (11g and earlier) need thick mode and the Oracle Instant Client:

    thickMode: true
    clientLibDir: /opt/oracle/instantclient_21_3
    # clientLibDir: C:\oracle\instantclient_21_3   # Windows

PostgreSQL

  analytics-pg:
    type: postgres
    host: 10.0.2.100
    port: 5432
    database: analytics
    user: readonly
    password: ${PG_ANALYTICS_PASS}
    ssl: true
    pool:
      min: 1
      max: 5
      queryTimeout: 120000

MySQL and SQL Server

  billing-mysql:
    type: mysql
    host: 10.0.3.10
    port: 3306
    database: billing
    user: report_reader
    password: ${MYSQL_PASS}

  warehouse-mssql:
    type: mssql
    host: 10.0.4.20
    port: 1433
    database: warehouse
    user: report_reader
    password: ${MSSQL_PASS}

File sources

CSV and TSV files are queried with DuckDB, so you can write ordinary SQL against a flat file.

  monthly-transactions:
    type: file
    path: /data/exports/transactions.csv
    delimiter: auto     # or an explicit character
    header: auto
    cache: false
    watch: true         # re-read when the file changes on disk

Connection pooling

Each datasource gets its own pool. Tune it to what the database will tolerate, not to what the agent wants:

    pool:
      min: 1              # idle connections held open
      max: 5              # ceiling on concurrent queries
      queryTimeout: 120000 # milliseconds; kill runaway queries

Pools self-heal — a connection that fails is discarded and re-established with backoff rather than poisoning the pool. Live pool status for every datasource is shown in Reporting → Datasources so you can see saturation before a schedule starts failing.

Testing and schema discovery

Test connection asks the agent to open a connection and report back. A failure returns the driver's own error, which is usually enough to diagnose it.

Discover schema reads table and column metadata and sends the structure back to the control plane. Only names and types travel — never row data. This is what powers autocomplete in the SQL editor and column pickers in the report builder.

Re-run discovery after schema changes; it is safe to run any time.

Permissions

Give the agent a dedicated read-only user per datasource. The agent only issues SELECT, and a read-only grant turns that from a promise into a constraint. Scope it to the schemas that reports actually need.