Persisting Session Backend State

Persisting state from your session backend

Session backends are useful for maintaining document state while a user session is active, but they require a way to store that data when a session has ended. Figma-like applications (opens in a new tab), for example, typically store documents in blob storage and load them into a session backend when the document is opened. This allows the session backend to act as the document's source of truth while syncing edits from multiple users.


Using locks when spawning a session backend ensures that a document or user only has one running session backend at a time. Learn more in our locks explainer.

There are several possible options for where to store documents and how to update them. We've described some of them below along with some of their trade-offs.


Blob storage (Recommended)

Persisting to your cloud's blob storage (e.g. AWS's S3 (opens in a new tab) or Google Cloud Storage (opens in a new tab)) can be a simple and cost-effective way to save state between sessions. To implement this approach, you'll likely want to do the following:

  1. Spawn a session backend with env vars that include what bucket to access and credentials to access it with.
  2. The session backend loads the bucket's contents into memory when it starts
  3. The session backend periodically persists updates to the bucket during the session
  4. The session backend listens for a SIGINT signal and ensures all changes have been persisted before it shuts down.

Generally, updates to blob storage cannot be appended to an existing document, but instead must replace the entire blob. This may present some challenges for very large documents. Still, these kinds of updates can potentially be very fast, especially if the session backends are running in the same cloud provider region as the blob storage. (See Jamsocket's Bring Your Own Compute offering (opens in a new tab).)

As with many of the approaches listed here, choosing how often you want to persist updates to storage depends on how large the files are, how often updates tend to occur for your application, and how quickly you need data to be durably persisted. (If your session backend encounters an error or is unexpectedly terminated, you may lose any updates that were not persisted since the last update to blob storage.)

Mounted volume

Another approach is to mount a cloud file storage product (e.g. AWS's EFS) into your session backend. These kinds of products, while much more expensive than blob storage, allow your session backend to simply act like it's writing to disk while EFS does the work of persisting the mounted volume's contents. This particular solution is only supported on the BYOC plan, so if you're interested in trying out this approach, drop us a note!

An existing database

While we tend to recommend the blob storage solution, your application may have some special requirements which mean documents must be persisted to an existing database. In these cases, the general approach of reading the document from the database when the session backend starts and periodically persisting updates back to the database is the same. As with most architectures, but especially for this kind of approach, you'll want to place an API in front of your database to avoid exceeding your database's connection limits.

Jamsocket is built by Drifting in Space.