---
title: "Postgres Token State Backend"
url: "https://docs.caracal.run/sdks/connectors/postgres/"
markdown_url: "https://docs.caracal.run/markdown/sdks/connectors/postgres.md"
description: "TypeScript Postgres backend for persisted token state."
page_type: "page"
concepts: []
requires: []
---

# Postgres Token State Backend

Canonical URL: https://docs.caracal.run/sdks/connectors/postgres/
Markdown URL: https://docs.caracal.run/markdown/sdks/connectors/postgres.md
Description: TypeScript Postgres backend for persisted token state.
Page type: page
Concepts: none
Requires: none

---

`@caracalai/tokenstate-postgres` stores token-state rows in Postgres for TypeScript services that need durable mandate state.

## Install

```bash
npm install @caracalai/tokenstate-postgres
```

The package targets Node `>=22`.

## Schema

The package exports `MCP_TOKEN_STATE_DDL`, which creates:

```sql
CREATE TABLE IF NOT EXISTS mcp_token_state (
  zone_id TEXT NOT NULL,
  sub TEXT NOT NULL,
  scope TEXT NOT NULL,
  expires_at TIMESTAMPTZ NOT NULL,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  PRIMARY KEY (zone_id, sub)
);
```

## Backend

```ts
import { MCP_TOKEN_STATE_DDL, PostgresBackend } from "@caracalai/tokenstate-postgres";

await pool.query(MCP_TOKEN_STATE_DDL);

const backend = new PostgresBackend(pool);
await backend.set({
  zone_id: "zone_prod",
  sub: "agent_123",
  scope: "tickets:read",
  expires_at: new Date(Date.now() + 60_000).toISOString(),
});
```

## Use cases

- Persisting active token state across service restarts.
- Sharing token-state reads across multiple TypeScript resource-server instances.
- Building custom resource-server controls that need a small `(zone_id, sub, scope)` state table.

## Boundary

This package is a token-state backend. It is not the revocation stream consumer. Use [Redis Revocation Store](/sdks/connectors/redis/) when you need to consume `caracal.sessions.revoke`.