Configuration guide¶

Overview¶

You can configure session factory in 2 steps:

Pick desired session features and add corresponding SQL Alchemy ORM Classes (Mixins) to the bases list of your model.

The library will detect mixin combination and enable corresponding session features.
Note

It’s much better to exclude mixins of features that you are not planning to use:
- your database will save some resources
- the library will run a bit less code
- if you accidentally try to enable a timeout setting that depends on a missing mixin, you will get explicit error at startup instead of a runtime error.
Apply session settings - globally, or per-session (if the setting is configurable at runtime). Global settings are provided at startup, and per-session settings use global settings as defaults. In case global settings are not provided, library defaults will be used as globals. (see Configuration settings reference)

Note

Timeout-related features have settings also deciding if the feature is enabled or not:

idle_timeout
absolute_timeout
renewal_timeout

For these features, even if corresponding mixin is included, the feature will not work when the setting value is None.

Model configuration¶

In the following example we configure a session storing user ID, having non-runtime-configurable Absolute Timeout and runtime-configurable Idle Timeout. The example also showcases:

ability to customize model columns - we use UUID as User ID instead of the default integer.
eager-loading of the user object.

from sqlalchemy import (
  Column,
  ForeignKey,
)
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import relationship
from pyramid_sqlalchemy_sessions import (
    BaseMixin,
    UseridMixin,
    AbsoluteMixin,
    ConfigIdleMixin,
)
# Using default declarative Base provided by the cookiecutter.
from .meta import Base

class Session(
    UseridMixin,
    AbsoluteMixin,
    ConfigIdleMixin,
    BaseMixin,
    Base,
    ):
    __tablename__ = 'session'

    userid = Column(UUID(as_uuid=True), ForeignKey('user.id'))
    # user instance loaded automatically when user is logged in.
    user = relationship('User', backref='sessions', lazy='joined')

Note

Runtime-configurable features mixins subclass their non-configurable versions, so you don’t need to include both.

Tip

Don’t forget to add DB indexes to your session table! The library doesn’t provide one, as it’s difficult to create universal index solution for all mixin configurations and different DB engines.

Working with settings¶

Some settings only meant to be set once and forgotten, such as cookie_name or dbsession_name. But most other settings are accessable and even configurable at runtime (if the corresponding session model mixin is enabled).

You can access current session settings using the settings object:

# Read
idle_timeout = request.session.settings.idle_timeout
# Settings is also a dict-like object.
absolute_timeout = request.session.settings['absolute_timeout']

By default you can only read the settings. But when you enable a runtime-configurable feature, it’s settings can be changed also:

# Suppose configurable cookie settings feature is enabled.
# You need to put settings in editable mode first.
request.session.settings.edit()
request.session.settings.cookie_max_age = 12345
# When you are done, you need to save it.
# Settings are always validated before saving.
request.session.settings.save()
# You can use settings as context manager so that edit and save
# is called automatically
with request.session.settings as s:
    s['cookie_max_age'] = 54321

Note

Currently changing of settings works only for a new session, otherwise you will get a SettingsError exception.

Note

The session implementation provided by the library is lazy, and will not persist clean session, so any changes of settings for such sessions also won’t be persisted in the DB.