Use PostgreSQL storage

The postgresql backend stores sessions in a PostgreSQL database. Multiple agent instances can connect to the same database for shared, distributed persistence.

When to use

Production, multi-instance, or distributed deployments;
Teams already using PostgreSQL as shared storage.

Usage

Provide connection details via config.yaml (or the matching environment variables) — never hard-code the password.

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory

stm = ShortTermMemory(backend="postgresql")  # connection details from config.yaml / env

agent = Agent(name="demo")
runner = Runner(agent=agent, short_term_memory=stm, app_name="memory_demo")

To forward SQLAlchemy driver args such as connection pooling, use db_kwargs:

stm = ShortTermMemory(
    backend="postgresql",
    db_kwargs={"pool_size": 10, "pool_recycle": 3600},
)

You can also inject a PostgreSqlConfig directly through backend_configs to override the environment variables:

import os

from veadk.configs.database_configs import PostgreSqlConfig

stm = ShortTermMemory(
    backend="postgresql",
    backend_configs={
        "postgresql_config": PostgreSqlConfig(
            host="127.0.0.1",
            port=5432,
            user="veadk",
            password=os.environ["DATABASE_POSTGRESQL_PASSWORD"],
            database="veadk_sessions",
            schema="customer_service",
        )
    },
)

Parameters

ShortTermMemory constructor parameters (postgresql)

Parameter	Type	Default	Effective for postgresql	Description
`backend`	`str`	`"local"`	Yes	Set to `"postgresql"` to select this backend.
`backend_configs`	`dict`	`{}`	Yes	PostgreSQL backend configuration. It may include `postgresql_config` (a `PostgreSqlConfig` instance) to override the config otherwise read from environment variables.
`db_kwargs`	`dict`	`{}`	Yes	Passed to the SQLAlchemy engine; commonly used for pool settings such as `pool_size`, `pool_recycle`, `pool_pre_ping`.
`db_url`	`str`	`""`	Yes (override)	A connection string. Once set, `backend` and `backend_configs` are ignored, and `db_url` is used with `db_kwargs`.
`local_database_path`	`str`	`/tmp/veadk_local_database.db`	No	Used only by `sqlite`.
`after_load_memory_callback`	`Callable \| None`	`None`	Yes	Callback invoked after a session is loaded; receives the loaded `Session`.

PostgreSqlConfig fields and environment variables

The PostgreSqlConfig config class uses the env prefix DATABASE_POSTGRESQL_.

config.yaml

database:
  postgresql:
    host:       # host or IP
    port: 5432
    user:
    password:
    database:
    schema:     # Optional; isolates this deployment's session tables

Field	Env var	Type	Default	Description
`host`	`DATABASE_POSTGRESQL_HOST`	`str`	`""`	Database host or IP.
`port`	`DATABASE_POSTGRESQL_PORT`	`int`	`5432`	Port.
`user`	`DATABASE_POSTGRESQL_USER`	`str`	`""`	Username.
`password`	`DATABASE_POSTGRESQL_PASSWORD`	`str`	`""`	Password.
`database`	`DATABASE_POSTGRESQL_DATABASE`	`str`	`""`	Database name.
`schema`	`DATABASE_POSTGRESQL_SCHEMA`	`str`	`""`	Optional PostgreSQL schema. When set, VeADK creates and accesses short-term session tables in this schema. When empty, the database’s default `search_path` applies.
`secret_token`	`DATABASE_POSTGRESQL_SECRET_TOKEN`	`str`	`""`	STS token for PostgreSQL auth; not supported yet.

Isolate session tables with a schema

Multiple applications can share one PostgreSQL database while using a different DATABASE_POSTGRESQL_SCHEMA for each deployment. VeADK creates the schema when it does not exist and pins the connection’s search_path to it, preventing deployments from sharing the same session tables.

export DATABASE_POSTGRESQL_SCHEMA="customer_service"

The schema name must start with a letter or underscore and contain only letters, digits, and underscores. The database user needs permission to create schemas and tables.

VeADK selects a PostgreSQL driver compatible with the installed Google ADK version and automatically encodes special characters in usernames and passwords. You can provision PostgreSQL on Volcengine.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

When to use

Usage

Parameters

ShortTermMemory constructor parameters (postgresql)

PostgreSqlConfig fields and environment variables

Isolate session tables with a schema

​When to use

​Usage

​Parameters

​ShortTermMemory constructor parameters (postgresql)

​PostgreSqlConfig fields and environment variables

​Isolate session tables with a schema

When to use

Usage

Parameters

ShortTermMemory constructor parameters (postgresql)

PostgreSqlConfig fields and environment variables

Isolate session tables with a schema