# 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 <jaitken@cpan.org>



# 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.