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.

Prerequisites

The veadk-python installation includes the required database drivers. Before running the example, create the database and account, grant permissions to create and read/write session tables, and make the database reachable. VeADK does not provision the database service or database itself Provide connection settings through environment variables and inject the password from your deployment secret configuration

export DATABASE_POSTGRESQL_HOST="127.0.0.1"
export DATABASE_POSTGRESQL_USER="veadk"
export DATABASE_POSTGRESQL_DATABASE="veadk_sessions"

Also set DATABASE_POSTGRESQL_PASSWORD. These settings work with reachable self-managed, Volcengine, or BytePlus database instances; they do not automatically select a cloud provider or region

Usage

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

import asyncio

from veadk.memory.short_term_memory import ShortTermMemory

stm = ShortTermMemory(backend="postgresql")

async def main():
    try:
        await stm.create_session(
            app_name="memory_demo", user_id="user_42", session_id="chat_01"
        )
        session = await stm.session_service.get_session(
            app_name="memory_demo", user_id="user_42", session_id="chat_01"
        )
        assert session is not None
        print(session.id)
    finally:
        await stm.session_service.close()

asyncio.run(main())

The output is chat_01, confirming that the session was created and read back. This example does not call a model. For conversations, pass the same stm to Runner(short_term_memory=stm, agent=agent) and keep the app, user, and session identifiers consistent 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	Synchronous read callback; receives `Session` or `None` plus the query arguments. Use `def callback(session, args, *kwargs)`
`after_create_session_callback`	`Callable \| None`	`None`	Yes	Runs after `ShortTermMemory.create_session()` creates a new session; accepts the new `Session` and can be synchronous or asynchronous

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 during connection and keeps session tables inside it; the account needs the corresponding schema creation and usage permissions
`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

Prerequisites

Usage

Parameters

ShortTermMemory constructor parameters (postgresql)

PostgreSqlConfig fields and environment variables

​When to use

​Prerequisites

​Usage

​Parameters

​ShortTermMemory constructor parameters (postgresql)

​PostgreSqlConfig fields and environment variables

When to use

Prerequisites

Usage

Parameters

ShortTermMemory constructor parameters (postgresql)

PostgreSqlConfig fields and environment variables