使用 Postgres 存储

当你需要可持久化、可多实例共享的存储后端时，使用 PostgreSQL。

前置条件

awaken-stores 启用了 postgres feature
有一个可连接的 PostgreSQL 实例
sqlx 所需 tokio 运行时依赖已就绪

步骤

添加依赖：

[dependencies]
awaken-stores = { git = "https://github.com/AwakenWorks/awaken", features = ["postgres"] }

创建连接池：

use sqlx::PgPool;

let pool = PgPool::connect("postgres://user:pass@localhost:5432/mydb").await?;

创建 PostgresStore：

use std::sync::Arc;
use awaken::stores::PostgresStore;

let store = Arc::new(PostgresStore::new(pool));

默认表名：

awaken_threads
awaken_runs
awaken_messages
awaken_configs
awaken_threads_state

使用自定义前缀：

let store = Arc::new(PostgresStore::with_prefix(pool, "myapp"));

接入 runtime：

use std::sync::Arc;
use awaken::contract::commit_coordinator::CommitCoordinator;
use awaken::AgentRuntimeBuilder;
use awaken::engine::GenaiExecutor;
use awaken::registry_spec::ModelSpec;
use awaken::stores::PgCommitCoordinator;

let coordinator =
    Arc::new(PgCommitCoordinator::new(store.clone())?) as Arc<dyn CommitCoordinator>;
let runtime = AgentRuntimeBuilder::new()
    .with_commit_coordinator(coordinator)
    .with_agent_spec(spec)
    .with_provider("anthropic", Arc::new(GenaiExecutor::new()))
    .with_model(ModelSpec::new("claude-sonnet", "anthropic", "claude-sonnet-4-20250514"))
    .build()?;

Schema 初始化：

表和索引会在首次访问时自动通过 ensure_schema() 创建。thread/run/message/config 表使用 JSONB payload，并带有 list/cursor query 所需的索引列。使用对应 server control-plane store 时，同一个 schema 初始化也会安装 event storage、 protocol replay、outbox、checkpoint repair 和 versioned registry 状态。

runtime projection：threads、runs、messages、thread state
managed config：namespace/id config rows 与 notify channel
server control plane：events、replay、outbox、checkpoints、registry versions

初始接入无需手动 migration。

验证

执行 agent 后，在数据库中查询：

SELECT id, updated_at FROM awaken_threads;
SELECT id, updated_at FROM awaken_runs;

应该能看到对应记录。

常见错误

错误	原因	修复
`sqlx::Error` connection refused	PostgreSQL 未启动或连接串错误	检查 `DATABASE_URL` 和数据库状态
首次写入报 `StorageError`	数据库用户权限不足	授予建表和写入权限
表名冲突	其他应用共用了默认表名	用 `with_prefix()` 做命名空间隔离

关键文件

crates/awaken-stores/Cargo.toml
crates/awaken-stores/src/postgres.rs
crates/awaken-stores/src/lib.rs

使用 Postgres 存储

前置条件

步骤

验证

常见错误

相关示例

关键文件

相关