NAME

Dancer2::Session::DatabasePlugin - Dancer2 Session implementation for databases

SYNOPSIS

  use Dancer2;
  use Dancer2::Plugin::Database;
  use Dancer2::Plugin::SessionDatabase;

DESCRIPTION

This class extends Dancer2::Core::Role::SessionFactory, and makes use of Dancer2::Plugin::Database for managing database connections.

CONFIGURATION

The session should be set to "DatabasePlugin" in order to use this session engine in your Dancer2 Application.

  session: "DatabasePlugin"

  engines:
    session:
      DatabasePlugin:
        connection: "foo"
        session_table: "SESSIONS"
        id_column:     "SESSION_ID"
        data_column:   "SESSION_DATA"

  plugins:
    Database:
      connections:
        foo:
          driver:   "SQLite"
          database: "foo.sqlite"

Expected Schema

The code was developed to use a table with 2 columns: SESSION_ID, SESSION_DATA, additional columns will not impact the code. No records are deleted unless the session destroy is called, so cleanup is something that may need to be done over time.

The sql statements are generated based on the configuration options, session_table, id_column, and data_column.

Example Schema

Testing and development was done using SQLite3.

Create statement is as follows:

  create table sessions (session_id varchar unique,session_data blob);

How Queries are generated

All queries are generated using sprintf statements against constatins.

Column SESSION_ID

This column must have constraint defining the values as unique. The id is a string representing the current session, internals from Dancer2::Core::Session seems to return a 32 byte long string. It is highly recommended this column be indexed.

Column SESSION_DATA

This field is expected to be a BLOB or binary data type, although a large text field should work. The data being written to this column is generated by using Storable::nfreeze($ref).

SQL Statements

All SQL Statements are generated based on the given configuration.

Insert

Default Query Shown:

  INSERT into SESSIONS (SESSION_ID,SESSION_DATA) values (?,?) 

Sprintf Template:

  INSERT into %s (%s,%s) values (?,?)

Update Existing session

Default Query Shown:

  UPDATE SESSIONS SET SESSION_DATA=? WHERE SESSION_ID=?

Sprintf Template:

  UPDATE %s SET %s=? WHERE %s=?

Delete

Default Query Shown:

  DELETE FROM SESSIONS WHERE SESSION_ID=?

Sprintf Template:

  DELETE FROM %s WHERE %s=?

SELECT Current Session

Default Query Shown:

  SELECT SESSION_DATA FROM SESSIONS WHERE SESSION_ID=?

Sprintf Template:

  SELECT %s FROM %s WHERE %s=?

SELECT All Session Keys

Default Query Shown:

  SELECT SESSION_ID FROM SESSIONS

Sprintf Template

  SELECT %s FROM %s

Rename Session

Default Query Shown:

  UPDATE SESSIONS SET SESSION_ID=? WHERE SESSION_ID=?

Sprintf Template:

  UPDATE %s SET %s=? WHERE %s=?

hooks

This package makes use of several exsting hooks and adds some new ones. This section documents those hooks.

Hooks Added

The following new Hooks were created to enable database functionality

Hook "engine.session.beforedb"

This Hook takes no arguments and is run before the session would connect to the database.

Hooks Used

This package makes use of hooks provdied by Dancer2::Database::Plugin.

"database_connection_lost"

This hook is used to clear the existing database statement handle cache.

"database_error"

This hook is used to clear the existing database statement handle cache.

"database_connected"

This hook is used to clear the existing database statement handle cache.

Notes

Session Compatibility

Once Dancer2::Session::DatabasePlugin is loaded it is not compatable with other configured session engines and will currently cause Your app to die, unless session is set to "DatabasePlugin".

Database Acces Pre-Fork

When accesiong sessions pre-fork, Databases Statement handles are cached in an anymous hash refrence at $Dancer2::Session::DatabasePlugin::CACHE. It is recommended that the cache be reset.

Example:

  %{$Dancer2::Session::DatabasePlugin::CACHE}=();

See Also

Dancer2::Plugin::Database Dancer2::Session::YAML

LICENSE

This softare is distributed under the Perl 5 License.

AUTHOR

Michael Shipper <AKALINUX@cpan.org>

cpanm Dancer2::Session::DatabasePlugin

perl -MCPAN -e shell
install Dancer2::Session::DatabasePlugin