TWiki/CGISessionDriverDBIDotPm.mdwn

   1 # <a name="Package &lt;code&gt;="></a> Package =
   2
   3 <div>
   4   <ul>
   5     <li><a href="#Package =="> Package ==</a></li>
   6   </ul>
   7 </div>
   8
   9 =head1 NAME
  10
  11 CGI::Session::Driver::DBI - Base class for native DBI-related CGI::Session drivers
  12
  13 =head1 SYNOPSIS
  14
  15 require CGI::Session::Driver::DBI; @ISA = qw( CGI::Session::Driver::DBI );
  16
  17 =head1 DESCRIPTION
  18
  19 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&lt;sqlite|CGI::Session::Driver::sqlite&gt; does. The only reason why this class doesn't suit for a valid driver is its name isn't in lowercase. I'm serious!
  20
  21 =head2 NOTES
  22
  23 CGI::Session::Driver::DBI defines init() method, which makes DBI handle available for drivers in I - object attribute regardless of what C&lt;\\%dsn\_args&gt; were used in creating session object. Should your driver require non-standard initialization you have to re-define init() method in your F&lt;.pm&gt; file, but make sure to set 'Handle' - object attribute to database handle (returned by DBI-&gt;connect(...)) if you wish to inherit any of the methods from CGI::Session::Driver::DBI.
  24
  25 =head1 STORAGE
  26
  27 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:
  28
  29 CREATE TABLE sessions ( id CHAR(32) NOT NULL PRIMARY KEY, a\_session TEXT NOT NULL );
  30
  31 Your session table can define additional columns, but the above two are required. Name of the session table is expected to be I by default. You may use a different name if you wish. To do this you have to pass I as part of your C&lt; \\%dsn\_args &gt;:
  32
  33 $s = new CGI::Session("driver:sqlite", undef, \{TableName=&gt;'my\_sessions'\}); $s = new CGI::Session("driver:mysql", undef, \{ [[TableName]]=&gt;'my\_sessions', [[DataSource]]=&gt;'dbi:mysql:shopping\_cart'\});
  34
  35 =head1 DRIVER ARGUMENTS
  36
  37 Following driver arguments are supported:
  38
  39 =over 4
  40
  41 =item [[DataSource]]
  42
  43 First argument to be passed to L&lt;DBI|DBI&gt;-&gt;L&lt;connect()|DBI/connect()&gt;. If the driver makes the database connection itself, it will also explicitly disconnect from the database when the driver object is DESTROYed.
  44
  45 =item User
  46
  47 User privileged to connect to the database defined in C.
  48
  49 =item Password
  50
  51 Password of the I privileged to connect to the database defined in C
  52
  53 =item Handle
  54
  55 An existing L database handle object. The handle can be created on demand by providing a code reference as a argument, such as C&lt;&lt;sub\{DBI-&gt;connect\}&gt;&gt;. This way, the database connection is only created if it actually needed. This can be useful when combined with a framework plugin like L&lt;CGI::Application::Plugin::Session&gt;, which creates a CGI::Session object on demand as well.
  56
  57 C will override all the above arguments, if any present.
  58
  59 =item [[TableName]]
  60
  61 Name of the table session data will be stored in.
  62
  63 =back
  64
  65 =head1 LICENSING
  66
  67 For support and licensing information see L&lt;CGI::Session|CGI::Session&gt;