How SQLAlchemy sessions are handled in Galaxy

Access to the Session object registry

We have a central resource from which to grab the Session object registry see sessionmaker in the SQLAlchemy documentation, that is app.model.session. You can either use it directly as a proxy to the current session or call app.model.session() to get the proxied Session object, or use the context manager (e.g. with app.model.session() as session:), as detailed in the SQLAlchemy documentation.

Session object registry scopes

The default scope of the Session object registry is thread local. This means that accessing a Session through the Session object registry will return the same Session in the same thread. This default scope can be changed if necessary.

WSGI, ASGI, Celery

In the context of the web app (WSGI and ASGI) there is a clearly delineated lifespan for a session, and that lifespan isn’t tied to a thread. The scope of the Session object registry is set at the beginning of a web request using app.model.set_request_id(request_id). At the end of a web request we remove the scope using app.model.unset_request_id(request_id). This also closes and removes any active Session object. Similarly, we set the scope for each Celery task execution using set_request_id and unset_request_id.

By using this mechanism we are certain that web requests and celery tasks receive a new Session object and that any resources held by the session are released.

Job and Workflow handlers

Job and Workflow handlers perform multiple pieces of business logic in separate threads and care needs to be taken when deciding when to start a transaction, when to do a rollback and if and where a session lifespan can be introduced.

The following paragraph discusses the choices made in https://github.com/galaxyproject/galaxy/blob/064360dab053426ce166bb7274d6a3a5790eb7cc/lib/galaxy/jobs/runners/__init__.py#L835-L843:

The JobHandlerQueue.monitor method is executed as a thread within the job handler process, and all work that requires access to the database is happening inside check_watched_items, which iterates over jobs assigned to this handler process. By setting the scope to a new, random uuid around check_watched_items we ensure that even if the session becomes corrupt the session is properly discarded and the next iteration of check_watched_items receives a new, clean session to work with. As the work within JobHandlerQueue.monitor is happening within a single thread it is not technically necessary to set a custom scope, and one could simply call app.model.session.close; however, there is very little cost associated to setting a custom scope and it becomes very clear where the session lifespan starts and ends.

As a guiding principle an attempt should be made to manage the session state and database-related exception handling as high up in the calling stack as possible.