NAME

Catalyst::Plugin::Session::Store::DBI - Store your sessions in a database

SYNOPSIS

    # Create a table in your database for sessions
    CREATE TABLE sessions (
        id           char(72) primary key,
        session_data text,
        expires      int(10)
    );

    # In your app
    use Catalyst qw/Session Session::Store::DBI Session::State::Cookie/;
    
    # Connect directly to the database
    MyApp->config('Plugin::Session' => {
        expires   => 3600,
        dbi_dsn   => 'dbi:mysql:database',
        dbi_user  => 'foo',
        dbi_pass  => 'bar',
        dbi_table => 'sessions',
        dbi_id_field => 'id',
        dbi_data_field => 'session_data',
        dbi_expires_field => 'expires',
    });
    
    # Or use an existing database handle from a DBIC/CDBI class
    MyApp->config('Plugin::Session' => {
        expires   => 3600,
        dbi_dbh   => 'DBIC', # which means MyApp::Model::DBIC
        dbi_table => 'sessions',
        dbi_id_field => 'id',
        dbi_data_field => 'session_data',
        dbi_expires_field => 'expires',
    });

    # ... in an action:
    $c->session->{foo} = 'bar'; # will be saved

DESCRIPTION

This storage module will store session data in a database using DBI.

CONFIGURATION

These parameters are placed in the configuration hash under the Plugin::Session key.

expires

The expires column in your table will be set with the expiration value. Note that no automatic cleanup is done on your session data, but you can use the delete_expired_sessions method to perform clean up. You can make use of the Catalyst::Plugin::Scheduler plugin to schedule automated session cleanup.

dbi_dbh

Set this to an existing $dbh or the class name of a DBIx::Class, Class::DBI, Rose::DB::Object, or Catalyst::Model::DBI model. DBIx::Class schema is also supported by setting dbi_dbh to the name of your schema model.

This method is recommended if you have other database code in your application as it will avoid opening additional connections.

dbi_dsn

dbi_user

dbi_pass

dbi_options

To connect directly to a database, specify the necessary dbi_dsn, dbi_user, and dbi_pass options. If you need to supply your own options to DBI, you may do so by passing a hashref to dbi_options. The default options are AutoCommit => 1 and RaiseError => 1.

dbi_table

Enter the table name within your database where sessions will be stored. This table must have at least 3 columns, id, session_data, and expires. See the Schema section below for additional details. The table name defaults to 'sessions'.

dbi_id_field

The name of the field on your sessions table which stores the session ID. Defaults to id.

dbi_data_field

The name of the field on your sessions table which stores session data. Defaults to session_data.

dbi_expires_field

The name of the field on your sessions table which stores the expiration time of the session. Defaults to expires.

SCHEMA

Your 'sessions' table must contain at minimum the following 3 columns:

    id           char(72) primary key
    session_data text
    expires      int(10)

The 'id' column should probably be 72 characters. It needs to handle the longest string that can be returned by "generate_session_id" in Catalyst::Plugin::Authentication, plus another 8 characters for internal use. This is less than 72 characters in practice when SHA-1 or MD5 are used, but SHA-256 will need all those characters.

The 'session_data' column should be a long text field. Session data is encoded using Base64 before being stored in the database.

Note that MySQL TEXT fields only store 64KB, so if your session data will exceed that size you'll want to move to MEDIUMTEXT, MEDIUMBLOB, or larger.

The 'expires' column stores the future expiration time of the session. This may be null for per-user and flash sessions.

NOTE: Your column names do not need to match with this schema, use config to set custom column names.

METHODS

get_session_data

store_session_data

delete_session_data

delete_expired_sessions

setup_session

These are implementations of the required methods for a store. See Catalyst::Plugin::Session::Store.

session_store_dbi_table

Return the configured table name.

session_store_dbi_id_field

Return the configured ID field name.

session_store_dbi_data_field

Return the configured data field name.

session_store_dbi_expires_field

Return the configured expires field name.

INTERNAL METHODS

prepare

setup_actions

SEE ALSO

Catalyst, Catalyst::Plugin::Session, Catalyst::Plugin::Scheduler

AUTHOR

Andy Grundman, <andy@hybridized.org>

COPYRIGHT

Copyright (c) 2005 - 2009 the Catalyst::Plugin::Session::Store::DBI "AUTHOR" as listed above.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.