serverpod-sessions

Serverpod Sessions

A Session provides access to database, cache, storage, messages, passwords, and logging. The framework creates and closes sessions automatically; only InternalSession requires manual management. Do not store a request session for work that outlives the request/stream/future call.

Session types

Type	Created for	Lifetime
MethodCallSession	Endpoint methods	Single request
WebCallSession	Web server routes	Single request
MethodStreamSession	Stream methods	Stream duration
FutureCallSession	Future calls	Task execution
InternalSession	Manual creation	Until closed

Manual sessions (InternalSession)

Prefer withSession, which closes the session for you and attaches the error and stack trace to the logs if the callback throws:

await Serverpod.instance.withSession((session) async {
  await doWork(session);
});

When the lifetime cannot be expressed as a callback, create the session manually and always close it in a finally block:

var session = await Serverpod.instance.createSession();
try {
  await doWork(session);
} finally {
  await session.close();
}

Unclosed sessions leak memory and never persist logs. Using a closed session throws StateError.

Cleanup callbacks

session.addWillCloseListener((session) async {
  // Runs just before session closes (all session types)
});

Common pitfall: using session after method returns

Sessions close when the endpoint returns. Do not capture for later use:

// BAD — session already closed when callback runs
Timer(Duration(seconds: 5), () => user.updateLastSeen(session));

Fix: Use a future call (session.serverpod.futureCalls.callWithDelay(...)) or open a new session inside the callback with Serverpod.instance.withSession(...).