Package org.springframework.ai.session.jdbc

Class JdbcSessionRepository

java.lang.Object

org.springframework.ai.session.jdbc.JdbcSessionRepository

All Implemented Interfaces:

SessionRepository

public final class JdbcSessionRepository
extends Object
implements SessionRepository

The SessionRepository on a relational database: AI_SESSION (id, expiry, metadata JSON, event version), AI_SESSION_INDEX (the indexed metadata attributes, one row per attribute) and AI_SESSION_EVENT (the log, ordered by a database-assigned seq). The schema scripts are under classpath:org/springframework/ai/session/jdbc/.

On every save the metadata entries whose keys are indexed, the principal by default, are copied into AI_SESSION_INDEX, on the first 512 characters of the value, and findByMetadata(java.lang.String, java.lang.String) is one query over that table, with the whole value checked on the sessions it returns. An event is stored in the four columns SessionEventCodec defines: the event type, the message type, the message text, its own column so a store can search it, and a JSON payload.

The event_version column of AI_SESSION advances on every appendEvent(org.springframework.ai.session.SessionEvent) that appends a new event and on every successful appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long), which claims the version with UPDATE … WHERE event_version = ? before inserting. appendEvent(org.springframework.ai.session.SessionEvent) looks the event id up under that row lock before inserting, so a replay is a no-op without a duplicate-key error, which would mark a caller's surrounding transaction rollback-only, or abort it on PostgreSQL. A read of the active view selects the newest COMPACTION row, fetches the rows it names plus every row from it on, and lets EventFilter.apply(List) order, filter and window them. Every mutation runs in a TransactionTemplate; the class is thread-safe as the DataSource is.

Since:

2.1.0

Author:

Christian Tzolov

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	JdbcSessionRepository.Builder	Builds a JdbcSessionRepository on a DataSource or a JdbcTemplate; everything else has a default.

Field Summary

Fields

Modifier and Type	Field	Description
static final Set<String>	DEFAULT_INDEXED_ATTRIBUTES	The metadata keys every repository indexes: the principal.
static final int	MAX_INDEXED_VALUE_LENGTH	The number of leading characters of a metadata value the index row holds: with four bytes per character on MySQL, the (attr_name, attr_value) index stays under InnoDB's key limit.

Method Summary

Modifier and Type	Method	Description
void	appendEvent(SessionEvent event)	Appends one event to the log of the session named by SessionEvent.getSessionId().
boolean	appendEvents(String sessionId, List<SessionEvent> events, long expectedVersion)	Appends several events in order, atomically, only if the log's version equals expectedVersion; otherwise nothing is written and false is returned.
static JdbcSessionRepository.Builder	builder()	Returns a new JdbcSessionRepository.Builder.
void	delete(String sessionId)	Deletes the session and its events.
int	deleteExpiredSessions(Instant before)	Deletes every session that expired before the given instant, with their events, in one atomic step per session, so a session whose expiry was extended concurrently (SessionRepository.save(org.springframework.ai.session.Session)) is kept.
@Nullable Session	findById(String sessionId)
List<Session>	findByMetadata(String name, String value)	The sessions whose metadata holds value under name, oldest first (creation time, then id).
List<SessionEvent>	findEvents(String sessionId, EventFilter filter)	The events of the session the filter selects, oldest first; an empty list for a session that does not exist.
long	getEventVersion(String sessionId)	The version of the session's log, advanced on every SessionRepository.appendEvent(org.springframework.ai.session.SessionEvent) that appends a new event and on every successful SessionRepository.appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long); 0 for a session that does not exist or has no events.
Set<String>	getIndexedAttributes()	The metadata keys this repository indexes; see findByMetadata(java.lang.String, java.lang.String).
Session	save(Session session)	Persists session metadata (create or update).
boolean	saveIfAbsent(Session session)	Inserts the session unless one with the same id exists, atomically: a primary-key-guarded INSERT, or a compare-and-set put.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MAX_INDEXED_VALUE_LENGTH

public static final int MAX_INDEXED_VALUE_LENGTH

The number of leading characters of a metadata value the index row holds: with four bytes per character on MySQL, the (attr_name, attr_value) index stays under InnoDB's key limit. The row is a prefix index: findByMetadata(java.lang.String, java.lang.String) compares the whole value on the sessions the query returns, so two values that share their first 512 characters are told apart.

See Also:

• Constant Field Values

DEFAULT_INDEXED_ATTRIBUTES

public static final Set<String> DEFAULT_INDEXED_ATTRIBUTES

The metadata keys every repository indexes: the principal.

Method Details

getIndexedAttributes

public Set<String> getIndexedAttributes()

The metadata keys this repository indexes; see findByMetadata(java.lang.String, java.lang.String).

save

public Session save(Session session)

Description copied from interface: SessionRepository

Persists session metadata (create or update). If the session already exists its event log and its original Session.createdAt() are preserved; the other metadata fields are replaced.

Specified by:

save in interface SessionRepository

Returns:

the saved session

saveIfAbsent

public boolean saveIfAbsent(Session session)

Description copied from interface: SessionRepository

Inserts the session unless one with the same id exists, atomically: a primary-key-guarded INSERT, or a compare-and-set put. SessionService.create(org.springframework.ai.session.CreateSessionRequest) relies on it, so two concurrent creates of one id cannot both succeed.

Specified by:

saveIfAbsent in interface SessionRepository

Returns:

true if the session was inserted, false if one with the same id exists; the existing session is left untouched

findById

public @Nullable Session findById(String sessionId)

Specified by:

findById in interface SessionRepository

findByMetadata

public List<Session> findByMetadata(String name,
 String value)

Description copied from interface: SessionRepository

The sessions whose metadata holds value under name, oldest first (creation time, then id). The one scoped lookup of the store, in the shape of Spring Session's findByIndexNameAndIndexValue: the store indexes attributes and has no notion of ownership. Every store indexes SessionAttributes.PRINCIPAL_NAME; a store that cannot index every key documents which others it answers for.

Specified by:

findByMetadata in interface SessionRepository

Parameters:

name - the metadata key

value - the value, compared as a string

deleteExpiredSessions

public int deleteExpiredSessions(Instant before)

Description copied from interface: SessionRepository

Deletes every session that expired before the given instant, with their events, in one atomic step per session, so a session whose expiry was extended concurrently (SessionRepository.save(org.springframework.ai.session.Session)) is kept.

Specified by:

deleteExpiredSessions in interface SessionRepository

Parameters:

before - the expiry cut-off

Returns:

the number of sessions deleted

delete

public void delete(String sessionId)

Description copied from interface: SessionRepository

Deletes the session and its events.

Specified by:

delete in interface SessionRepository

appendEvent

public void appendEvent(SessionEvent event)

Description copied from interface: SessionRepository

Appends one event to the log of the session named by SessionEvent.getSessionId().

Idempotent by id: an event whose id is already in the session's log is a retried append and a no-op, neither a duplicate nor an error, and the version is not advanced. A caller that wants to retry safely supplies its own id rather than the builder's random one. Event ids are unique across sessions: a persistent store keys events by id alone and rejects an id used by another session rather than dropping the event.

Specified by:

appendEvent in interface SessionRepository

appendEvents

public boolean appendEvents(String sessionId,
 List<SessionEvent> events,
 long expectedVersion)

Description copied from interface: SessionRepository

Appends several events in order, atomically, only if the log's version equals expectedVersion; otherwise nothing is written and false is returned. On success the version advances once, whatever the number of events. This is how a compaction is recorded: one EventType.COMPACTION boundary and its summary events, with the version check keeping two concurrent compactions from both landing. Read SessionRepository.getEventVersion(java.lang.String) before SessionRepository.findEvents(java.lang.String, org.springframework.ai.session.EventFilter), then pass that version here.

Specified by:

appendEvents in interface SessionRepository

Parameters:

sessionId - the session whose log is appended to; every event must belong to it

events - the events, in order; at least one, with ids that are new to the log

expectedVersion - the version the caller read

Returns:

true when the events were appended, false when the version did not match

getEventVersion

public long getEventVersion(String sessionId)

Description copied from interface: SessionRepository

The version of the session's log, advanced on every SessionRepository.appendEvent(org.springframework.ai.session.SessionEvent) that appends a new event and on every successful SessionRepository.appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long); 0 for a session that does not exist or has no events. Read it before SessionRepository.findEvents(java.lang.String, org.springframework.ai.session.EventFilter), so that the version passed to SessionRepository.appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long) is not newer than the events read.

Specified by:

getEventVersion in interface SessionRepository

findEvents

public List<SessionEvent> findEvents(String sessionId,
 EventFilter filter)

Description copied from interface: SessionRepository

The events of the session the filter selects, oldest first; an empty list for a session that does not exist.

A EventFilter.Window.Last window returns the newest N matching events, extended back to the start of the turn it lands in (the nearest preceding turn start among the matches), so a tool call is never returned without its results; the extension is skipped when no turn start precedes the window. With EventFilter.activeView() the filter applies to the active view, the events the newest EventType.COMPACTION boundary names and everything appended after it, rather than to the whole log.

EventFilter.apply(List) is the reference implementation of both. A store pushes the criteria and the window down to its query, so that a read does not cost the whole log, and may fetch only the rows a view can contain and hand them to apply, as JdbcSessionRepository does.

Specified by:

findEvents in interface SessionRepository

builder

public static JdbcSessionRepository.Builder builder()

Returns a new JdbcSessionRepository.Builder.