.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "CGI::Session::Driver::DBI 3"
.TH CGI::Session::Driver::DBI 3 2026-06-30 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
CGI::Session::Driver::DBI \- Base class for native DBI\-related CGI::Session drivers
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    require CGI::Session::Driver::DBI;
\&    @ISA = qw( CGI::Session::Driver::DBI );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
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\*(Aqs exactly what sqlite does. The only reason why this class doesn\*(Aqt suit for a valid driver is its name isn\*(Aqt in lowercase. I\*(Aqm serious!
.SS NOTES
.IX Subsection "NOTES"
CGI::Session::Driver::DBI defines \fBinit()\fR method, which makes DBI handle available for drivers in \fIHandle\fR \- object attribute regardless of what \f(CW\*(C`\e%dsn_args\*(C'\fR were used in creating session object. Should your driver require non\-standard initialization you have to re\-define \fBinit()\fR method in your \fI.pm\fR file, but make sure to set \*(AqHandle\*(Aq \- object attribute to database handle (returned by DBI\->connect(...)) if you wish to inherit any of the methods from CGI::Session::Driver::DBI.
.SH STORAGE
.IX Header "STORAGE"
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:
.PP
.Vb 4
\&    CREATE TABLE sessions (
\&        id CHAR(32) NOT NULL PRIMARY KEY,
\&        a_session TEXT NOT NULL
\&    );
.Ve
.PP
Your session table can define additional columns, but the above two are required. Name of the session table is expected to be \fIsessions\fR by default. You may use a different name if you wish. To do this you have to pass \fITableName\fR as part of your \f(CW\*(C` \e%dsn_args \*(C'\fR:
.PP
.Vb 6
\&    $s = CGI::Session\->new(\*(Aqdriver:sqlite\*(Aq, undef, {TableName=>\*(Aqmy_sessions\*(Aq});
\&    $s = CGI::Session\->new(\*(Aqdriver:mysql\*(Aq, undef,
\&    {
\&        TableName=>\*(Aqmy_sessions\*(Aq,
\&        DataSource=>\*(Aqdbi:mysql:shopping_cart\*(Aq.
\&    });
.Ve
.PP
To use different column names, change the \*(Aqcreate table\*(Aq statement, and then simply do this:
.PP
.Vb 7
\&    $s = CGI::Session\->new(\*(Aqdriver:pg\*(Aq, undef,
\&    {
\&        TableName=>\*(Aqsession\*(Aq,
\&        IdColName=>\*(Aqmy_id\*(Aq,
\&        DataColName=>\*(Aqmy_data\*(Aq,
\&        DataSource=>\*(Aqdbi:pg:dbname=project\*(Aq,
\&    });
.Ve
.PP
or
.PP
.Vb 7
\&    $s = CGI::Session\->new(\*(Aqdriver:pg\*(Aq, undef,
\&    {
\&        TableName=>\*(Aqsession\*(Aq,
\&        IdColName=>\*(Aqmy_id\*(Aq,
\&        DataColName=>\*(Aqmy_data\*(Aq,
\&        Handle=>$dbh,
\&    });
.Ve
.SH "DRIVER ARGUMENTS"
.IX Header "DRIVER ARGUMENTS"
Following driver arguments are supported:
.IP DataSource 4
.IX Item "DataSource"
First argument to be passed to DBI\->\fBconnect()\fR. If the driver makes
the database connection itself, it will also explicitly disconnect from the database when 
the driver object is DESTROYed.
.IP User 4
.IX Item "User"
User privileged to connect to the database defined in \f(CW\*(C`DataSource\*(C'\fR.
.IP Password 4
.IX Item "Password"
Password of the \fIUser\fR privileged to connect to the database defined in \f(CW\*(C`DataSource\*(C'\fR
.IP Handle 4
.IX Item "Handle"
An existing DBI database handle object. The handle can be created on demand
by providing a code reference as a argument, such as \f(CW\*(C`<sub{DBI\-\*(C'\fRconnect}>>.
This way, the database connection is only created if it actually needed. This can be useful
when combined with a framework plugin like CGI::Application::Plugin::Session, which creates
a CGI::Session object on demand as well.
.Sp
\&\f(CW\*(C`Handle\*(C'\fR will override all the above arguments, if any present.
.IP TableName 4
.IX Item "TableName"
Name of the table session data will be stored in.
.SH LICENSING
.IX Header "LICENSING"
For support and licensing information see CGI::Session