> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```python lines theme={null}
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`:

```python lines theme={null}
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:

```python lines theme={null}
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-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_`.

```yaml config.yaml lines theme={null}
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.

```bash lines theme={null}
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.

<Note>
  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](https://www.volcengine.com/product/rds-pg).
</Note>