Skip to content

Commit a27ebfa

Browse files
voborl00voborl00
committed
feat: Add MySQL Session Service implementation
1 parent 5d8f85b commit a27ebfa

File tree

8 files changed

+1469
-0
lines changed

8 files changed

+1469
-0
lines changed

‎contrib/mysql-session-service/README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# MySQL Session Service for ADK
2+
3+
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.
4+
5+
## Getting Started
6+
7+
To integrate this MySQL session service into your ADK project, add the following dependencies to your project's build configuration.
8+
9+
### Maven
10+
11+
```xml
12+
<dependencies>
13+
<!-- ADK Core -->
14+
<dependency>
15+
<groupId>com.google.adk</groupId>
16+
<artifactId>google-adk</artifactId>
17+
<version>0.4.1-SNAPSHOT</version>
18+
</dependency>
19+
<!-- MySQL Session Service -->
20+
<dependency>
21+
<groupId>com.google.adk.contrib</groupId>
22+
<artifactId>google-adk-mysql-session-service</artifactId>
23+
<version>0.4.1-SNAPSHOT</version>
24+
</dependency>
25+
<!-- MySQL Connector (or your preferred driver) -->
26+
<dependency>
27+
<groupId>com.mysql</groupId>
28+
<artifactId>mysql-connector-j</artifactId>
29+
<version>8.3.0</version>
30+
</dependency>
31+
<!-- HikariCP (Recommended for connection pooling) -->
32+
<dependency>
33+
<groupId>com.zaxxer</groupId>
34+
<artifactId>HikariCP</artifactId>
35+
<version>5.1.0</version>
36+
</dependency>
37+
</dependencies>
38+
```
39+
40+
## Database Schema
41+
42+
You must create the following tables in your MySQL database (version 8.0+ required for JSON support).
43+
44+
```sql
45+
CREATE TABLE IF NOT EXISTS adk_sessions (
46+
session_id VARCHAR(255) PRIMARY KEY,
47+
app_name VARCHAR(255) NOT NULL,
48+
user_id VARCHAR(255) NOT NULL,
49+
state JSON,
50+
created_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
51+
updated_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
52+
INDEX idx_app_user (app_name, user_id)
53+
);
54+
55+
CREATE TABLE IF NOT EXISTS adk_events (
56+
event_id VARCHAR(255) PRIMARY KEY,
57+
session_id VARCHAR(255) NOT NULL,
58+
event_data JSON,
59+
created_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
60+
FOREIGN KEY (session_id) REFERENCES adk_sessions(session_id) ON DELETE CASCADE,
61+
INDEX idx_session_created (session_id, created_at)
62+
);
63+
64+
CREATE TABLE IF NOT EXISTS adk_app_state (
65+
app_name VARCHAR(255) NOT NULL,
66+
state_key VARCHAR(255) NOT NULL,
67+
state_value JSON,
68+
PRIMARY KEY (app_name, state_key)
69+
);
70+
71+
CREATE TABLE IF NOT EXISTS adk_user_state (
72+
app_name VARCHAR(255) NOT NULL,
73+
user_id VARCHAR(255) NOT NULL,
74+
state_key VARCHAR(255) NOT NULL,
75+
state_value JSON,
76+
PRIMARY KEY (app_name, user_id, state_key)
77+
);
78+
```
79+
80+
## Usage
81+
82+
You can configure the `MySqlSessionService` by passing a `DataSource`. We recommend using HikariCP for production connection pooling.
83+
84+
```java
85+
import com.google.adk.runner.Runner;
86+
import com.google.adk.sessions.MySqlSessionService;
87+
import com.zaxxer.hikari.HikariConfig;
88+
import com.zaxxer.hikari.HikariDataSource;
89+
import javax.sql.DataSource;
90+
91+
public class MyApp {
92+
public static void main(String[] args) {
93+
// 1. Configure Data Source
94+
HikariConfig config = new HikariConfig();
95+
config.setJdbcUrl("jdbc:mysql://localhost:3306/my_db");
96+
config.setUsername("user");
97+
config.setPassword("password");
98+
DataSource dataSource = new HikariDataSource(config);
99+
100+
// 2. Create the Session Service
101+
MySqlSessionService sessionService = new MySqlSessionService(dataSource);
102+
103+
// 3. Pass it to the Runner
104+
Runner runner = new Runner(
105+
new MyAgent(),
106+
"MyAppName",
107+
new InMemoryArtifactService(), // or GcsArtifactService
108+
sessionService, // <--- Your MySQL Service
109+
new InMemoryMemoryService() // or FirestoreMemoryService
110+
);
111+
112+
runner.runLive();
113+
}
114+
}
115+
```
116+
117+
## Testing
118+
119+
This module includes both unit tests and integration tests.
120+
121+
* **Unit Tests:** Fast, in-memory tests that mock the database connection. These verify the service logic without requiring a running database.
122+
```bash
123+
mvn test
124+
```
125+
126+
* **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).
127+
```bash
128+
mvn verify
129+
```
130+

‎contrib/mysql-session-service/pom.xml‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
Copyright 2025 Google LLC
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
-->
17+
<project xmlns="http://maven.apache.org/POM/4.0.0"
18+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
19+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
20+
<modelVersion>4.0.0</modelVersion>
21+
22+
<parent>
23+
<groupId>com.google.adk</groupId>
24+
<artifactId>google-adk-parent</artifactId>
25+
<version>0.4.1-SNAPSHOT</version>
26+
<relativePath>../../pom.xml</relativePath>
27+
</parent>
28+
29+
<artifactId>google-adk-mysql-session-service</artifactId>
30+
<name>Agent Development Kit - MySQL Session Management</name>
31+
<description>MySQL integration with Agent Development Kit for User Session Management</description>
32+
33+
<dependencies>
34+
<dependency>
35+
<groupId>com.google.adk</groupId>
36+
<artifactId>google-adk</artifactId>
37+
<version>${project.version}</version>
38+
</dependency>
39+
<dependency>
40+
<groupId>com.google.genai</groupId>
41+
<artifactId>google-genai</artifactId>
42+
</dependency>
43+
44+
<dependency>
45+
<groupId>com.mysql</groupId>
46+
<artifactId>mysql-connector-j</artifactId>
47+
<version>8.3.0</version>
48+
<scope>provided</scope>
49+
</dependency>
50+
51+
<!-- Testing -->
52+
<dependency>
53+
<groupId>com.google.truth</groupId>
54+
<artifactId>truth</artifactId>
55+
<scope>test</scope>
56+
</dependency>
57+
<dependency>
58+
<groupId>org.mockito</groupId>
59+
<artifactId>mockito-core</artifactId>
60+
<scope>test</scope>
61+
</dependency>
62+
<dependency>
63+
<groupId>org.junit.jupiter</groupId>
64+
<artifactId>junit-jupiter-api</artifactId>
65+
<scope>test</scope>
66+
</dependency>
67+
<dependency>
68+
<groupId>org.junit.jupiter</groupId>
69+
<artifactId>junit-jupiter-engine</artifactId>
70+
<scope>test</scope>
71+
</dependency>
72+
73+
<dependency>
74+
<groupId>org.testcontainers</groupId>
75+
<artifactId>mysql</artifactId>
76+
<version>1.19.7</version>
77+
<scope>test</scope>
78+
</dependency>
79+
<dependency>
80+
<groupId>org.testcontainers</groupId>
81+
<artifactId>junit-jupiter</artifactId>
82+
<version>1.19.7</version>
83+
<scope>test</scope>
84+
</dependency>
85+
<dependency>
86+
<groupId>com.zaxxer</groupId>
87+
<artifactId>HikariCP</artifactId>
88+
<version>5.1.0</version>
89+
<scope>test</scope>
90+
</dependency>
91+
<dependency>
92+
<groupId>org.slf4j</groupId>
93+
<artifactId>slf4j-simple</artifactId>
94+
<version>2.0.17</version>
95+
<scope>test</scope>
96+
</dependency>
97+
<dependency>
98+
<groupId>com.h2database</groupId>
99+
<artifactId>h2</artifactId>
100+
<version>2.2.224</version>
101+
<scope>test</scope>
102+
</dependency>
103+
</dependencies>
104+
<build>
105+
<plugins>
106+
<plugin>
107+
<groupId>org.apache.maven.plugins</groupId>
108+
<artifactId>maven-failsafe-plugin</artifactId>
109+
<version>3.2.5</version>
110+
<executions>
111+
<execution>
112+
<goals>
113+
<goal>integration-test</goal>
114+
<goal>verify</goal>
115+
</goals>
116+
</execution>
117+
</executions>
118+
</plugin>
119+
</plugins>
120+
</build>
121+
</project>

0 commit comments

Comments
 (0)