vercel__chat/apps/docs/content/adapters/official/postgres.mdx

---
title: PostgreSQL
description: Production state adapter using PostgreSQL via node-postgres.
packageName: "@chat-adapter/state-pg"
slug: postgres
type: state
logo: postgres
tagline: Production state adapter for Chat SDK built on `pg` (node-postgres). Use this when PostgreSQL is your primary datastore and you don't want a separate Redis.
beta: true
features:
  persistence: yes
  multiInstance: yes
  subscriptions: yes
  distributedLocking: yes
  keyValueCache:
    status: yes
    label: TTL
  lists: yes
  queues: yes
  keyPrefix: yes
---

## Install

<PackageInstall package="@chat-adapter/state-pg" />

## Quick start

<Callout type="info">
The adapter auto-detects `POSTGRES_URL` (or `DATABASE_URL`) from the environment.
</Callout>

```typescript title="lib/bot.ts" lineNumbers
import { Chat } from "chat";
import { createPostgresState } from "@chat-adapter/state-pg";

const bot = new Chat({
  userName: "mybot",
  adapters: { /* ... */ },
  state: createPostgresState(),
});
```

The adapter creates its tables on `connect()` if they don't already exist.

## Configuration

<TypeTable
  type={{
    url: {
      type: "string",
      description:
        "Postgres connection URL. Auto-detected from `POSTGRES_URL` or `DATABASE_URL`.",
    },
    client: {
      type: "pg.Pool",
      description: "An existing `pg.Pool` instance.",
    },
    keyPrefix: {
      type: "string",
      default: '"chat-sdk"',
      description: "Prefix applied to every row written by the adapter.",
    },
    logger: {
      type: "Logger",
      description:
        'Logger instance. Defaults to `ConsoleLogger("info").child("postgres")`.',
    },
  }}
/>

Either `url`, `POSTGRES_URL`/`DATABASE_URL`, or `client` is required.

## Advanced

### Using an existing pool

```typescript title="lib/state.ts" lineNumbers
import pg from "pg";
import { createPostgresState } from "@chat-adapter/state-pg";

const client = new pg.Pool({ connectionString: process.env.POSTGRES_URL! });
export const state = createPostgresState({ client });
```

### Data model

The following tables are created on first connect:

```
chat_state_subscriptions
chat_state_locks
chat_state_cache
chat_state_lists
chat_state_queues
```

All rows are namespaced by `key_prefix`.

### Locking under high contention

The Redis adapters use atomic `SET NX PX` for lock acquisition. The Postgres adapter uses `INSERT ... ON CONFLICT DO UPDATE WHERE expires_at <= now()`, relying on row-level locking. Safe for typical workloads, but under extreme contention prefer a Redis adapter.

### Expired row cleanup

Postgres does not delete expired rows automatically. The adapter cleans up opportunistically — expired locks are overwritten on the next `acquireLock()`, expired cache entries are deleted on the next `get()`, and so on. For high-throughput deployments, run a periodic job:

```sql
DELETE FROM chat_state_locks WHERE expires_at <= now();
DELETE FROM chat_state_cache WHERE expires_at <= now();
DELETE FROM chat_state_lists WHERE expires_at <= now();
DELETE FROM chat_state_queues WHERE expires_at <= now();
```

## Feature support

<FeatureSupport />