docs: Add PostgreSQL session storage sample and documentation #3926

hiroakis · 2025-12-16T07:04:36Z

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

Related: This library DatabaseSessionService is showing error #3916

2. Or, if no issue exists, describe the change:

Problem:
While DatabaseSessionService already supports PostgreSQL through SQLAlchemy, there is no documentation or sample code showing users how to configure and use it.

Solution:
Add a comprehensive sample under contributing/samples/postgres_session_service/ that demonstrates:

How to configure DatabaseSessionService with PostgreSQL
The auto-generated database schema (sessions, events, app_states, user_states tables)
Connection URL format and configuration options
A working sample agent with session persistence

Testing Plan

Unit Tests:

I have added or updated unit tests for my change.
All unit tests pass locally.

This is a documentation-only change (new sample), so no new unit tests are required. Existing tests continue to pass.

Manual End-to-End (E2E) Tests:

Tested locally with the following steps:

Started PostgreSQL using docker compose up -d
Set environment variables:

export POSTGRES_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/adk_sessions
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=true

Ran pip install google-adk asyncpg greenlet to install the required packages
Ran python main.py - session created successfully
Ran python main.py again - previous session resumed with event history
Verified tables and rows created in PostgreSQL (sessions, events, app_states, user_states)

Checklist

I have read the https://github.com/google/adk-python/blob/main/CONTRIBUTING.md document.
I have performed a self-review of my own code.
I have commented my code, particularly in hard-to-understand areas.
I have added tests that prove my fix is effective or that my feature works.
New and existing unit tests pass locally with my changes.
I have manually tested my changes end-to-end.
Any dependent changes have been merged and published in downstream modules.

Additional context

This PR adds documentation and a working sample for an already-supported feature. The DatabaseSessionService class already handles PostgreSQL through its DynamicJSON type decorator which uses JSONB for PostgreSQL.

Files added:

contributing/samples/postgres_session_service/README.md - Comprehensive guide
contributing/samples/postgres_session_service/agent.py - Sample agent
contributing/samples/postgres_session_service/main.py - Usage example
contributing/samples/postgres_session_service/compose.yml - Local PostgreSQL setup
contributing/samples/postgres_session_service/__init__.py - Package init

Add a comprehensive sample demonstrating how to use DatabaseSessionService with PostgreSQL, including: - README with schema documentation and configuration guide - Sample agent and main.py for session persistence demo - Docker Compose file for local PostgreSQL setup Related to google#3916

gemini-code-assist · 2025-12-16T07:04:53Z

Summary of Changes

Hello @hiroakis, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a gap in user guidance by introducing a comprehensive sample and documentation for integrating PostgreSQL with the DatabaseSessionService. While PostgreSQL support already existed, this change provides clear instructions and a runnable example, enabling users to easily configure and utilize PostgreSQL for persisting agent sessions, events, and various states. The new sample enhances the developer experience by offering a practical demonstration of this crucial feature.

Highlights

New PostgreSQL Session Storage Sample: Introduces a comprehensive sample and documentation for using PostgreSQL with DatabaseSessionService to persist agent sessions, events, and states.
Detailed Configuration Guide: Provides a detailed guide on configuring DatabaseSessionService for PostgreSQL, including connection URL formats, basic and advanced SQLAlchemy options, and prerequisites.
Auto-Generated Database Schema: Outlines the auto-generated database schema for sessions, events, app_states, and user_states tables, including column types and descriptions.
Working Sample Agent and Docker Setup: Includes a functional sample LLM agent and a docker compose file for easily setting up a local PostgreSQL instance to run the sample.
Demonstrates Session Persistence and State Management: Showcases how sessions and events are persisted across application restarts and how PostgreSQL's JSONB type is used for efficient state storage.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request adds a valuable sample and documentation for using PostgreSQL as a session store with DatabaseSessionService. The code and documentation are well-structured and clear. I have a few suggestions to improve the sample code's robustness and the documentation's clarity. Specifically, I've recommended using timezone-aware datetimes in the sample agent and improving the consistency and clarity of instructions in the README.md file.

gemini-code-assist · 2025-12-16T07:06:49Z

contributing/samples/postgres_session_service/README.md

+Install the required async PostgreSQL driver:
+
+```bash
+pip install asyncpg
+```


The installation instructions are split between the 'Installation' section and 'Running the Sample' section (step 3). This can be confusing. It would be clearer to provide the complete installation command in this 'Installation' section. With this change, step 3 under 'Running the Sample' (lines 155-159) becomes redundant and can be removed for better clarity.

Suggested change

Install the required async PostgreSQL driver:

```bash

pip install asyncpg

```

Install the required Python packages:

```bash

pip install google-adk asyncpg greenlet

gemini-code-assist · 2025-12-16T07:06:49Z

contributing/samples/postgres_session_service/README.md

+
+```bash
+POSTGRES_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/adk_sessions
+GOOGLE_CLOUD_PROJECT={{ your project }}


The placeholder {{ your project }} is a bit unconventional. Using a more standard placeholder format like <your-gcp-project-id> would be clearer for users and consistent with common documentation practices. It also makes it more obvious that this is a value they need to replace.

Suggested change

GOOGLE_CLOUD_PROJECT={{ your project }}

GOOGLE_CLOUD_PROJECT=<your-gcp-project-id>

gemini-code-assist · 2025-12-16T07:06:50Z

contributing/samples/postgres_session_service/agent.py

+from datetime import datetime
+
+from google.adk.agents.llm_agent import Agent
+
+
+def get_current_time() -> str:
+  """Get the current time.
+
+  Returns:
+    A string with the current time in ISO format.
+  """
+  return datetime.now().strftime("%Y-%m-%d %H:%M:%S")


The current implementation of get_current_time uses datetime.now(), which produces a timezone-naive datetime object. This can lead to ambiguity and bugs when dealing with different timezones. It's best practice to use timezone-aware datetimes, for instance by using UTC.

Additionally, the docstring claims to return an ISO format string, but the strftime format "%Y-%m-%d %H:%M:%S" is not the standard ISO 8601 format. Using datetime.isoformat() on a timezone-aware datetime object is the correct way to produce an ISO 8601 compliant string. This change also requires importing timezone from datetime.

Suggested change

from datetime import datetime

from google.adk.agents.llm_agent import Agent

def get_current_time() -> str:

"""Get the current time.

Returns:

A string with the current time in ISO format.

"""

return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

from datetime import datetime, timezone

from google.adk.agents.llm_agent import Agent

def get_current_time() -> str:

"""Get the current time.

Returns:

A string with the current time in ISO 8601 format.

"""

return datetime.now(timezone.utc).isoformat()

- Consolidate installation instructions in Installation section - Remove duplicate step 3 and renumber steps - Use standard placeholder format (<your-gcp-project-id>) - Use timezone-aware datetime with ISO 8601 format

hiroakis · 2025-12-16T07:21:23Z

I've addressed all the feedback in 66bc944

Consolidated installation instructions and removed the duplicate step
Changed placeholder to standard format ()
Updated to use timezone-aware datetime with ISO 8601 format

AlejandroBlanco2001 · 2025-12-16T14:19:03Z

Great addition, @hiroakis. I will make the corresponding change in the service documentation to correct the SQLite example: google/adk-docs#1075

ryanaiagent · 2025-12-17T20:02:36Z

Hi @hiroakis , Thank you for your contribution! We appreciate you taking the time to submit this pull request.
Can you fix lint errors by running autoformat.sh

hiroakis · 2025-12-18T01:25:48Z

@ryanaiagent Fixed in 30bbad2 ! Note: Running autoformat.sh also fixed contributing/samples/gepa/run_experiment.py and contributing/samples/gepa/experiment.py, so I've included those changes in the commit as well.

adk-bot added the documentation [Component] This issue is related to documentation, it will be transferred to adk-docs label Dec 16, 2025

gemini-code-assist bot reviewed Dec 16, 2025

View reviewed changes

docs: Address review comments for PostgreSQL sample

66bc944

- Consolidate installation instructions in Installation section - Remove duplicate step 3 and renumber steps - Use standard placeholder format (<your-gcp-project-id>) - Use timezone-aware datetime with ISO 8601 format

AlejandroBlanco2001 approved these changes Dec 16, 2025

View reviewed changes

ryanaiagent self-assigned this Dec 16, 2025

chore: Run autoformat.sh to fix import style

30bbad2

	GOOGLE_CLOUD_PROJECT={{ your project }}
	GOOGLE_CLOUD_PROJECT=<your-gcp-project-id>

docs: Add PostgreSQL session storage sample and documentation #3926

Are you sure you want to change the base?

docs: Add PostgreSQL session storage sample and documentation #3926

Uh oh!

Conversation

hiroakis commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Link to Issue or Description of Change

Testing Plan

Checklist

Additional context

Uh oh!

gemini-code-assist bot commented Dec 16, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

hiroakis Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

hiroakis Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

hiroakis Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

hiroakis commented Dec 16, 2025

Uh oh!

AlejandroBlanco2001 commented Dec 16, 2025

Uh oh!

ryanaiagent commented Dec 17, 2025

Uh oh!

hiroakis commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hiroakis commented Dec 16, 2025 •

edited

Loading