orchid-storage-postgres
PostgreSQL storage plugin: chat and config persistence, MCP stores, events, checkpointer, and visibility fragment.
orchid-storage-postgres is the production-grade PostgreSQL storage plugin for the Orchid AI framework. It implements the same storage surface as orchid-storage-sqlite — chat persistence, agent-config CRUD, MCP OAuth stores, event storage, and the LangGraph checkpointer — backed by asyncpg, with all extension points auto-registering via Python entry points.
Installation
pip install orchid-ai orchid-storage-postgresWhat It Provides
| Component | Class | Purpose |
|---|---|---|
| Chat storage | OrchidPostgresChatStorage | Full OrchidChatStorage implementation backed by asyncpg |
| Config storage | OrchidPostgresConfigStorage | OrchidConfigStorage CRUD for database-backed agent definitions |
| MCP token store | OrchidPostgresMCPTokenStore | Per-user OAuth tokens for outbound MCP servers |
| MCP registration store | OrchidPostgresMCPClientRegistrationStore | RFC 7591 dynamic-client registrations |
| MCP gateway state | OrchidPostgresMCPGatewayStateStore | Inbound gateway clients, auth codes, and tokens |
| Event storage | PostgresEventStorage | Pollen + Bloom signal / job / schedule / trigger persistence |
| Signal queue | PostgresSignalQueue | Durable lease-based queue (FOR UPDATE SKIP LOCKED + pg_notify) |
| Checkpointer | _build_postgres_checkpointer | LangGraph AsyncPostgresSaver for agent-state persistence |
| Visibility | _build_postgres_filter | PostgreSQL $1..$N positional-parameter visibility fragment |
| Migrations | v001_initial_schema + v002_ingestion_manifest | Unified DDL for all framework-owned tables + the indexing manifest |
Auto-Registration
The package registers itself via importlib.metadata entry points:
[project.entry-points."orchid.visibility_fragments"]
postgres = "orchid_storage_postgres:_register"
[project.entry-points."orchid.checkpointers"]
postgres = "orchid_storage_postgres:_register"No manual register_visibility_fragment() or register_checkpointer() calls are needed by integrators. The storage classes are referenced via dotted class path in YAML config.
Configuration
storage:
class: orchid_storage_postgres.chat_storage.OrchidPostgresChatStorage
dsn: postgresql://user:pass@host:5432/orchid
checkpointer:
type: postgres
dsn: postgresql://user:pass@host:5432/orchidorchid-api and orchid-cli bundle SQLite defaults; point storage.class at OrchidPostgresChatStorage (and checkpointer.type at postgres) to move state to PostgreSQL for multi-replica deployments. See Persistence for the full backend comparison.