Serverpod Sessions#

한마디로 (비개발자용)#

세션(Session)은 서버가 한 가지 일을 처리하는 동안 들고 다니는 "출입증 겸 작업 가방"이라고 보면 됩니다. 이 가방 안에는 데이터베이스, 캐시, 저장소, 로그 같은 도구가 들어 있어, 서버가 요청 하나를 끝낼 때까지 필요한 것들을 꺼내 씁니다. 보통은 서버가 알아서 가방을 챙겨주고 끝나면 반납하지만, 직접 만든 가방(InternalSession)은 사람이 손수 반납해야 합니다. 이 문서는 그 가방을 언제 만들고 어떻게 제대로 닫는지를 설명합니다.

무엇을·언제 (비개발자용)#

• 무엇을 해주나: 세션의 종류, 생성·종료(생명주기), 직접 만드는 InternalSession, 닫히기 직전 처리(cleanup) 방법을 정리해 줍니다.
• 언제 쓰나:
  • 직접(수동으로) 세션을 만들어야 할 때
  • "세션이 이미 닫혔다"는 오류를 만나 원인을 찾을 때
  • 세션이 언제 만들어지고 언제 닫히는지 흐름을 이해하고 싶을 때
• 핵심 주의: 직접 만든 세션을 닫지 않으면 메모리가 새고 기록(로그)도 남지 않습니다. 그래서 "항상 닫기"가 중요합니다.

핵심 용어 (비개발자용)#

A Session provides access to database, cache, storage, messages, passwords, and logging. The framework creates and closes sessions automatically; only InternalSession requires manual management.

Session types#

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.