Multi-Database Setup

Configure the Basira agent to monitor multiple databases from a single process using YAML configuration.

The Basira agent can monitor multiple databases — PostgreSQL, ClickHouse, or a mix — from a single process. This guide covers the YAML config format and deployment options.

Configuration Modes

The agent supports two configuration modes:

Mode	Trigger	Use case
Environment variables	`BASIRA_CONFIG` not set	Single database (backwards compatible)
YAML config file	`BASIRA_CONFIG=/path/to/config.yaml`	Multiple databases

When BASIRA_CONFIG is set, the agent reads all configuration from the YAML file. When unset, it falls back to individual environment variables for single-database monitoring.

YAML Config Format

api:
  endpoint: https://api.usebasira.com  # optional, defaults to http://localhost:8080
  key: dbm_ak_your_api_key            # required

databases:
  - name: primary-pg                   # optional, defaults to "db-0", "db-1", etc.
    engine: postgres                   # optional, auto-detected from DSN
    dsn: postgres://basira_monitor:password@pg-primary:5432/myapp?sslmode=require
    instance_id: clx1abc...            # required, from Basira dashboard
    poll_interval: 10s                 # optional, default 10s

  - name: analytics-ch
    dsn: clickhouse://basira_monitor:password@ch-analytics:9000/analytics
    instance_id: clx2def...
    poll_interval: 30s

Field Reference

`api` (required)

Field	Required	Default	Description
`endpoint`	No	`http://localhost:8080`	Basira API URL
`key`	Yes	—	API key from the dashboard

`databases[]` (at least one required)

Field	Required	Default	Description
`name`	No	`db-{index}`	Unique name for this database. Used in logs and buffer file names.
`engine`	No	Auto-detected from DSN	`postgres` or `clickhouse`
`dsn`	Yes	—	Connection string
`instance_id`	Yes	—	Database instance ID from the Basira dashboard
`poll_interval`	No	`10s`	How often to collect metrics (Go duration: `10s`, `1m`, etc.)

Engine auto-detection: DSNs starting with clickhouse:// or tcp:// are detected as ClickHouse. Everything else defaults to PostgreSQL.

Buffer files: Each database gets its own buffer at basira_buffer_{name}.db for resilient delivery.

Validation rules:

Database names must be unique
At least one database entry is required
dsn and instance_id are required per database

Examples

Multiple PostgreSQL Databases

api:
  endpoint: https://api.usebasira.com
  key: dbm_ak_prod_key

databases:
  - name: app-primary
    dsn: postgres://basira_monitor:pass@pg-primary:5432/app?sslmode=require
    instance_id: clx1abc000primary
    poll_interval: 10s

  - name: app-replica
    dsn: postgres://basira_monitor:pass@pg-replica:5432/app?sslmode=require
    instance_id: clx1abc000replica
    poll_interval: 10s

  - name: auth-db
    dsn: postgres://basira_monitor:pass@pg-auth:5432/auth?sslmode=require
    instance_id: clx1abc000auth
    poll_interval: 15s

Multiple ClickHouse Databases

api:
  endpoint: https://api.usebasira.com
  key: dbm_ak_prod_key

databases:
  - name: events-ch
    dsn: clickhouse://basira_monitor:pass@ch-events:9000/events
    instance_id: clx2def000events
    poll_interval: 30s

  - name: analytics-ch
    dsn: clickhouse://basira_monitor:pass@ch-analytics:9000/analytics
    instance_id: clx2def000analytics
    poll_interval: 30s

Mixed PostgreSQL + ClickHouse

api:
  endpoint: https://api.usebasira.com
  key: dbm_ak_prod_key

databases:
  - name: app-pg
    dsn: postgres://basira_monitor:pass@pg-primary:5432/app?sslmode=require
    instance_id: clx1abc000pg
    poll_interval: 10s

  - name: analytics-ch
    dsn: clickhouse://basira_monitor:pass@ch-analytics:9000/analytics
    instance_id: clx2def000ch
    poll_interval: 30s

Environment Variable Mode (Single Database)

For single-database setups, you can use environment variables without a YAML file:

Variable	Required	Default	Description
`BASIRA_DSN`	Yes	—	Database connection string
`BASIRA_API_KEY`	Yes	—	API key
`BASIRA_API_ENDPOINT`	No	`http://localhost:8080`	API URL
`BASIRA_DB_INSTANCE_ID`	No	—	Database instance ID
`BASIRA_POLL_INTERVAL`	No	`10s`	Collection interval
`BASIRA_AGENT_ID`	No	Hostname	Agent identifier
`BASIRA_BUFFER_PATH`	No	`basira_buffer.db`	Buffer file path
`BASIRA_ENGINE`	No	Auto-detected	`postgres` or `clickhouse`
`BASIRA_COLLECTORS`	No	All	Comma-separated collector list
`BASIRA_PG_LOG_DIR`	No	—	PostgreSQL log directory for slow query collection

Kubernetes Deployment

ConfigMap with YAML Config

Create a ConfigMap containing your agent configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: basira-agent-config
data:
  config.yaml: |
    api:
      endpoint: https://api.usebasira.com
      key: will-be-overridden  # placeholder, actual key from Secret
    databases:
      - name: app-pg
        dsn: will-be-overridden  # placeholder, actual DSN from Secret
        instance_id: clx1abc000pg
        poll_interval: 10s
      - name: analytics-ch
        dsn: will-be-overridden
        instance_id: clx2def000ch
        poll_interval: 30s

For production, store sensitive values (DSNs and API keys) in a Secret and mount them as environment variables or use a secrets manager. The YAML config file handles structure; override secrets at runtime.

Deployment with Config File

apiVersion: apps/v1
kind: Deployment
metadata:
  name: basira-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: basira-agent
  template:
    metadata:
      labels:
        app: basira-agent
    spec:
      containers:
        - name: agent
          image: ghcr.io/usebasira/basira-agent:latest
          env:
            - name: BASIRA_CONFIG
              value: /etc/basira/config.yaml
          volumeMounts:
            - name: config
              mountPath: /etc/basira
              readOnly: true
            - name: buffer
              mountPath: /data
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
              memory: 128Mi
      volumes:
        - name: config
          configMap:
            name: basira-agent-config
        - name: buffer
          emptyDir: {}

Helm (Single Database)

The Helm chart currently supports single-database mode via values.yaml:

apiKey: "dbm_ak_your_key"
apiEndpoint: "https://api.usebasira.com"
dsn: "postgres://basira_monitor:pass@pg-host:5432/mydb?sslmode=require"
dbInstanceID: "clx1abc000id"
pollInterval: "10s"
engine: ""  # auto-detect from DSN

helm install basira-agent oci://registry.basira.io/charts/basira-agent \
  -f values.yaml

For multi-database deployments with Helm, use the raw Kubernetes manifests above or install one Helm release per database.

Troubleshooting

Verify Databases Are Monitored

Check each database's status via the health endpoint:

# Replace {id} with your database instance ID
curl -s -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.usebasira.com/api/v1/databases/{id}/health | jq .

Response:

{
  "id": "clx1abc000pg",
  "status": "connected",
  "last_seen_at": "2026-03-14T12:00:00Z"
}

Status values:

connected — agent is actively sending heartbeats
pending — database registered but no agent connected yet
disconnected — agent heartbeat not received for >30 seconds
error — connection error

Common Issues

"at least one database entry is required" — Your YAML file has an empty databases list.

"duplicate name" — Two databases have the same name. Use unique names or omit the field to auto-generate.

"unsupported engine" — The engine field must be postgres or clickhouse. Remove it to auto-detect from the DSN.

Database shows "pending" — The agent hasn't connected yet. Check agent logs for connection errors and verify the DSN is reachable from the agent's network.

Database shows "disconnected" — The agent was connected but stopped sending heartbeats. Check agent pod logs and resource limits.

Multi-Database Setup

On this page