---
name: "CGI::Session::Driver::DBI"
section: "3pm"
platform: "linux"
package: "perl-cgi-session"
version: "4.49-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/CGI::Session::Driver::DBI"
---

# CGI::Session::Driver::DBI(3pm)

Base class for native DBI-related CGI::Session drivers

## NAME

CGI::Session::Driver::DBI - Base class for native DBI-related CGI::Session drivers

## SYNOPSIS

```
    require CGI::Session::Driver::DBI;
    @ISA = qw( CGI::Session::Driver::DBI );
```

## 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's exactly what 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!

### NOTES

CGI::Session::Driver::DBI defines **init()** method, which makes DBI handle available for drivers in *Handle* - object attribute regardless of what `"\%dsn_args"` were used in creating session object. Should your driver require non-standard initialization you have to re-define **init()** method in your *.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.

## 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:

```
    CREATE TABLE sessions (
        id CHAR(32) NOT NULL PRIMARY KEY,
        a_session TEXT NOT NULL
    );
```

Your session table can define additional columns, but the above two are required. Name of the session table is expected to be *sessions* by default. You may use a different name if you wish. To do this you have to pass *TableName* as part of your `" \%dsn_args "`:

```
    $s = CGI::Session->new('driver:sqlite', undef, {TableName=>'my_sessions'});
    $s = CGI::Session->new('driver:mysql', undef,
    {
        TableName=>'my_sessions',
        DataSource=>'dbi:mysql:shopping_cart'.
    });
```

To use different column names, change the 'create table' statement, and then simply do this:

```
    $s = CGI::Session->new('driver:pg', undef,
    {
        TableName=>'session',
        IdColName=>'my_id',
        DataColName=>'my_data',
        DataSource=>'dbi:pg:dbname=project',
    });
```

or

```
    $s = CGI::Session->new('driver:pg', undef,
    {
        TableName=>'session',
        IdColName=>'my_id',
        DataColName=>'my_data',
        Handle=>$dbh,
    });
```

## DRIVER ARGUMENTS

Following driver arguments are supported:

- DataSource

  First argument to be passed to DBI-\>**connect()**. If the driver makes the database connection itself, it will also explicitly disconnect from the database when  the driver object is DESTROYed.

- User

  User privileged to connect to the database defined in `"DataSource"`.

- Password

  Password of the *User* privileged to connect to the database defined in `"DataSource"`

- Handle

  An existing DBI database handle object. The handle can be created on demand by providing a code reference as a argument, such as `"<sub{DBI-"`connect}\>\>. 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.

  `"Handle"` will override all the above arguments, if any present.

- TableName

  Name of the table session data will be stored in.

## LICENSING

For support and licensing information see CGI::Session