PostgresBaseStore

PostgreSQL-backed BaseStore.

Schema

`CREATE TABLE agentscope_store (
namespace_path VARCHAR(2048) NOT NULL,
item_key VARCHAR(255) NOT NULL,
value_json TEXT NOT NULL,
version BIGINT NOT NULL,
updated_at BIGINT NOT NULL,
PRIMARY KEY (namespace_path, item_key)
)
`

The optional Builder#initializeSchema(true) flag runs CREATE TABLE IF NOT EXISTS on construction.

Namespace encoding

To preserve the prefix-search behaviour of InMemoryStore, the namespace components are joined with the ASCII unit-separator 0x1F and stored with a trailing separator. Searching by namespace [a, b] translates into WHERE namespace_path LIKE 'ab%' ESCAPE '!', which matches both that exact namespace and any deeper sub-namespace. Namespace segments that contain 0x1F are rejected.

CAS

#putIfVersion uses a single-statement conditional UPDATE keyed on version. The expectedVersion == 0 case issues an INSERT and treats a primary-key conflict as a failed CAS. Both paths are atomic without additional locking, so the store is safe to share among multiple JVMs writing to the same database.