data/TWiki/CGISessionDriverDBIDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 ---+ Package ==
     2 
     3 %TOC%
     4 =head1 NAME
     5 
     6 CGI::Session::Driver::DBI - Base class for native DBI-related CGI::Session drivers
     7 
     8 =head1 SYNOPSIS
     9 
    10     require CGI::Session::Driver::DBI;
    11     @ISA = qw( CGI::Session::Driver::DBI );
    12 
    13 =head1 DESCRIPTION
    14 
    15 In most cases you can create a new DBI-driven CGI::Session driver by simply creating an empty driver file that inherits from CGI::Session::Driver::DBI. That's exactly what L<sqlite|CGI::Session::Driver::sqlite> does. The only reason why this class doesn't suit for a valid driver is its name isn't in lowercase. I'm serious!
    16 
    17 =head2 NOTES
    18 
    19 CGI::Session::Driver::DBI defines init() method, which makes DBI handle available for drivers in I<Handle> - object attribute regardless of what C<\%dsn_args> were used in creating session object. Should your driver require non-standard initialization you have to re-define init() method in your F<.pm> file, but make sure to set 'Handle' - object attribute to database handle (returned by DBI->connect(...)) if you wish to inherit any of the methods from CGI::Session::Driver::DBI.
    20 
    21 =head1 STORAGE
    22 
    23 Before you can use any DBI-based session drivers you need to make sure compatible database table is created for CGI::Session to work with. Following command will produce minimal requirements in most SQL databases:
    24 
    25     CREATE TABLE sessions (
    26         id CHAR(32) NOT NULL PRIMARY KEY,
    27         a_session TEXT NOT NULL
    28     );
    29 
    30 Your session table can define additional columns, but the above two are required. Name of the session table is expected to be I<sessions> by default. You may use a different name if you wish. To do this you have to pass I<TableName> as part of your C< \%dsn_args >:
    31 
    32     $s = new CGI::Session("driver:sqlite", undef, {TableName=>'my_sessions'});
    33     $s = new CGI::Session("driver:mysql", undef, {
    34                                         TableName=>'my_sessions', 
    35                                         DataSource=>'dbi:mysql:shopping_cart'});
    36 
    37 =head1 DRIVER ARGUMENTS
    38 
    39 Following driver arguments are supported:
    40 
    41 =over 4
    42 
    43 =item DataSource
    44 
    45 First argument to be passed to L<DBI|DBI>->L<connect()|DBI/connect()>. If the driver makes
    46 the database connection itself, it will also explicitly disconnect from the database when 
    47 the driver object is DESTROYed.
    48 
    49 =item User
    50 
    51 User privileged to connect to the database defined in C<DataSource>.
    52 
    53 =item Password
    54 
    55 Password of the I<User> privileged to connect to the database defined in C<DataSource>
    56 
    57 =item Handle
    58 
    59 An existing L<DBI> database handle object. The handle can be created on demand
    60 by providing a code reference as a argument, such as C<<sub{DBI->connect}>>.
    61 This way, the database connection is only created if it actually needed. This can be useful
    62 when combined with a framework plugin like L<CGI::Application::Plugin::Session>, which creates
    63 a CGI::Session object on demand as well. 
    64 
    65 C<Handle> will override all the above arguments, if any present.
    66 
    67 =item TableName
    68 
    69 Name of the table session data will be stored in.
    70 
    71 =back
    72 
    73 =head1 LICENSING
    74 
    75 For support and licensing information see L<CGI::Session|CGI::Session>
    76