data/TWiki/CGISessionDriverDBIDotPm.txt
changeset 0 414e01d06fd5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/CGISessionDriverDBIDotPm.txt	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,76 @@
     1.4 +---+ Package ==
     1.5 +
     1.6 +%TOC%
     1.7 +=head1 NAME
     1.8 +
     1.9 +CGI::Session::Driver::DBI - Base class for native DBI-related CGI::Session drivers
    1.10 +
    1.11 +=head1 SYNOPSIS
    1.12 +
    1.13 +    require CGI::Session::Driver::DBI;
    1.14 +    @ISA = qw( CGI::Session::Driver::DBI );
    1.15 +
    1.16 +=head1 DESCRIPTION
    1.17 +
    1.18 +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!
    1.19 +
    1.20 +=head2 NOTES
    1.21 +
    1.22 +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.
    1.23 +
    1.24 +=head1 STORAGE
    1.25 +
    1.26 +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:
    1.27 +
    1.28 +    CREATE TABLE sessions (
    1.29 +        id CHAR(32) NOT NULL PRIMARY KEY,
    1.30 +        a_session TEXT NOT NULL
    1.31 +    );
    1.32 +
    1.33 +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 >:
    1.34 +
    1.35 +    $s = new CGI::Session("driver:sqlite", undef, {TableName=>'my_sessions'});
    1.36 +    $s = new CGI::Session("driver:mysql", undef, {
    1.37 +                                        TableName=>'my_sessions', 
    1.38 +                                        DataSource=>'dbi:mysql:shopping_cart'});
    1.39 +
    1.40 +=head1 DRIVER ARGUMENTS
    1.41 +
    1.42 +Following driver arguments are supported:
    1.43 +
    1.44 +=over 4
    1.45 +
    1.46 +=item DataSource
    1.47 +
    1.48 +First argument to be passed to L<DBI|DBI>->L<connect()|DBI/connect()>. If the driver makes
    1.49 +the database connection itself, it will also explicitly disconnect from the database when 
    1.50 +the driver object is DESTROYed.
    1.51 +
    1.52 +=item User
    1.53 +
    1.54 +User privileged to connect to the database defined in C<DataSource>.
    1.55 +
    1.56 +=item Password
    1.57 +
    1.58 +Password of the I<User> privileged to connect to the database defined in C<DataSource>
    1.59 +
    1.60 +=item Handle
    1.61 +
    1.62 +An existing L<DBI> database handle object. The handle can be created on demand
    1.63 +by providing a code reference as a argument, such as C<<sub{DBI->connect}>>.
    1.64 +This way, the database connection is only created if it actually needed. This can be useful
    1.65 +when combined with a framework plugin like L<CGI::Application::Plugin::Session>, which creates
    1.66 +a CGI::Session object on demand as well. 
    1.67 +
    1.68 +C<Handle> will override all the above arguments, if any present.
    1.69 +
    1.70 +=item TableName
    1.71 +
    1.72 +Name of the table session data will be stored in.
    1.73 +
    1.74 +=back
    1.75 +
    1.76 +=head1 LICENSING
    1.77 +
    1.78 +For support and licensing information see L<CGI::Session|CGI::Session>
    1.79 +