Session Storage

Posit Workbench keeps track of information about each user’s active sessions. The homepage uses this metadata to display and manage the list of sessions.

By default, session metadata is stored on the file system in the user’s home directory. Workbench can instead store session metadata in the internal database by using the following configuration option:

/etc/rstudio/rserver.conf

session-use-file-storage=0

Steps to change session metadata storage

To avoid unexpected behavior, follow this procedure when changing the session-use-file-storage option:

Ensure that all users have fully quit their sessions.
Stop Workbench and the Launcher using sudo rstudio-server stop and sudo rstudio-launcher stop.
Add or modify the session-use-file-storage option in /etc/rstudio/rserver.conf.
Start Workbench and the Launcher using sudo rstudio-server start and sudo rstudio-launcher start.

Note

Even when Workbench is configured to store session metadata in the database, sessions will continue to store some data (for example, RStudio suspended session data) in the file system for their own use. Do not remove the files in .local/share/rstudio.

Reverting back to file storage

If you previously set session-use-file-storage=0 in rserver.conf to enable database storage, you can revert back to using file storage. Before reverting back to file storage, consider the Expected behavior after reverting back to file storage section below.

If you would like to revert back to file storage, follow the steps in Steps to change session metadata storage. For step 2, either set session-use-file-storage=1, or remove the setting entirely from rserver.conf.

Expected behavior after reverting back to file storage:

These effects are all transient and a direct result of the migration. Once users open new sessions and reopen projects, the Workbench homepage will return to normal behavior.

RStudio sessions (both active and suspended) created under database storage will disappear from the homepage.
Jupyter, VS Code, and Positron sessions created under database storage will disappear from the homepage. Sessions that had an associated project might appear as Finished rather than disappearing entirely.
Sessions previously created under file storage might reappear on the homepage if their file-based metadata still exists on disk.
Some remaining or reappearing sessions might be missing names or metadata because metadata is not migrated from the database onto the file system. These can be cleaned up by quitting or closing the sessions or projects from the homepage.

Inform users that any sessions created while database storage was active must be relaunched after the revert. Previously suspended RStudio sessions created under database storage will need to be started fresh, as the suspension data stored in .local/share/rstudio cannot be associated with a new file-based session record.

Note

No user data is lost when reverting back to file storage. The only potential data loss is the metadata Workbench uses to keep track of sessions and projects, which is why sessions might disappear from the homepage.

As long as sessions are shut down before the migration, all user data and projects are accessible by launching a new session.

Networking considerations

Workbench only supports storing session metadata in the database for Launcher sessions. Ensure that the Launcher is enabled and properly configured before setting session-use-file-storage=0. For more information on configuring the Launcher, see the Server options section of the Launcher Configuration section.