Skip to content

feat: Implementation of MySQL-backed session service for ADK #647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
voborl00 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Implementation of MySQL-backed session service for ADK #647

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 130 additions & 0 deletions contrib/mysql-session-service/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# MySQL Session Service for ADK

This sub-module contains an implementation of a session service for the ADK (Agent Development Kit) that uses MySQL as the backend for storing session data. This allows developers to manage user sessions in a scalable and reliable manner using MySQL's relational database capabilities and JSON column support.

## Getting Started

To integrate this MySQL session service into your ADK project, add the following dependencies to your project's build configuration.

### Maven

```xml
<dependencies>
<!-- ADK Core -->
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk</artifactId>
<version>0.4.1-SNAPSHOT</version>
</dependency>
<!-- MySQL Session Service -->
<dependency>
<groupId>com.google.adk.contrib</groupId>
<artifactId>google-adk-mysql-session-service</artifactId>
<version>0.4.1-SNAPSHOT</version>
</dependency>
<!-- MySQL Connector (or your preferred driver) -->
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<version>8.3.0</version>
</dependency>
<!-- HikariCP (Recommended for connection pooling) -->
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>5.1.0</version>
</dependency>
</dependencies>
```

## Database Schema

You must create the following tables in your MySQL database (version 8.0+ required for JSON support).

```sql
CREATE TABLE IF NOT EXISTS adk_sessions (
session_id VARCHAR(255) PRIMARY KEY,
app_name VARCHAR(255) NOT NULL,
user_id VARCHAR(255) NOT NULL,
state JSON,
created_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
updated_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
INDEX idx_app_user (app_name, user_id)
);

CREATE TABLE IF NOT EXISTS adk_events (
event_id VARCHAR(255) PRIMARY KEY,
session_id VARCHAR(255) NOT NULL,
event_data JSON,
created_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
FOREIGN KEY (session_id) REFERENCES adk_sessions(session_id) ON DELETE CASCADE,
INDEX idx_session_created (session_id, created_at)
);

CREATE TABLE IF NOT EXISTS adk_app_state (
app_name VARCHAR(255) NOT NULL,
state_key VARCHAR(768) NOT NULL,
state_value JSON,
PRIMARY KEY (app_name, state_key)
);

CREATE TABLE IF NOT EXISTS adk_user_state (
app_name VARCHAR(255) NOT NULL,
user_id VARCHAR(255) NOT NULL,
state_key VARCHAR(768) NOT NULL,
state_value JSON,
PRIMARY KEY (app_name, user_id, state_key)
);
```

## Usage

You can configure the `MySqlSessionService` by passing a `DataSource`. We recommend using HikariCP for production connection pooling.

```java
import com.google.adk.runner.Runner;
import com.google.adk.sessions.MySqlSessionService;
import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class MyApp {
public static void main(String[] args) {
// 1. Configure Data Source
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:mysql://localhost:3306/my_db");
config.setUsername("user");
config.setPassword("password");
DataSource dataSource = new HikariDataSource(config);

// 2. Create the Session Service
MySqlSessionService sessionService = new MySqlSessionService(dataSource);

// 3. Pass it to the Runner
Runner runner = new Runner(
new MyAgent(),
"MyAppName",
new InMemoryArtifactService(), // or GcsArtifactService
sessionService, // <--- Your MySQL Service
new InMemoryMemoryService() // or FirestoreMemoryService
);

runner.runLive();
}
}
```

## Testing

This module includes both unit tests and integration tests.

* **Unit Tests:** Fast, in-memory tests that mock the database connection. These verify the service logic without requiring a running database.
```bash
mvn test
```

* **Integration Tests:** Comprehensive tests that run against a real MySQL instance using [Testcontainers](https://testcontainers.com/). These require a Docker environment (e.g., Docker Desktop, or a CI runner with Docker support).
```bash
mvn verify
```

121 changes: 121 additions & 0 deletions contrib/mysql-session-service/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2025 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>com.google.adk</groupId>
<artifactId>google-adk-parent</artifactId>
<version>0.5.1-SNAPSHOT</version>
<relativePath>../../pom.xml</relativePath>
</parent>

<artifactId>google-adk-mysql-session-service</artifactId>
<name>Agent Development Kit - MySQL Session Management</name>
<description>MySQL integration with Agent Development Kit for User Session Management</description>

<dependencies>
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.google.genai</groupId>
<artifactId>google-genai</artifactId>
</dependency>

<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<version>8.3.0</version>
<scope>provided</scope>
</dependency>

<!-- Testing -->
<dependency>
<groupId>com.google.truth</groupId>
<artifactId>truth</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-engine</artifactId>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>mysql</artifactId>
<version>1.19.7</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<version>1.19.7</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>5.1.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>2.0.17</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>2.2.224</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>3.2.5</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Loading