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. With telemetry enabled, AIDB stores spans and log records in the aidb_otel schema. The viewer groups recorded activity into sessions, shows each step, and highlights governance decisions. No log pipeline, Hybrid Manager, or Loki is involved. See Understanding what the dashboard shows for the data the viewer uses.

This page is for the database administrator of the source database and the administrator of EDB Agent Governance.

Prerequisites

Before you register a database:

• Install and run the EDB Agent Governance viewer. See Installing.

• Install and configure EDB Postgres AI (aidb extension) 7.7.0 or later on the source database. See Installing AIDB and Configuring AIDB.

  • Add aidb to shared_preload_libraries.

  • Run CREATE EXTENSION aidb CASCADE in the database the agents use.

  • Don't use an earlier version. Earlier versions store telemetry in a different aidb_otel layout that the viewer doesn't read, and it reports them as Unsupported aidb_otel schema.

• Upgrade to aidb 7.9.0 or later to get these features, which the viewer can't offer on 7.7 and 7.8:

  • Governance evidence for each statement: the database objects it referenced and, when PostgreSQL refused the statement for lack of privileges, the Denial Class, Denial Message, and SQLSTATE of that refusal.

  • Source filtering: aidb marks the records it produces as internal, and the viewer shows only those, excluding telemetry ingested from outside. Records that existed before the upgrade are marked internal without being classified, so they stay visible but their origin isn't verified.

  On 7.7 and 7.8, the session page doesn't show the evidence fields. The viewer also shows everything in the database, and the audit report's provenance_note says the source of its records can't be verified.

• Allow network connectivity from the viewer's backend to the Postgres server. Source databases usually use private addresses, so the bff.aidbBlockPrivate chart value is false by default.

• Enable TLS on the Postgres server with a certificate valid for the host name in the connection string. Use sslmode=verify-ca or sslmode=verify-full in the connection string; the viewer accepts no other values.

• Get superuser access to the source database to run the one-time steps in Enabling telemetry on the source database and Creating the viewer role. The viewer itself never needs these 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 with read-only access to aidb_otel.traces and aidb_otel.logs. Add the catalog grants below if you use the Agents roster. Don't use a superuser, the aidb owner, or the role agents run as. The backend stores the connection string and any client certificate server-side. Grant only the access listed below.

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.