Connecting an EDB Postgres AI database v1

Connect EDB Agent Governance to a Postgres database that runs the aidb extension so the viewer can read its AI agent telemetry directly. The extension records every agent call as OpenTelemetry spans in the aidb_otel schema, and the viewer groups those spans into sessions, shows each step, and highlights governance decisions. No log pipeline, Hybrid Manager, or Loki is involved.

This page is for the database administrator of the source database and the administrator of EDB Agent Governance. Complete Installing first; the viewer must be running before you register a database.

Prerequisites

Make sure you have the following before you register a database:

• EDB Postgres AI (aidb extension) 7.7.0 or later, installed and configured on the source database as described in Installing AIDB and Configuring AIDB: aidb in shared_preload_libraries and CREATE EXTENSION aidb CASCADE run in the database the agents use. Earlier versions store telemetry in a different aidb_otel layout, which the viewer doesn't read; it reports them as Unsupported aidb_otel schema.
• Network connectivity from the viewer's backend to the Postgres server. Source databases usually live on private addresses; the bff.aidbBlockPrivate chart value is false by default so that works out of the box.
• TLS on the Postgres server, with a certificate valid for the host name in the connection string. The viewer accepts only sslmode=verify-ca or sslmode=verify-full.
• A superuser to run the one-time provisioning below. The viewer itself never needs those rights.

Enabling telemetry on the source database

Set the aidb.otel_client parameter to database so that aidb writes spans. The default is noop, which writes nothing. The parameter is SUSET: a superuser, or a role granted SET on the parameter, can change it. Like the other aidb.* parameters, set it in postgresql.conf or with ALTER SYSTEM — no restart is required. The full list of OpenTelemetry parameters is in Configuring AIDB — OpenTelemetry tracing.

1. Turn on telemetry for the server:

   → WrapCopy

   ALTER SYSTEM SET aidb.otel_client = 'database';
   SELECT pg_reload_conf();

   To enable it for one database only, use ALTER DATABASE <db> SET aidb.otel_client = 'database'; instead.

2. Recycle the agent backends. The parameter is captured once per Postgres backend at its first instrumented call. Reconnect the applications that run agents, or recycle their connection pool, so new sessions pick up the value. Backends that were already running keep the old value.

Creating the viewer role

Create a dedicated login role that can only read the two telemetry tables for the viewer to connect with. Don't use a superuser, the aidb owner, or the role the agents run as. The connection string and any client certificate are stored server-side by the viewer's backend, so scope the credential to only what the viewer needs — if it's ever exposed, it should grant no more than read access to the telemetry tables.

Run this in the database the agents use, replacing <db> with its name. Set the password interactively with \password so it doesn't end up in a script or shell history:

CREATE ROLE governance_viewer LOGIN;
\password governance_viewer
GRANT CONNECT ON DATABASE <db> TO governance_viewer;
GRANT USAGE ON SCHEMA aidb_otel TO governance_viewer;
GRANT SELECT ON aidb_otel.traces, aidb_otel.logs TO governance_viewer;

Don't grant this role aidb_users, aidb_governance, write privileges, or administration rights. aidb_governance also allows retention cleanup and purpose management (see Managing audit access with the aidb_governance role), which is more than the viewer needs. If your database has extra grants to PUBLIC or inherited roles, review them too.

These grants are enough for the dashboard, Activity, session pages, and the Behavior tab. The Roster tab on the Agents page also reads the aidb agent catalog. To use it, grant read access to the columns it needs:

GRANT USAGE ON SCHEMA aidb TO governance_viewer;
GRANT SELECT (id, name, purpose, created_at) ON aidb.agents TO governance_viewer;
GRANT SELECT (name, role, deleted_at) ON aidb.purpose_registry TO governance_viewer;

Without these grants, the Roster tab shows Agent registry unavailable and everything else works. Without the aidb.purpose_registry grant, the roster lists agents but not their roles or permissions.

To check the role, connect as governance_viewer and run:

SELECT session_user, current_database();
SELECT id, recorded_at FROM aidb_otel.traces ORDER BY id DESC LIMIT 1;
SELECT id, recorded_at FROM aidb_otel.logs ORDER BY id DESC LIMIT 1;

An empty result is fine: it means no agent calls have been recorded yet, or retention has removed them. A permission error means a grant is missing.

A role that can read traces but not logs is accepted: sessions and steps appear, log records don't, and the instance's health status asks for SELECT on aidb_otel.logs. A role that can't read traces fails the health check.

Registering the database as an instance

Register the database on the Configure page, accessible from the home page's Configure Instances button or from Settings > Configure instance in the header.

1. Open the Configure Instances page.
2. Select Add New.
3. Complete the form:
   • Type — Postgres (aidb_otel).
   • Name — A descriptive label, for example Production aidb.
   • DSN — The connection string for the viewer role, for example postgres://governance_viewer:<password>@db.example.com:5432/<db>?sslmode=verify-full. sslmode must be verify-ca or verify-full; prefer verify-full, which also checks the host name. Only sslmode and application_name are accepted as query parameters. URL-encode special characters in the password.
   • CA certificate (PEM) — The CA chain that signed the Postgres server certificate. Paste the PEM contents or select Load from file. Leave it empty if the server certificate is signed by a publicly trusted CA; verify-ca always needs it. Use this field instead of sslrootcert or other file paths in the DSN.
   • Client certificate (PEM) and Client key (PEM) — Optional, for certificate authentication. Provide both or neither.
4. Select Add Instance.

The backend opens a read-only connection and checks the aidb_otel layout, columns, and privileges. The result appears above the instance list: Connection verified when everything is in place, otherwise a warning or error with the reason appears. To run the check again later, use the Verify the stored connection action on the instance row. Each database appears as one cluster on the home page; selecting it opens the cluster's Dashboard. Agent activity appears within seconds of the first agent call.

Credentials are encrypted at rest and never returned to the browser. To rotate them, update the password or certificates on the source database, then use the Edit connection credentials action on the instance row and enter the new values. Certificate fields left empty keep the stored certificates. Verify the connection again afterward.

Troubleshooting

Use this table to resolve the messages the viewer shows when it can't read an aidb database:

The same titles appear on the Activity and session pages when a query fails there, together with a hint and a Retry button.

Handling retention and missing data

Account for retention when you read results: the viewer shows only what is still in aidb_otel. If retention deletes part of a call, the remaining steps still appear, but the viewer doesn't reconstruct the deleted part. A call deleted completely no longer opens. Each session reads at most 1,000 traces, 5,000 spans, and 5,000 log records.