PostgreSQL storage

PostgresStorage implements core’s StorageDriver using a PostgreSQL kv_store table. Use it for supported conversation, memory, or configuration records when you already operate PostgreSQL. It is a key/value driver, not the lease-based store for durable tasks or the pgvector search adapter.

Installation

Use an ESM TypeScript project ("type": "module" in package.json) on a supported Node version.

npm install @agentium/core@4.0.0 pg@8
npm install --save-dev tsx typescript @types/node

Supply a reachable database and a role allowed to create/use kv_store. These programs connect to that database when run; the documentation type check does not create tables.

Setup

Set DATABASE_URL through your host environment. Save as storage.ts:

import { PostgresStorage } from "@agentium/core";

const connectionString = process.env.DATABASE_URL;
if (!connectionString) throw new Error("Set DATABASE_URL");
const storage = new PostgresStorage(connectionString);
try {
  await storage.initialize();
  await storage.set("docs-demo", "check", { value: 42 });
  const value = await storage.get<{ value: number }>("docs-demo", "check");
  console.log(value);
  await storage.delete("docs-demo", "check");
} finally {
  await storage.close();
}

npx tsx storage.ts

Expect { value: 42 }. The example removes its one demo record; the initialized table remains. A missing-key read returns null. Resolve authentication, network, or table-permission errors before connecting an Agent.

Constructor

The constructor takes one connection-string argument:

import { PostgresStorage } from "@agentium/core";

export function createConversationStorage(connectionString: string) {
  return new PostgresStorage(connectionString);
}

Call initialize() before operations. The host owns the returned driver and calls close() after all consumers finish.

Full example

Add the openai optional dependency and set OPENAI_API_KEY for this live-model example. Use a session/user identity supplied by your trusted application boundary when adapting it to a server.

import { Agent, PostgresStorage, openai } from "@agentium/core";

const connectionString = process.env.DATABASE_URL;
if (!connectionString) throw new Error("Set DATABASE_URL");
const storage = new PostgresStorage(connectionString);
let agent: Agent | undefined;
try {
  await storage.initialize();
  agent = new Agent({
    name: "support",
    model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
    memory: { storage },
  });
  const result = await agent.run("My project is Atlas. Remember its name.", {
    userId: "demo-user",
    sessionId: "demo-session",
  });
  if (result.status !== "completed") throw new Error(`Run ended with ${result.status}`);
  console.log(result.text);
} finally {
  await agent?.close({ closeStorage: false });
  await storage.close();
}

The Agent closes its owned services; the host closes the shared driver exactly once. Continue with sessions for identity and history behavior. Admin blueprints and Agent history are different records even when they use the same database.

Schema

initialize() creates the table if absent:

Column	Type	Meaning
`namespace`	`TEXT`	Record category
`key`	`TEXT`	Key within the namespace
`value`	`JSONB`	JSON-serializable value
`updated_at`	`TIMESTAMPTZ`	Last write timestamp

The primary key is (namespace, key). set() uses an upsert to replace one entire value. Namespaces organize records; they are not tenant authorization rules.

Multi-instance deployments

Processes can connect to the same PostgreSQL table, but that alone does not coordinate a multi-step read → modify → write sequence or concurrent session turns. Two writers can overwrite the same record. Use application coordination appropriate to the operation and an atomic durable-store contract when task claims/leases are required.

Connection pooling

The adapter constructs an internal pg.Pool from the connection string. V4 has no second constructor argument for pool options and no injected-pool overload. Do not pass { max: 20 } to PostgresStorage. Budget connections across processes and any external database pooler. If you require pool controls outside this adapter’s contract, implement a StorageDriver with your host-owned database client rather than reaching into private adapter fields.

Load balancer setup

A load balancer distributes requests; it does not serialize turns sharing a session. Pair your routing with trusted resource ownership and a strategy for concurrent updates. Closing one instance’s pool does not close pools in other instances.

Best practices

Keep credentials in host configuration, use the database’s verified TLS settings, initialize before admitting work, and monitor errors/connection usage. Plan retention, backups, and schema access for the data you store. Database persistence is not automatic interrupted-run recovery.

Environment variables

DATABASE_URL is a convention used by these examples; the constructor receives a string and does not read that variable itself.

API reference

Method	Behavior
`initialize()`	Create `kv_store` if absent
`get<T>(namespace, key)`	Read a value or `null`
`set<T>(namespace, key, value)`	Upsert one JSON value
`delete(namespace, key)`	Remove one key
`list<T>(namespace, prefix?)`	List keys/values; prefix is used with SQL `LIKE`
`close()`	End the adapter’s connection pool

See storage APIs for exact declarations and recovery for choosing the right persistence layer.

Find an integration

Voice and call adapters

Sandbox and telemetry

Providers and services

Protocols and devices

PostgreSQL storage

Installation

Setup

Constructor

Full example

Schema

Multi-instance deployments

Connection pooling

Load balancer setup

Best practices

Environment variables

API reference

​Installation

​Setup

​Constructor

​Full example

​Schema

​Multi-instance deployments

​Connection pooling

​Load balancer setup

​Best practices

​Environment variables

​API reference

Installation

Setup

Constructor

Full example

Schema

Multi-instance deployments

Connection pooling

Load balancer setup

Best practices

Environment variables

API reference