# CGI::Session::PostgreSQL - PostgreSQL driver for CGI::Session
#
# Copyright (C) 2001-2002 Sherzod Ruzmetov, sherzodr@cpan.org
#
# Copyright (C) 2002 Cosimo Streppone, cosimo@cpan.org
# This module is based on CGI::Session::MySql module
# by Sherzod Ruzmetov, original author of CGI::Session modules
# and CGI::Session::MySQL driver.
#
# 2002/12/08 cosimo@cpan.org
# Initial release
# 2003/03/01 cosimo@cpan.org
# Added `FOR UPDATE' sql clauses to enable database row lock management
#
# $Id: PostgreSQL.pm,v 1.1.1.1 2003/08/02 23:39:34 takezoe Exp $
package CGI::Session::PostgreSQL;
use strict;
# Inheriting necessary functionalities from the
# following libraries. Do not change it unless you know
# what you are doing
use base qw(
CGI::Session
CGI::Session::ID::MD5
CGI::Session::Serialize::Default
);
# driver specific libraries should go below
use vars qw($VERSION $TABLE_NAME);
($VERSION) = '$Revision: 1.1.1.1 $' =~ m/Revision:\s*(\S+)/;
$TABLE_NAME = 'sessions';
########################
# Driver methods follow
########################
# stores the serialized data. Returns 1 for sucess, undef otherwise
sub store {
my ($self, $sid, $options, $data) = @_;
my $dbh = $self->PostgreSQL_dbh($options);
my $db_data;
eval {
($db_data) = $dbh->selectrow_array(
' SELECT a_session FROM '.$TABLE_NAME.
' WHERE id = '.$dbh->quote($sid).' FOR UPDATE'
);
};
if( $@ ) {
$self->error("Couldn't acquire data on id '$sid'");
return undef;
}
eval {
if( $db_data ) {
#warn('do update sid='.$sid.' data='.$self->freeze($data));
$dbh->do(
' UPDATE '.$TABLE_NAME.
' SET a_session='.$dbh->quote($self->freeze($data)).
' WHERE id='.$dbh->quote($sid)
);
} else {
#warn('do insert sid='.$sid.' data='.$self->freeze($data));
$dbh->do(
'INSERT INTO '.$TABLE_NAME.' (id,a_session) '.
'VALUES ('.$dbh->quote($sid).', '.$dbh->quote($self->freeze($data)).')'
);
}
};
if( $@ ) {
$self->error("Error in session update on id '$sid'. $@");
warn("Error in session update on id '$sid'. $@");
return undef;
}
return 1;
}
# retrieves the serialized data and deserializes it
sub retrieve {
my ($self, $sid, $options) = @_;
# after you get the data, deserialize it using
# $self->thaw(), and return it
my $dbh = $self->PostgreSQL_dbh($options);
my $data;
eval {
$data = $dbh->selectrow_array(
' SELECT a_session FROM '.$TABLE_NAME.
' WHERE id = '.$dbh->quote($sid)
);
};
if( $@ ) {
$self->error("Couldn't acquire data on id '$sid'");
return undef;
}
return $self->thaw($data);
}
# removes the given data and all the disk space associated with it
sub remove {
my ($self, $sid, $options) = @_;
my $dbh = $self->PostgreSQL_dbh($options);
my $data;
eval {
$data = $dbh->selectrow_array(
' SELECT a_session FROM '.$TABLE_NAME.
' WHERE id = '.$dbh->quote($sid).' FOR UPDATE'
);
};
if( $@ ) {
$self->error("Couldn't acquire data on id '$sid'");
return undef;
}
eval {
$dbh->do(
'DELETE FROM '.$TABLE_NAME.' WHERE id = '.$dbh->quote($sid)
);
};
if( $@ ) {
$self->error("Couldn't release lock of '$sid'");
return undef;
}
return 1;
}
# Called right before the object is destroyed to do cleanup
sub teardown {
my ($self, $sid, $options) = @_;
my $dbh = $self->PostgreSQL_dbh($options);
# Call commit if it isn't meant to be autocommited!
unless ( $dbh->{AutoCommit} ) {
$dbh->commit();
}
if ( $self->{PostgreSQL_disconnect} ) {
$dbh->disconnect();
}
return 1;
}
sub PostgreSQL_dbh {
my ($self, $options) = @_;
my $args = $options->[1] || {};
if ( defined $self->{PostgreSQL_dbh} ) {
return $self->{PostgreSQL_dbh};
}
if ( defined $args->{TableName} ) {
$TABLE_NAME = $args->{TableName};
}
require DBI;
$self->{PostgreSQL_dbh} = $args->{Handle} || DBI->connect(
$args->{DataSource},
$args->{User} || undef,
$args->{Password} || undef,
{ RaiseError=>1, PrintError=>1, AutoCommit=>1 } );
# If we're the one established the connection,
# we should be the one who closes it
$args->{Handle} or $self->{PostgreSQL_disconnect} = 1;
return $self->{PostgreSQL_dbh};
}
# $Id: PostgreSQL.pm,v 1.1.1.1 2003/08/02 23:39:34 takezoe Exp $
1;
=pod
=head1 NAME
CGI::Session::PostgreSQL - PostgreSQL driver for CGI::Session
=head1 SYNOPSIS
use CGI::Session;
$session = new CGI::Session("driver:PostgreSQL", undef, {Handle=>$dbh});
For more examples, consult L<CGI::Session> manual
=head1 DESCRIPTION
CGI::Session::PostgreSQL is a CGI::Session driver to store session data in a PostgreSQL table.
To write your own drivers for B<CGI::Session> refere L<CGI::Session> manual.
=head1 STORAGE
To store session data in PostgreSQL database, you first need
to create a suitable table for it with the following command:
CREATE TABLE sessions (
id CHAR(32) NOT NULL,
a_session TEXT NOT NULL
);
You can also add any number of additional columns to the table,
but the above "id" and "a_session" are required.
If you want to store the session data in other table than "sessions",
you will also need to specify B<TableName> attribute as the
first argument to new():
use CGI::Session;
$session = new CGI::Session("driver:PostgreSQL", undef,
{Handle=>$dbh, TableName=>'my_sessions'});
Every write access to session records is done through PostgreSQL own row locking mechanism,
enabled by `FOR UPDATE' clauses in SELECTs or implicitly enabled in UPDATEs and DELETEs.
=head1 COPYRIGHT
Copyright (C) 2002 Cosimo Streppone. All rights reserved.
This library is free software and can be modified and distributed
under the same terms as Perl itself.
=head1 AUTHOR
Cosimo Streppone <cosimo@cpan.org>, heavily based on the CGI::Session::MySQL
driver by Sherzod Ruzmetov, original author of CGI::Session.
=head1 SEE ALSO
=over 4
=item *
L<CGI::Session|CGI::Session> - CGI::Session manual
=item *
L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual
=item *
L<CGI::Session::CookBook|CGI::Session::CookBook> - practical solutions for real life problems
=item *
B<RFC 2965> - "HTTP State Management Mechanism" found at ftp://ftp.isi.edu/in-notes/rfc2965.txt
=item *
L<CGI|CGI> - standard CGI library
=item *
L<Apache::Session|Apache::Session> - another fine alternative to CGI::Session
=back
=cut