> ## 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 MySQL storage

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

## When to use

* Production, multi-instance, or distributed deployments;
* When sessions are centrally managed by a shared MySQL.

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

```bash theme={null}
export DATABASE_MYSQL_HOST="127.0.0.1"
export DATABASE_MYSQL_USER="veadk"
export DATABASE_MYSQL_DATABASE="veadk_sessions"
```

Also set `DATABASE_MYSQL_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.

```python lines theme={null}
import asyncio

from veadk.memory.short_term_memory import ShortTermMemory

stm = ShortTermMemory(backend="mysql")

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`:

```python lines theme={null}
stm = ShortTermMemory(
    backend="mysql",
    db_kwargs={"pool_size": 10, "pool_recycle": 3600},
)
```

You can also inject a `MysqlConfig` directly through `backend_configs` to override the environment variables (hard-coding the password is discouraged):

```python lines theme={null}
import os

from veadk.configs.database_configs import MysqlConfig

stm = ShortTermMemory(
    backend="mysql",
    backend_configs={
        "mysql_config": MysqlConfig(
            host="127.0.0.1",
            user="veadk",
            password=os.environ["DATABASE_MYSQL_PASSWORD"],
            database="veadk_sessions",
        )
    },
)
```

## Parameters

### ShortTermMemory constructor parameters (mysql)

| Parameter | Type | Default | Effective for mysql | Description |
| :- | :- | :- | :- | :- |
| `backend` | `str` | `"local"` | Yes | Set to `"mysql"` to select this backend. |
| `backend_configs` | `dict` | `{}` | Yes | MySQL-specific settings; may include `mysql_config` (a `MysqlConfig` 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 |

### MysqlConfig fields and environment variables

The `MysqlConfig` config class uses the env prefix `DATABASE_MYSQL_`.

```yaml config.yaml lines theme={null}
database:
  mysql:
    host:       # host or IP
    user:
    password:
    database:
    charset: utf8
```

| Field | Env var | Type | Default | Description |
| :- | :- | :- | :- | :- |
| `host` | `DATABASE_MYSQL_HOST` | `str` | `""` | Database host or IP. |
| `user` | `DATABASE_MYSQL_USER` | `str` | `""` | Username. |
| `password` | `DATABASE_MYSQL_PASSWORD` | `str` | `""` | Password. |
| `database` | `DATABASE_MYSQL_DATABASE` | `str` | `""` | Database name. |
| `charset` | `DATABASE_MYSQL_CHARSET` | `str` | `utf8` | Configuration default; session connections do not forward this field. Set `db_kwargs={"connect_args": {"charset": "utf8mb4"}}` when required |
| `secret_token` | `DATABASE_MYSQL_SECRET_TOKEN` | `str` | `""` | STS token for MySQL auth; not supported yet. |

<Note>
  VeADK selects a MySQL driver compatible with the installed Google ADK version and automatically encodes special characters in usernames and passwords. You can [provision MySQL on Volcengine](https://www.volcengine.com/product/rds-mysql).
</Note>

<Warning>
  `MysqlConfig` has no port field, so the connection uses MySQL's default port. For a non-default port or finer connection control, use `db_url` to supply a full connection string instead.
</Warning>