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="support_agent",
        )
    },
)

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-specific settings; may include `postgresql_config` (a `PostgreSqlConfig` instance) to override the configuration 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: support_agent

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. VeADK creates it when needed and keeps session tables inside it. Added in 1.0.2.
`secret_token`	`DATABASE_POSTGRESQL_SECRET_TOKEN`	`str`	`""`	STS token for PostgreSQL auth; not supported yet.

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.

Use schema when several VeADK deployments share a database but must keep separate session tables. Schema names may contain letters, digits, and underscores and cannot start with a digit.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Usage

Parameters

ShortTermMemory constructor parameters (postgresql)

PostgreSqlConfig fields and environment variables

​When to use

​Usage

​Parameters

​ShortTermMemory constructor parameters (postgresql)

​PostgreSqlConfig fields and environment variables

When to use

Usage

Parameters

ShortTermMemory constructor parameters (postgresql)

PostgreSqlConfig fields and environment variables