# tjni/langgraph-checkpoint-mysql architecture

> Architecture diagram of the GitHub repository tjni/langgraph-checkpoint-mysql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tjni/langgraph-checkpoint-mysql
- Repository: https://github.com/tjni/langgraph-checkpoint-mysql

## Overview

##### Project Type and Purpose
- This is an open-source Python library (“LangGraph Checkpoint MySQL”) that implements checkpoint saving/loading functionality on top of MySQL (or MariaDB).
- It provides both synchronous and asynchronous checkpointer implementations, mirroring the official Postgres version.

##### File Structure
- Top-level directories:
- langgraph/checkpoint/mysql – core checkpoint saver modules (sync + async drivers, base classes).
- langgraph/store/mysql – store modules (similar driver variants).
- tests & langgraph-tests – unit/integration test suites for sync/async behavior and edge cases.
- .github/workflows & Makefile – CI, linting, testing, and release automation.
- Key modules: pymysql.py, aio.py, asyncmy.py (driver-specific implementations), _internal.py (shared logic), base classes, utils.

##### README Insights
- Usage examples for synchronous (`PyMySQLSaver`) and asynchronous (`AIOMySQLSaver` / `AsyncMySaver`) checkpointers.
- Emphasis on a `.setup()` step to create tables and on passing `autocommit=True`.
- Dependency variants via extras (e.g., `[pymysql]`, `[aiomysql]`, `[asyncmy]`).

##### Main Components & Relationships
a. Components:
- Client Code (LangGraph or user application)
- Checkpointer Library
- Sync Layer: `PyMySQLSaver`
- Async Layer: `AIOMySQLSaver` / `AsyncMySaver`
- Shared Base & Internal Modules (`_internal`, utils)
- MySQL Database (or MariaDB)
- Driver Adapters: PyMySQL, aiomysql, asyncmy
- CI/CD Pipeline (GitHub Actions)
- Test Harness (pytest + Docker Compose for MySQL/MariaDB)
b. Interactions:
- Client invokes `from_conn_string()` → library instantiates appropriate Saver.
- Saver `.setup()` issues DDL statements to MySQL.
- Saver methods (`put`/`aput`, `get`/`aget`, `list`/`alist`) translate checkpoint operations into SQL queries.
- Driver adapter executes queries against the MySQL server.
- Results flow back to client in Python data structures.
c. Architectural Patterns:
- Strategy Pattern: different driver implementations (sync vs async, PyMySQL vs aiomysql vs asyncmy) share a common interface.
- Repository Pattern: Checkpointer classes encapsulate persistence logic.
- Layered Modules: separation between public API, internal shared logic, and driver-specific code.
d. Technologies & Frameworks:
- Python 3, MySQL/MariaDB ≥ required versions
- Database drivers: PyMySQL, aiomysql, asyncmy
- Testing: pytest, Docker Compose for test databases
- CI: GitHub Actions, Poetry setup

##### Detailed Capture of Architectural Elements
- Version gating for MySQL/MariaDB features.
- GitHub Actions workflow invoking lint, test, and release steps.
- Test suite spinning up MySQL/MariaDB via Docker Compose and running pytest.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Code"
        ClientApp["Client Application"]:::external
    end

    %% Checkpointer Library
    subgraph "Checkpointer Library" 
        direction TB
        subgraph "Sync Layer"
            direction TB
            PyMySQLSaver["PyMySQLSaver"]:::library
        end
        subgraph "Async Layer"
            direction TB
            AIOMySQLSaver["AIOMySQLSaver"]:::library
            AsyncMySaver["AsyncMySaver"]:::library
        end
        subgraph "Shared Base"
            direction TB
            BaseSync["base.py"]:::library
            BaseAsync["aio_base.py"]:::library
        end
        subgraph "Internal Logic"
            direction TB
            InternalSync["_internal.py"]:::library
            InternalAsync["_ainternal.py"]:::library
        end
        Utils["utils.py"]:::library
        Shallow["shallow.py"]:::library
    end

    %% Driver Adapters
    subgraph "Driver Adapters"
        direction TB
        PyMySQLDrv["PyMySQL Adapter"]:::adapter
        aiomysqlDrv["aiomysql Adapter"]:::adapter
        asyncmyDrv["asyncmy Adapter"]:::adapter
    end

    %% Database
    MySQLDB["MySQL / MariaDB"]:::external

    %% Store Modules
    subgraph "Store Modules"
        direction TB
        StoreSync["PyMySQL Store"]:::library
        StoreAsyncAio["AIOMySQL Store"]:::library
        StoreAsyncMy["AsyncMySQL Store"]:::library
        StoreBaseSync["base.py"]:::library
        StoreBaseAsync["aio_base.py"]:::library
    end

    %% Testing Infrastructure
    subgraph "Test Infrastructure"
        direction TB
        UT1["tests/test_sync.py"]:::tooling
        UT2["tests/test_async.py"]:::tooling
        UT3["tests/test_store.py"]:::tooling
        UT4["tests/test_async_store.py"]:::tooling
        ComposeMySQL["tests/compose-mysql.yml"]:::tooling
        ComposeMariaDB["tests/compose-mariadb.yml"]:::tooling
        ConftestTests["tests/conftest.py"]:::tooling
        LGTests["langgraph-tests/tests/*.pytest"]:::tooling
        LGConftest["langgraph-tests/tests/conftest.py"]:::tooling
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CI1[".github/workflows/ci.yml"]:::tooling
        CI2[".github/workflows/_lint.yml"]:::tooling
        CI3[".github/workflows/_test.yml"]:::tooling
        CI4[".github/workflows/release.yml"]:::tooling
        PoetryAction[".github/actions/poetry_setup/action.yml"]:::tooling
        Makefile["Makefile"]:::tooling
    end

    %% Project Metadata
    subgraph "Metadata & Docs"
        direction TB
        README["README.md"]:::tooling
        PyProject["pyproject.toml"]:::tooling
        License["LICENSE"]:::tooling
        Gitignore[".gitignore"]:::tooling
    end

    %% Connections
    ClientApp -->|"invokes from_conn_string()"| PyMySQLSaver
    ClientApp -->|"invokes from_conn_string()"| AIOMySQLSaver
    ClientApp -->|"invokes from_conn_string()"| AsyncMySaver

    PyMySQLSaver -->|"uses"| BaseSync
    AIOMySQLSaver -->|"uses"| BaseAsync
    AsyncMySaver -->|"uses"| BaseAsync

    PyMySQLSaver -->|"delegates to"| InternalSync
    AIOMySQLSaver -->|"delegates to"| InternalAsync
    AsyncMySaver -->|"delegates to"| InternalAsync

    PyMySQLSaver -->|"calls"| Utils
    AIOMySQLSaver -->|"calls"| Utils
    AsyncMySaver -->|"calls"| Utils
    PyMySQLSaver -->|"calls"| Shallow
    AIOMySQLSaver -->|"calls"| Shallow
    AsyncMySaver -->|"calls"| Shallow

    PyMySQLSaver -->|"executes SQL via"| PyMySQLDrv
    AIOMySQLSaver -->|"executes SQL via"| aiomysqlDrv
    AsyncMySaver -->|"executes SQL via"| asyncmyDrv

    PyMySQLDrv -->|"connects to"| MySQLDB
    aiomysqlDrv -->|"connects to"| MySQLDB
    asyncmyDrv -->|"connects to"| MySQLDB

    StoreSync -->|"uses Base"| StoreBaseSync
    StoreAsyncAio -->|"uses Base"| StoreBaseAsync
    StoreAsyncMy -->|"uses Base"| StoreBaseAsync

    StoreSync -->|"executes SQL via"| PyMySQLDrv
    StoreAsyncAio -->|"executes SQL via"| aiomysqlDrv
    StoreAsyncMy -->|"executes SQL via"| asyncmyDrv

    UT1 -->|"tests"| PyMySQLSaver
    UT2 -->|"tests"| AIOMySQLSaver
    UT2 -->|"tests"| AsyncMySaver
    UT3 -->|"tests"| StoreSync
    UT4 -->|"tests"| StoreAsyncAio
    UT4 -->|"tests"| StoreAsyncMy
    ComposeMySQL -->|"spins up"| MySQLDB
    ComposeMariaDB -->|"spins up"| MySQLDB
    ConftestTests -->|"configures pytest"| UT1
    ConftestTests -->|"configures pytest"| UT2
    ConftestTests -->|"configures pytest"| UT3
    ConftestTests -->|"configures pytest"| UT4
    LGTests -->|"integration tests"| ClientApp
    LGConftest -->|"configures pytest"| LGTests

    CI1 -->|"runs"| UT1
    CI1 -->|"runs"| UT2
    CI1 -->|"runs"| UT3
    CI1 -->|"runs"| UT4
    CI2 -->|"checks"| PyMySQLSaver
    CI2 -->|"checks"| AIOMySQLSaver
    CI2 -->|"checks"| AsyncMySaver
    CI3 -->|"runs"| LGTests
    CI4 -->|"publishes release"| PyProject

    %% Click Events
    click PyMySQLSaver "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/pymysql.py"
    click AIOMySQLSaver "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/aio.py"
    click AsyncMySaver "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/asyncmy.py"
    click BaseSync "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/base.py"
    click BaseAsync "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/aio_base.py"
    click InternalSync "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/_internal.py"
    click InternalAsync "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/_ainternal.py"
    click Utils "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/utils.py"
    click Shallow "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/checkpoint/mysql/shallow.py"
    click StoreSync "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/store/mysql/pymysql.py"
    click StoreAsyncAio "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/store/mysql/aio.py"
    click StoreAsyncMy "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/store/mysql/asyncmy.py"
    click StoreBaseSync "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/store/mysql/base.py"
    click StoreBaseAsync "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph/store/mysql/aio_base.py"
    click UT1 "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/tests/test_sync.py"
    click UT2 "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/tests/test_async.py"
    click UT3 "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/tests/test_store.py"
    click UT4 "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/tests/test_async_store.py"
    click ComposeMySQL "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/tests/compose-mysql.yml"
    click ComposeMariaDB "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/tests/compose-mariadb.yml"
    click ConftestTests "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/tests/conftest.py"
    click LGTests "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph-tests/tests/*.pytest"
    click LGConftest "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/langgraph-tests/tests/conftest.py"
    click CI1 "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/.github/workflows/_lint.yml"
    click CI3 "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/.github/workflows/_test.yml"
    click CI4 "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/.github/workflows/release.yml"
    click PoetryAction "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/.github/actions/poetry_setup/action.yml"
    click Makefile "https://github.com/tjni/langgraph-checkpoint-mysql/tree/main/Makefile"
    click README "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/README.md"
    click PyProject "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/pyproject.toml"
    click License "https://github.com/tjni/langgraph-checkpoint-mysql/tree/main/LICENSE"
    click Gitignore "https://github.com/tjni/langgraph-checkpoint-mysql/blob/main/.gitignore"

    %% Styles
    classDef library fill:#cce5ff,stroke:#004085,color:#004085
    classDef adapter fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#ffeeba,stroke:#856404,color:#856404
    classDef tooling fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
