sentryagent-idp/docs/devops/database.md

Database

AgentIdP uses PostgreSQL 14+ as its primary data store. The schema consists of four tables managed by a custom migration runner.

---

Schema Overview

agents
  └── credentials (FK: client_id → agents.agent_id, CASCADE DELETE)

audit_events (no FK — append-only, agent_id is informational)

token_revocations (no FK — independent revocation store)

---

Tables

agents

The Agent Registry. One row per registered AI agent identity.

Column	Type	Nullable	Description
agent_id	UUID	No	Primary key — system-assigned, immutable
email	VARCHAR(255)	No	Unique email-format identifier
agent_type	VARCHAR(32)	No	Enum: screener, classifier, orchestrator, extractor, summarizer, router, monitor, custom
version	VARCHAR(64)	No	Semantic version string
capabilities	TEXT[]	No	Array of resource:action strings
owner	VARCHAR(128)	No	Owning team or organisation
deployment_env	VARCHAR(16)	No	Enum: development, staging, production
status	VARCHAR(24)	No	Enum: active, suspended, decommissioned. Default: active
created_at	TIMESTAMPTZ	No	Registration timestamp. Default: NOW()
updated_at	TIMESTAMPTZ	No	Last update timestamp. Default: NOW()

Indexes:

Index	Column	Purpose
idx_agents_email	email	Unique lookup on registration and conflict check
idx_agents_status	status	Filter by lifecycle status
idx_agents_owner	owner	Filter by owner
idx_agents_agent_type	agent_type	Filter by type
idx_agents_created_at	created_at DESC	Default sort for list queries

Constraints:

• email is UNIQUE — one registration per email address
• agent_type and deployment_env and status have CHECK constraints enforcing the enum values

---

credentials

OAuth 2.0 client credentials. One agent can have multiple credentials.

Column	Type	Nullable	Description
credential_id	UUID	No	Primary key — system-assigned
client_id	UUID	No	FK → agents.agent_id (CASCADE DELETE)
secret_hash	VARCHAR(255)	No	bcrypt hash of the client secret. Plaintext is never stored.
status	VARCHAR(16)	No	Enum: active, revoked. Default: active
created_at	TIMESTAMPTZ	No	Creation timestamp
expires_at	TIMESTAMPTZ	Yes	Optional expiry. NULL = no expiry.
revoked_at	TIMESTAMPTZ	Yes	Revocation timestamp. NULL = not revoked.

Indexes:

Index	Column	Purpose
idx_credentials_client_id	client_id	List credentials for an agent
idx_credentials_status	status	Filter active/revoked
idx_credentials_created_at	created_at DESC	Default sort

Cascade behaviour: Deleting an agent record cascades and deletes all associated credentials. In practice, agents are soft-deleted (status → decommissioned) not hard-deleted, so this cascade is a safety net.

---

audit_events

Immutable audit log. Append-only by design — no application-layer UPDATE or DELETE is ever issued against this table.

Column	Type	Nullable	Description
event_id	UUID	No	Primary key — system-assigned
agent_id	UUID	No	Agent that triggered the event (informational, no FK)
action	VARCHAR(32)	No	Enum — see values below
outcome	VARCHAR(16)	No	Enum: success, failure
ip_address	VARCHAR(64)	No	Client IP address (IPv4 or IPv6)
user_agent	TEXT	No	HTTP User-Agent from the request
metadata	JSONB	No	Action-specific data. Default: {}
timestamp	TIMESTAMPTZ	No	Event timestamp. Default: NOW()

action enum values: agent.created, agent.updated, agent.decommissioned, agent.suspended, agent.reactivated, token.issued, token.revoked, token.introspected, credential.generated, credential.rotated, credential.revoked, auth.failed

Indexes:

Index	Column	Purpose
idx_audit_events_agent_id	agent_id	Filter events by agent
idx_audit_events_action	action	Filter by action type
idx_audit_events_outcome	outcome	Filter successes/failures
idx_audit_events_timestamp	timestamp DESC	Default sort, date range queries

Why no FK on agent_id? Audit records must be retained even after an agent is decommissioned. A FK would prevent decommission or cascade-delete history. The agent_id is stored as an informational reference only.

Free tier retention: The application enforces a 90-day retention window at the query layer. Purging old records is not yet automated — it is a Phase 2 task.

---

token_revocations

Durable record of revoked JWT tokens. Supplements Redis for durability across Redis restarts.

Column	Type	Nullable	Description
jti	UUID	No	Primary key — the JWT ID claim from the revoked token
expires_at	TIMESTAMPTZ	No	When the token would have expired naturally
revoked_at	TIMESTAMPTZ	No	When the token was revoked. Default: NOW()

Indexes:

Index	Column	Purpose
idx_token_revocations_expires_at	expires_at	Enables future cleanup of expired revocation records

Dual-store design: When a token is revoked, the jti is written to both:

1. Redis key revoked:<jti> with TTL set to the token's remaining lifetime — fast O(1) lookup on every authenticated request
2. This PostgreSQL table — durable record if Redis is restarted

Note: On Redis restart, the in-memory revocation cache is cold. Tokens revoked before the restart will pass auth until Phase 2 implements a warm-up that loads active revocations from PostgreSQL into Redis on startup.

---

Migration Runner

Migrations are managed by scripts/migrate.ts. It reads .sql files from src/db/migrations/ in alphabetical order, tracks applied migrations in a schema_migrations table, and executes only unapplied migrations — each in its own transaction.

schema_migrations table

Created automatically on first run if it does not exist.

Column	Type	Description
name	VARCHAR(255)	Migration filename (primary key)
applied_at	TIMESTAMPTZ	When the migration was applied

Running migrations

# Set DATABASE_URL in environment or .env first
npm run db:migrate

Expected output (first run):

Running database migrations...
  ✓ Applied: 001_create_agents.sql
  ✓ Applied: 002_create_credentials.sql
  ✓ Applied: 003_create_audit_events.sql
  ✓ Applied: 004_create_tokens.sql

Migrations complete. 4 migration(s) applied.

Expected output (already applied):

Running database migrations...
  - Skipped (already applied): 001_create_agents.sql
  - Skipped (already applied): 002_create_credentials.sql
  - Skipped (already applied): 003_create_audit_events.sql
  - Skipped (already applied): 004_create_tokens.sql

Migrations complete. 0 migration(s) applied.

Verifying applied migrations

psql "$DATABASE_URL" -c "SELECT name, applied_at FROM schema_migrations ORDER BY name;"

Expected output:

               name                |          applied_at
-----------------------------------+-------------------------------
 001_create_agents.sql             | 2026-03-28 09:00:00.000000+00
 002_create_credentials.sql        | 2026-03-28 09:00:00.000000+00
 003_create_audit_events.sql       | 2026-03-28 09:00:00.000000+00
 004_create_tokens.sql             | 2026-03-28 09:00:00.000000+00
(4 rows)

Adding a new migration

1. Create a new .sql file in src/db/migrations/ with the next numeric prefix (e.g. 005_add_column.sql)
2. Write idempotent SQL using IF NOT EXISTS / IF EXISTS guards where possible
3. Run npm run db:migrate

Migrations are run in alphabetical filename order. The prefix ensures correct ordering.

Rollback

There is no automated rollback. To undo a migration:

1. Write and apply a compensating migration (e.g. 005_rollback_add_column.sql)
2. Or connect directly to PostgreSQL and run the reverse SQL manually

---

Connection Pool

The application uses pg.Pool with default settings (max 10 connections). The pool is a singleton — one pool per process instance.

To override pool size, modify src/db/pool.ts. In production, ensure DATABASE_URL includes connection pool parameters if using PgBouncer or a managed connection pooler.