NAME

Apache::Session::DBI - Store client sessions in your DBMS

SYNOPSIS

use Apache::Session::DBI

DESCRIPTION

This is a DBI storage subclass for Apache::Session. Client state is stored in a database via the DBI module. Try perldoc Session for more info.

INSTALLATION

Getting started

The first thing that you will need to do is select a database for use by this package. The primary concerns are transaction support and the atomicity of the INSERT statement. If your DBMS's INSERT is non-atomic, there is the possibility that the locking mechanism employed here will not work. Transaction support is not critical, but it can help stop the madness when something goes awry.

You will need to create two tables in your database for Session::DBI to use. They are named "sessions" and "locks". Sessions should have four columns, "id", "expires", "length", and "session", where id is the primary key or unique index. id should have a datatype of CHAR(n), where n is the length of your session id (default 16). The column "session" needs to be a variable-length field which can hold ASCII data. Depending on you DBMS, "session" will be of type TEXT or LONG. A typical SQL statement to setup this table might look like:

 CREATE TABLE sessions (
   id CHAR(16) NOT NULL, 
   expires INTEGER,
   length INTEGER,
   a_session TEXT, 
   PRIMARY KEY ( id ) 
 )

The "expires" column is largely ignored by the module. Since the module does not actively garbage collect, this column is conveniently provided so that you can clean out your sessions table occassionally.

The table "locks" needs only one column, "id", which is identical to the id in "sessions". It is essential that "id" be a unique index. For example:

 CREATE TABLE locks (
   id CHAR(16) NOT NULL,
   PRIMARY KEY ( id )
 )

Now, build, test, and install DBI, Apache::DBI, DBD::yourdbms, MD5, and FreezeThaw. Apache::DBI is not actually required, but it is recommended. Finally, build and install Apache::Session.

Environment

You will need to configure your environment to get Session::DBI to work. You should define:

SESSION_DBI_DATASOURCE

This is the DBI datasource string used in DBI->connect(), which is usually in the form DBI:vendor:databasename.

SESSION_DBI_USERNAME

The username used to connect to the datasourse. The user must have SELECT, UPDATE, INSERT, and DELETE priviledges.

SESSION_DBI_PASSWORD

The password that corresponds to the user from above.

I define these variables in my httpd.conf:

 PerlSetEnv SESSION_DBI_DATASOURCE DBI:mysql:sessions
 PerlSetEnv SESSION_DBI_USERNAME jeff
 PerlSetEnv SESSION_DBI_PASSWORD password
 

USAGE

This package complies with the API defined by Apache::Session. For details, please see that package's documentation.

The default for autocommit in Apache::Session::DBI is 0, which means that you will need to either call $session->store() when you are done or set autocommit to 1 via the open() and new() functions. (Note: This autocommit is separate from DBI's AutoCommit).

NOTES

I used FreezeThaw to serialize data structures here. Storable is faster. However, FreezeThaw returns ASCII strings which play nicely with all known databases, while Storable generates binary scalars which are less friendly. In particular, Storable-generated scalars cannot be thawed out of an mSQL database. If you are using a database such as Oracle or mysql, you may want to replace use FreezeThaw with use Storable at the top of DBI.pm. Actually, Storable's byte-order-independent nfreeze would be a better choice.

AUTHORS

Jeffrey Baker <jeff@godzilla.tamu.edu>, author and maintainer.

Redistribute under the Perl Artistic License.