Storage

In-memory storage for development, PostgreSQL for production. Swap without code changes.

The SDK ships with two storage backends: in-memory (default) for development and PostgreSQL for production. Both implement the same interface, so you can swap between them without changing any application code.

In-Memory Storage (Default)

import { createGovernance } from 'governance-sdk';

// In-memory storage is the default — no configuration needed
const gov = createGovernance({
  rules: [...],
});

// Agents and audit events are stored in process memory.
// Fast for development, tests, and single-process deployments.
// Data is lost on process restart.

Good for: Local development, unit and integration tests, single-process deployments, quick prototyping.

Not for: Production with multiple processes, data that must survive restarts, regulatory audit requirements, high-volume event logging.

PostgreSQL Storage

For production, use the PostgreSQL adapter. It persists agents and audit events to your database with automatic table creation.

import { createGovernance } from 'governance-sdk';
import { createPostgresStorage } from 'governance-sdk/storage-postgres';
import { Pool } from 'pg';

// Create a PostgreSQL-backed storage adapter
const storage = await createPostgresStorage({
  pool: new Pool({
    connectionString: process.env.DATABASE_URL,
  }),
  autoMigrate: true,  // CREATE TABLE IF NOT EXISTS on first use (default: true)
});

// Pass it to createGovernance — same API, persistent storage
const gov = createGovernance({
  rules: [...],
  storage,
});

// When shutting down, close the pool
await storage.close();

Note: The pg package is a peer dependency — it is not bundled with the SDK. Install it separately: npm install pg.

Auto-Migration

By default, autoMigrate: true runs CREATE TABLE IF NOT EXISTS on the first storage operation. Tables are only created if they don't already exist.

// Disable auto-migration if you want explicit control
const storage = await createPostgresStorage({
  pool,
  autoMigrate: false,
});

// Run migration manually (e.g., during deployment)
await storage.migrate();

// Now storage is ready
const gov = createGovernance({ rules: [...], storage });

Warning: Auto-migration has no schema versioning. It only creates tables — it does not run ALTER TABLE for schema changes. If the SDK schema evolves between versions, you must drop and recreate the tables or manage migrations externally.

Database Tables

The PostgreSQL adapter creates two tables. The default prefix is lua_gov.

`{prefix}_agents`

Registered agents with metadata, scores, and governance levels.

Columns: id, name, framework, owner, description, version, channels, tools, permissions, metadata, composite_score, governance_level, status, registered_at, updated_at

`{prefix}_audit_events`

Enforcement decisions, custom events, kill switch events, all audit log entries.

Columns: id, agent_id, event_type, outcome, severity, detail, policy_rule_id, created_at

Multi-Tenant with Table Prefix

Use the tablePrefix option to isolate tenants in a shared database. Each prefix gets its own set of tables.

// Multi-tenant: use table prefix to isolate tenants in the same database
const storageOrgA = await createPostgresStorage({
  pool: sharedPool,
  tablePrefix: 'org_a_gov',  // Tables: org_a_gov_agents, org_a_gov_audit_events
});

const storageOrgB = await createPostgresStorage({
  pool: sharedPool,
  tablePrefix: 'org_b_gov',  // Tables: org_b_gov_agents, org_b_gov_audit_events
});

// Each org gets completely isolated agent and audit data
const govA = createGovernance({ rules: [...], storage: storageOrgA });
const govB = createGovernance({ rules: [...], storage: storageOrgB });

Tip: For full multi-tenant governance with RBAC, org management, and cross-tenant analytics, see the Enterprise package.

PgPoolLike Interface

The adapter accepts any object that implements the PgPoolLike interface. You are not locked into the pg package.

interface PgPoolLike {
  query<R = Record<string, unknown>>(
    text: string,
    values?: unknown[],
  ): Promise<{ rows: R[]; rowCount: number | null }>;
  end(): Promise<void>;
}

// Works with: pg.Pool, @neondatabase/serverless, @vercel/postgres,
// drizzle raw pools, or any custom wrapper that implements query() + end().