serverpod/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 | | StreamingSession | WebSocket connections | Connection duration | | FutureCallSession | Future calls | Task execution | | InternalSession | Manual creation | Until closed |

Manual sessions (InternalSession)

Always close 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 create a new InternalSession inside the callback and close it in finally.