Postgres backend¶
PostgresStore persists state to a PostgreSQL table with the same interface as the
in-memory Store. Values are stored as msgpack bytes (the same wire
format as the Rust core), so state is durable, shared across processes and machines, and
readable by any msgpack consumer.
Use it like a Store¶
from swarmstate.backends.postgres import PostgresStore
store = PostgresStore("postgresql://user:pass@host:5432/db")
store.set("workflow", "onboarding", {"step": 3})
store.get("workflow", "onboarding") # -> {"step": 3}
It implements the full interface (set, get, contains, delete, keys,
namespaces, clear, len(store), snapshot() / restore(), and the batch operations
set_many, get_many, delete_many, delete_namespace), plus close(). A set_many
batch is one transaction: all of it lands, or none of it.
Async¶
Every key/value operation has an a-prefixed async twin (aget, aset_many, akeys,
...). SwarmStateSaver awaits them from its async methods, so an
async graph never parks a worker thread on Postgres:
store = PostgresStore("postgresql://user:pass@host/db")
await store.aset("workflow", "onboarding", {"step": 3})
await store.aget("workflow", "onboarding") # -> {"step": 3}
await store.aclose() # the async pool of this event loop
A store built from a DSN opens an AsyncConnectionPool lazily, one per event loop
(async connections belong to the loop that opened them), or a single async connection
without psycopg_pool. A store given only conn= / pool= has no async support unless
you also pass apool=; the saver then falls back to a worker thread.
Durable, shared LangGraph checkpoints¶
PostgresStore drops straight into SwarmStateSaver, so LangGraph
checkpoints live in your existing Postgres, survive restarts, and are shared across
workers:
from swarmstate.backends.postgres import PostgresStore
from swarmstate.integrations.langgraph import SwarmStateSaver
saver = SwarmStateSaver(PostgresStore("postgresql://user:pass@host/db"))
graph = builder.compile(checkpointer=saver)
Which backend?¶
| Backend | Persistent | Shared across processes | Needs a server |
|---|---|---|---|
Store (memory) |
no | no | no |
DiskStore (SQLite) |
yes (a file) | one machine | no |
RedisStore |
yes | yes (networked) | yes (Redis) |
PostgresStore |
yes | yes (networked) | yes (Postgres) |
Connections¶
Connections come from a psycopg_pool pool (max_size=8 by default), so concurrent
workers are not serialized through one connection — which is the point of choosing Postgres
in the first place:
store = PostgresStore("postgresql://user:pass@host/db", max_size=16)
store = PostgresStore(conn=my_connection) # opt out: single connection, mutex-guarded
An install without psycopg_pool falls back to the single-connection path automatically.
Like DiskStore, max_key is answered from the primary-key index, so the
LangGraph saver resolves "newest checkpoint" with an indexed query and writes no pointer
row.
Layout & parameters¶
A single table (ns text, k text, v bytea, primary key (ns, k)) (default name
swarmstate_kv); v is msgpack bytes. ns and k use COLLATE "C", so keys order by
code point like every other backend, and the prefix lookups the LangGraph saver runs on
each list() and delete_thread() seek the primary key (Postgres 15+) instead of
scanning the table.
Tables created by swarmstate 0.11 or earlier keep the database's collation and keep working as before. To give one the same behaviour:
ALTER TABLE swarmstate_kv
ALTER COLUMN ns TYPE text COLLATE "C",
ALTER COLUMN k TYPE text COLLATE "C";
| Parameter | Default | Description |
|---|---|---|
dsn |
postgresql:///swarmstate |
libpq connection string |
conn |
None |
pass an existing psycopg connection instead of a DSN |
pool |
None |
an existing psycopg_pool.ConnectionPool for the sync methods |
apool |
None |
an existing psycopg_pool.AsyncConnectionPool for the async ones |
max_size |
8 |
size of the pools the store opens itself |
table |
"swarmstate_kv" |
table name (validated identifier) |
codec |
"msgpack" |
value serialization (stable, cross-language) |