# NAME

# NAME

Dancer::Session::DBI - DBI based session engine for Dancer

# SYNOPSIS

This module implements a session engine by serializing the session,
and storing it in a database via [DBI](http://search.cpan.org/perldoc?DBI). The default serialization method is [JSON](http://search.cpan.org/perldoc?JSON),
though one can specify any serialization format you want. [YAML](http://search.cpan.org/perldoc?YAML) and [Storable](http://search.cpan.org/perldoc?Storable) are
viable alternatives.

JSON was chosen as the default serialization format, as it is fast, terse, and portable.

Supported databases are MySQL > 4.1.1, PostgreSQL > 9.1, and SQLite > 3.0

# USAGE

In config.yml

session: "DBI"
session_options:
dsn: "DBI:mysql:database=testing;host=127.0.0.1;port=3306" # DBI Data Source Name
table: "sessions" # Name of the table to store sessions
user: "user" # Username used to connect to the database
password: "password" # Password to connect to the database

Alternatively, you can set the database handle in your application, by passing
an anonymous sub that returns an active DBH connection. Specifying a custom
serializer / deserializer is also possible

set 'session_options' => {
dbh => sub { DBI->connect( 'DBI:mysql:database=testing;host=127.0.0.1;port=3306', 'user', 'password' ); },
serializer => sub { YAML::Dump(@_); },
deserializer => sub { YAML::Load(@_); },
table => 'sessions',
};

The following schema is the minimum requirement.

CREATE TABLE `sessions` (
`id` CHAR(40) PRIMARY KEY,
`session_data` TEXT
);

If using a `Memory` table, you must use a `VARCHAR` type for the `session_data` field, as that
table type doesn't support `TEXT`

A timestamp field that updates when a session is updated is recommended, so you can expire sessions
server-side as well as client-side. You can do this in MySQL with the following SQL. Other database
engines are left as an exercise for the reader.

`last_active` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

This session engine will not automagically remove expired sessions on the server, but with a timestamp
field as above, you should be able to to do this manually.

# METHODS

## create()

Creates a new session. Returns the session object.

## flush()

Write the session to the database. Returns the session object.

## retrieve($id)

Look for a session with the given id.

Returns the session object if found, `undef` if not. Logs a warning if the
session was found, but could not be deserialized.

## destroy()

Remove the current session object from the database..

# SEE ALSO

[Dancer](http://search.cpan.org/perldoc?Dancer), [Dancer::Session](http://search.cpan.org/perldoc?Dancer::Session), [Plack::Session::Store::DBI](http://search.cpan.org/perldoc?Plack::Session::Store::DBI)

# AUTHOR

James Aitken <[email protected]>

# COPYRIGHT AND LICENSE

This software is copyright (c) James Aitken.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.