Template-DBI-2.65004075500017500000024000000000001142360176400127455ustar trevorstaffTemplate-DBI-2.65/META.yml010064400017500000024000000016371142360176400143010ustar trevorstaff--- #YAML:1.0 name: Template-DBI version: 2.65 abstract: Template interface to the DBI module author: - Andy Wardley , Jens Rehsack license: perl distribution_type: module configure_requires: ExtUtils::MakeMaker: 0 build_requires: MLDBM: 0 SQL::Statement: 1.28 requires: DBI: 1.612 perl: 5.008 Template: 2.22 resources: license: http://dev.perl.org/licenses/ MailingList: mailto:templates@template-toolkit.org repository: svn://svn.tt2.org/tt/Template-DBI/trunk/ no_index: directory: - t - inc generated_by: ExtUtils::MakeMaker version 6.56 meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 recommends: MLDBM: 0 SQL::Statement: 1.28 threads::variable::reap: 0.05 Template-DBI-2.65/t004075500017500000024000000000001142360176400132105ustar trevorstaffTemplate-DBI-2.65/t/lib.pl010064400017500000024000000105341142202362100143570ustar trevorstaff# -*-perl-*- # lib.pl is the file where database specific things should live, # whereever possible. For example, you define certain constants # here and the like. use strict; use warnings; use vars qw($test_dsn $test_user $test_pass $test_pass $test_attr $dbh $short_dsn $PK $dir); use Carp; use Cwd; use File::Path; use File::Spec; my %v; my @req = qw(DBI Template Template::Plugin::DBI); my @eval = map { qq{require $_;\n\$v{"$_"} = $_->VERSION ()} } @req; $@ = undef; eval $_ for @eval; if ($@) { my @missing = grep { !exists $v{$_} } qw( DBI Template ); print STDERR "\n\nYOU ARE MISSING REQUIRED MODULES: [ @missing ]\n\n"; exit 0; } # Start each test clean $dir = File::Spec->catdir( getcwd(), 'test_output' ); rmtree $dir; END { rmtree $dir } mkpath $dir; $test_dsn = $ENV{DBI_DSN} || "dbi:DBM(RaiseError=0,PrintError=1,ChopBlanks=1):f_dir=$dir;dbm_mldbm=Storable"; $test_user = $ENV{DBI_USER} || ""; $test_pass = $ENV{DBI_PASS} || ""; $test_attr = {}; # new feature in DBI plugin v2.30+ is to allow user to drop initial 'dbi:' ( $short_dsn = $test_dsn ) =~ s/^dbi://i; # another hack: if we want to test Tie::DBI updates then we have to build # database with primary keys to force uniqueness. However, different database # have different ways of defining primary keys, so we're only going to test # it on mysql $PK = ( $short_dsn =~ /^mysql/i ) ? 'PRIMARY KEY' : ''; eval "use Tie::DBI"; my $tiedbi = $@ ? 0 : 1; sub BAIL_OUT($) { carp $_[0]; ntests(1); ok(0); exit(0); } sub get_tt_test_vars { my $vars = { dbh => $dbh, dsn => $test_dsn, user => $test_user, pass => $test_pass, attr => $test_attr, short => $short_dsn, mysql => $PK ? 1 : 0, tiedbi => $tiedbi, }; return $vars; } sub connect_database { $dbh = DBI->connect( $test_dsn, $test_user, $test_pass ); } #------------------------------------------------------------------------ # init_database #------------------------------------------------------------------------ sub init_database { my $dbh = shift; # ensure tables don't already exist (in case previous test run failed). sql_query( $dbh, 'DROP TABLE IF EXISTS usr', 1 ); sql_query( $dbh, 'DROP TABLE IF EXISTS grp', 1 ); # create some tables sql_query( $dbh, "CREATE TABLE grp ( id Char(16) $PK, name Char(32) )" ); sql_query( $dbh, "CREATE TABLE usr ( id Char(16) $PK, name Char(32), grp Char(16) )" ); # add some records to the 'grp' table sql_query( $dbh, "INSERT INTO grp VALUES ('foo', 'The Foo Group')" ); sql_query( $dbh, "INSERT INTO grp VALUES ('bar', 'The Bar Group')" ); sql_query( $dbh, "INSERT INTO grp VALUES ('baz', 'The Baz Group')" ); # add some records to the 'usr' table sql_query( $dbh, "INSERT INTO usr VALUES ('abw', 'Andy Wardley', 'foo')" ); sql_query( $dbh, "INSERT INTO usr VALUES ('sam', 'Simon Matthews', 'foo')" ); sql_query( $dbh, "INSERT INTO usr VALUES ('hans', 'Hans von Lengerke', 'bar')" ); sql_query( $dbh, "INSERT INTO usr VALUES ('mrp', 'Martin Portman', 'bar')" ); sql_query( $dbh, "INSERT INTO usr VALUES ('craig', 'Craig Barratt', 'baz')" ); } #------------------------------------------------------------------------ # sql_query($dbh, $sql, $quiet) #------------------------------------------------------------------------ sub sql_query { my ( $dbh, $sql, $quiet ) = @_; my $sth = $dbh->prepare($sql) || warn "prepare() failed: $DBI::errstr\n"; $sth->execute() || $quiet || warn "execute() failed: $DBI::errstr\n"; $sth->finish(); } #------------------------------------------------------------------------ # cleanup_database($dsn, $user, $pass) #------------------------------------------------------------------------ sub cleanup_database { my $dbh = shift; sql_query( $dbh, 'DROP TABLE usr' ); sql_query( $dbh, 'DROP TABLE grp' ); } 1; Template-DBI-2.65/t/dbi.t010064400017500000024000000337461142202771500142210ustar trevorstaff# -*-perl-*- #======================================================================== # # t/dbi.t # # Test script for the DBI plugin. # # This is free software; you can redistribute it and/or modify it # under the same terms as Perl itself. # # $Id: dbi.t,v 2.16 2002/09/04 12:04:01 darren Exp $ # #======================================================================== use strict; use warnings; do "t/lib.pl"; use Template::Test; use Template::Stash; use DBI; $Template::Test::PRESERVE = 1; my $dbh = connect_database(); unless ($dbh) { BAIL_OUT("Unable to connect to the database $DBI::errstr\nTests skipped.\n"); exit 0; } #------------------------------------------------------------------------ # See if DBI and Tie::DBI are installed #------------------------------------------------------------------------ # warn "Tie::DBI not found, skipping those tests\n" unless $tiedbi; init_database($dbh); my $vars = get_tt_test_vars(); # NOTE: Template::Stash::XS does not handle tied hashes so we must force # the use of the regular Template::Stash my $stash = Template::Stash->new($vars); test_expect( \*DATA, { STASH => $stash }, $vars ); cleanup_database($dbh); $dbh->disconnect(); #======================================================================== __END__ #------------------------------------------------------------------------ # test plugin loading with implicit and explicit connect() method #------------------------------------------------------------------------ -- test -- [% USE DBI -%] [% DBI.connect(dsn, user, pass, ChopBlanks => 1) -%] [% FOREACH user = DBI.query("SELECT name FROM usr WHERE id='abw'") -%] * [% user.name %] [% END %] -- expect -- * Andy Wardley -- test -- [% USE dbi -%] [% dbi.connect(dsn, user, pass, ChopBlanks => 1) -%] [% FOREACH user = dbi.query("SELECT name FROM usr WHERE id='sam'") -%] * [% user.name %] [% END %] -- expect -- * Simon Matthews -- test -- [% USE db = DBI -%] [% db.connect(dsn, user, pass, ChopBlanks => 1) -%] [% FOREACH user = db.query("SELECT name FROM usr WHERE id='hans'") -%] * [% user.name %] [% END %] -- expect -- * Hans von Lengerke -- test -- [% USE db = DBI(data_source => dsn, username => user, password => pass, ChopBlanks => 1) -%] [% FOREACH user = db.query("SELECT name FROM usr WHERE id='mrp'") -%] * [% user.name %] [% END %] -- expect -- * Martin Portman -- test -- [% USE dbi -%] [% dbi.connect(dsn=dsn, user=user, pass=pass ChopBlanks=1) -%] [% FOREACH user = dbi.query("SELECT name FROM usr WHERE id='abw'") -%] * [% user.name %] [% END %] -- expect -- * Andy Wardley -- test -- [% USE dbi -%] [% dbi.connect(database=dsn, user=user, pass=pass, ChopBlanks=1) -%] [% FOREACH user = dbi.query("SELECT name FROM usr WHERE id='abw'") -%] * [% user.name %] [% END %] -- expect -- * Andy Wardley -- test -- [% USE DBI -%] [% TRY; DBI.query('blah blah'); CATCH; error; END %] -- expect -- DBI error - data source not defined #------------------------------------------------------------------------ # test short form of dsn, e.g. 'mysql:dbase' instead of 'dbi:mysql:dbase' #------------------------------------------------------------------------ -- test -- [% USE dbi -%] [% dbi.connect(short, user, pass ChopBlanks=1) -%] [% FOREACH user = dbi.query("SELECT name FROM usr WHERE id='abw'") -%] * [% user.name %] [% END %] -- expect -- * Andy Wardley #------------------------------------------------------------------------ # disconnect() and subsequent connect() #------------------------------------------------------------------------ -- test -- [% USE DBI(dsn, user, pass, attr) -%] [% DBI.disconnect -%] [% TRY; DBI.query('blah blah'); CATCH; error; END %] -- expect -- DBI error - data source not defined -- test -- [% USE DBI(dsn, user, pass, attr) -%] [% DBI.disconnect -%] [% DBI.connect(dsn, user, pass, attr) -%] [% FOREACH user = DBI.query("SELECT name FROM usr WHERE id='abw'") -%] * [% user.name %] [% END %] -- expect -- * Andy Wardley #------------------------------------------------------------------------ # validate 'loop' reference to iterator #------------------------------------------------------------------------ -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% FOREACH user = dbi.query('SELECT * FROM usr ORDER BY id') -%] [% loop.number %]: [% user.id %] - [% user.name %] [% END %] -- expect -- 1: abw - Andy Wardley 2: craig - Craig Barratt 3: hans - Hans von Lengerke 4: mrp - Martin Portman 5: sam - Simon Matthews -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% names = [ 'abw', 'sam' ] -%] [% query = dbi.prepare('SELECT * FROM usr WHERE id IN (?,?) ORDER BY id') -%] [% FOREACH user = query.execute(names) -%] [% loop.number %]: [% user.id %] - [% user.name %] [% END %] -- expect -- 1: abw - Andy Wardley 2: sam - Simon Matthews -- test -- # DBI plugin before TT 2.00 used 'count' instead of 'number' [% USE dbi(dsn, user, pass, attr) -%] [% FOREACH user = dbi.query('SELECT * FROM usr ORDER BY id') -%] [% loop.count %]: [% user.id %] - [% user.name %] [% END %] -- expect -- 1: abw - Andy Wardley 2: craig - Craig Barratt 3: hans - Hans von Lengerke 4: mrp - Martin Portman 5: sam - Simon Matthews #------------------------------------------------------------------------ # test 'loop' reference to iterator in nested queries #------------------------------------------------------------------------ -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% FOREACH group = dbi.query('SELECT * FROM grp ORDER BY id') -%] Group [% loop.number %]: [% group.name %] ([% group.id %]) [% FOREACH user = dbi.query("SELECT * FROM usr WHERE grp='$group.id' ORDER BY id") -%] #[% loop.number %]: [% user.name %] ([% user.id %]) [% END -%] [% END -%] -- expect -- Group 1: The Bar Group (bar) #1: Hans von Lengerke (hans) #2: Martin Portman (mrp) Group 2: The Baz Group (baz) #1: Craig Barratt (craig) Group 3: The Foo Group (foo) #1: Andy Wardley (abw) #2: Simon Matthews (sam) #------------------------------------------------------------------------ # test prev and next iterator methods #------------------------------------------------------------------------ -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% FOREACH user = dbi.query('SELECT * FROM usr ORDER BY id') -%] [% loop.prev ? "[$loop.prev.id] " : "[no prev] " -%] [% user.id %] - [% user.name -%] [% loop.next ? " [$loop.next.id]" : " [no next]" %] [% END %] -- expect -- [no prev] abw - Andy Wardley [craig] [abw] craig - Craig Barratt [hans] [craig] hans - Hans von Lengerke [mrp] [hans] mrp - Martin Portman [sam] [mrp] sam - Simon Matthews [no next] #------------------------------------------------------------------------ # test do() to perform SQL queries without returning results #------------------------------------------------------------------------ -- test -- [% USE DBI(dsn, user, pass, attr) -%] [% CALL DBI.do("INSERT INTO usr VALUES ('numb', 'Numb Nuts', 'bar')") -%] [% FOREACH user = DBI.query("SELECT * FROM usr WHERE grp = 'bar' ORDER BY id") -%] * [% user.name %] ([% user.id %]) [% END %] -- expect -- * Hans von Lengerke (hans) * Martin Portman (mrp) * Numb Nuts (numb) -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% IF dbi.do("DELETE FROM usr WHERE id = 'numb'") -%] deleted the user [% ELSE -%] failed to delete the user [% END -%] [% FOREACH user = dbi.query("SELECT * FROM usr WHERE grp = 'bar' ORDER BY id") -%] * [% user.name %] ([% user.id %]) [% END %] -- expect -- deleted the user * Hans von Lengerke (hans) * Martin Portman (mrp) #------------------------------------------------------------------------ # prepare() #------------------------------------------------------------------------ -- test -- [% USE dbi(dsn=dsn, user=user, pass=pass, ChopBlanks=1) -%] [% user_query = dbi.prepare('SELECT * FROM usr WHERE grp = ? ORDER BY id') -%] Foo: [% users = user_query.execute('foo') -%] [% FOREACH user = users -%] #[% users.index %]: [% user.name %] ([% user.id %]) [% END -%] Bar: [% users = user_query.execute('bar') -%] [% FOREACH user = users -%] #[% users.index %]: [% user.name %] ([% user.id %]) [% END -%] -- expect -- Foo: #0: Andy Wardley (abw) #1: Simon Matthews (sam) Bar: #0: Hans von Lengerke (hans) #1: Martin Portman (mrp) -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% group_query = dbi.prepare('SELECT * FROM grp ORDER BY id') -%] [% user_query = dbi.prepare('SELECT * FROM usr WHERE grp = ? ORDER BY id') -%] [% groups = group_query.execute -%] [% FOREACH group = groups -%] Group [% groups.count %] : [% group.name %] [% users = user_query.execute(group.id) -%] [% FOREACH user = users -%] User [% users.index %] : [% user.name %] ([% user.id %]) [% END -%] [% END %] -- expect -- Group 1 : The Bar Group User 0 : Hans von Lengerke (hans) User 1 : Martin Portman (mrp) Group 2 : The Baz Group User 0 : Craig Barratt (craig) Group 3 : The Foo Group User 0 : Andy Wardley (abw) User 1 : Simon Matthews (sam) -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% CALL dbi.prepare('SELECT * FROM usr WHERE id = ?') -%] [% FOREACH uid = [ 'abw', 'sam' ] -%] === [% FOREACH user = dbi.execute(uid) -%] * [% user.name %] ([% user.id %]) [% END -%] === [% END %] -- expect -- === * Andy Wardley (abw) === === * Simon Matthews (sam) === #------------------------------------------------------------------------ # test that dbh can be passed as a named parameter and remains open #------------------------------------------------------------------------ -- test -- [% USE dbi(dbh => dbh) -%] [% FOREACH dbi.query("SELECT * FROM usr WHERE id = 'abw'") -%] * [% name %] [% END -%] [% dbi.connect(dsn, user, pass, ChopBlanks=1) -%] [% FOREACH user = dbi.query("SELECT * FROM usr WHERE id = 'abw'") -%] * [% user.name %] [% END -%] -- expect -- * Andy Wardley * Andy Wardley #------------------------------------------------------------------------ # test get_all() #------------------------------------------------------------------------ -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% people = dbi.query('SELECT * FROM usr ORDER BY id').get_all -%] [% FOREACH p = people -%] [% p.name %] [% END; global.people = people %] -- expect -- Andy Wardley Craig Barratt Hans von Lengerke Martin Portman Simon Matthews -- test -- [% FOREACH p = global.people.reverse -%] [% p.name %] [% END %] -- expect -- Simon Matthews Martin Portman Hans von Lengerke Craig Barratt Andy Wardley -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% people = dbi.query('SELECT * FROM usr ORDER BY id') -%] first: [% people.get.name %] [% FOREACH p = people.get_all -%] rest: [% p.name %] [% END %] -- expect -- first: Andy Wardley rest: Craig Barratt rest: Hans von Lengerke rest: Martin Portman rest: Simon Matthews #------------------------------------------------------------------------ # test size() and max() methods #------------------------------------------------------------------------ -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% users = dbi.query('SELECT * FROM usr ORDER BY id') -%] size: [% users.size +%] max: [% users.max +%] -- expect -- size: 5 max: 4 -- test -- [% USE dbi(dsn, user, pass, attr) -%] There are [% dbi.query('SELECT * FROM usr').size -%] users -- expect -- There are 5 users -- test -- [% USE dbi(dsn, user, pass, attr) -%] [% FOREACH user = dbi.query('SELECT * FROM usr ORDER BY id') -%] [% loop.count %]/[%loop.size %] ([% loop.index %]/[% loop.max %]) [% user.name %] [% END %] -- expect -- 1/5 (0/4) Andy Wardley 2/5 (1/4) Craig Barratt 3/5 (2/4) Hans von Lengerke 4/5 (3/4) Martin Portman 5/5 (4/4) Simon Matthews #------------------------------------------------------------------------ # test tie() method to interface to Tie::DBI #------------------------------------------------------------------------ -- test -- [% IF tiedbi -%] [% USE dbi(dsn, user, pass, attr) -%] [% people = dbi.tie('usr', 'id') -%] [% people.abw.name %] [% ELSE -%] Skipping Tie::DBI tests [%- END %] -- expect -- -- process -- [% IF tiedbi -%] Andy Wardley [% ELSE -%] Skipping Tie::DBI tests [%- END %] -- test -- [% IF tiedbi -%] [% USE dbi(dsn, user, pass, attr) -%] [% people = dbi.tie('usr', 'id') -%] [% FOREACH id = people.keys.sort -%] [% id %]: [% people.${id}.name +%] [% END %] [% ELSE -%] Skipping Tie::DBI tests [%- END %] -- expect -- -- process -- [% IF tiedbi -%] abw: Andy Wardley craig: Craig Barratt hans: Hans von Lengerke mrp: Martin Portman sam: Simon Matthews [% ELSE -%] Skipping Tie::DBI tests [%- END %] -- test -- [% IF tiedbi -%] [% USE dbi(dsn, user, pass, attr) -%] [% people = dbi.tie('usr', 'id') -%] dave: [[% people.dave.name %]] [% TRY; people.dave = { name = 'Dave Hodgkinson' }; CATCH; "ok\n"; END -%] dave: [[% people.dave.name %]] [% ELSE -%] Skipping Tie::DBI tests [%- END %] -- expect -- -- process -- [% IF tiedbi -%] dave: [] ok dave: [] [% ELSE -%] Skipping Tie::DBI tests [%- END %] -- test -- [% IF tiedbi -%] [% USE dbi(dsn, user, pass, attr) -%] [% people = dbi.tie('usr', 'id', clobber=1) -%] dave: [[% people.dave.name %]] [% IF mysql -%] [% people.dave = { name = 'Dave Hodgkinson', grp = 'bar' } -%] dave: [[% people.dave.name %] | [% people.dave.grp %]] [% people.dave.grp = 'foo' -%] [% people.dave.name = 'Davey Boy' -%] dave: [[% people.dave.name %] | [% people.dave.grp %]] [%- END %] [% ELSE -%] Skipping Tie::DBI tests [%- END %] -- expect -- -- process -- [% IF tiedbi -%] dave: [] [% IF mysql -%] dave: [Dave Hodgkinson | bar] dave: [Davey Boy | foo] [%- END %] [% ELSE -%] Skipping Tie::DBI tests [%- END %] Template-DBI-2.65/Changes010064400017500000024000000013011142360165100143020ustar trevorstaffRevision history for Template-DBI 2.65 2010-07-27 - take over maintainership from prior maintainers Andy Wardley and Simon Matthews (Jens Rehsack) Thanks to both guys for their great work so far - improve connect to can reconnect after CLONE - add support for keeping alive in threaded environment - add ability to prepare/query with passing params to $dbh->prepare - add some neat functions to the iterator of th $sth - add ability to fetch and store $dbh and $sth attributes - reap DBI handles for new threads when used in threaded environments and threads::variable::reap is available - add test with two placeholders 2.64 2006-05-25 - last release by Andy Wardley Template-DBI-2.65/lib004075500017500000024000000000001142360176400135135ustar trevorstaffTemplate-DBI-2.65/lib/Template004075500017500000024000000000001142360176400152665ustar trevorstaffTemplate-DBI-2.65/lib/Template/Plugin004075500017500000024000000000001142360176400165245ustar trevorstaffTemplate-DBI-2.65/lib/Template/Plugin/DBI.pm010075500017500000024000000751721142336433000175460ustar trevorstaff#============================================================================== # # Template::Plugin::DBI # # DESCRIPTION # A Template Toolkit plugin to provide access to a DBI data source. # # AUTHORS # Original version by Simon Matthews # with some reworking by Andy Wardley and other # contributions from Craig Barratt , # Dave Hodgkinson and Rafael Kitover # . # Since 2010 Jens Rehsack maintains this module. # # COPYRIGHT # Copyright (C) 1999-2000 Simon Matthews. All Rights Reserved. # Copyright (C) 2006 Andy Wardley. All Rights Reserved. # Copyright (C) 2010 Jens Rehsack. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # REVISION # $Id$ # #============================================================================== package Template::Plugin::DBI; use strict; use warnings; use Carp qw(croak carp); use DBI; use Template::Exception; use base 'Template::Plugin'; our $VERSION = 2.65; our $DEBUG = 0 unless defined $DEBUG; our $QUERY = 'Template::Plugin::DBI::Query'; our $ITERATOR = 'Template::Plugin::DBI::Iterator'; my $threads_enabled = 0; my $have_tvr = 0; BEGIN { $INC{"threads.pm"} and eval { ++$threads_enabled; require threads::variable::reap; ++$have_tvr; }; $have_tvr and threads::variable::reap->import(qw(reap reapref)); } # alias _connect() to connect() for backwards compatability *_connect = \*connect; #------------------------------------------------------------------------ # new($context, @params) # # Constructor which returns a reference to a new DBI plugin object. # A connection string (dsn), user name and password may be passed as # positional arguments or a hash array of connection parameters can be # passed to initialise a connection. Otherwise, an unconnected DBI # plugin object is returned. #------------------------------------------------------------------------ sub new { my ( $class, $context, @connect_args ) = @_; my $self = ref $class ? $class : bless { _CONTEXT => $context, _STH => undef, }, $class; $self->connect(@connect_args) if @connect_args; return $self; } #------------------------------------------------------------------------ # connect( $data_source, $username, $password, $attributes ) # connect( { data_source => 'dbi:driver:database' # username => 'foo' # password => 'bar' } ) # # Opens a DBI connection for the plugin. #------------------------------------------------------------------------ sub connect { my $self = shift; my $params = ref $_[-1] eq 'HASH' ? pop(@_) : {}; my ( $dbh, $dsn, $user, $pass, $klobs ); # set debug flag exists $params->{debug} and $DEBUG = $params->{debug}; $self->{_DEBUG} = $params->{debug} || 0; # fetch 'dbh' named paramater or use positional arguments or named # parameters to specify 'dsn', 'user' and 'pass' if ( $dbh = $params->{dbh} ) { # disconnect any existing database handle that we previously opened $self->{_DBH}->disconnect() if $self->{_DBH} && $self->{_DBH_CONNECT}; # store new dbh but leave _DBH_CONNECT false to prevent us # from automatically closing it in the future $self->{_DBH} = $dbh; $self->{_DBH_CONNECT} = 0; } else { # certain Perl programmers are known to have problems with short # term memory loss (see Tie::Hash::Cannabinol) so we let the poor # blighters fumble any kind of argument that looks like it might # identify the database $dsn = shift || delete $params->{data_source} || delete $params->{database} || delete $params->{connect} || delete $params->{dsn} || delete $params->{db} || delete $self->{_DSN} || $ENV{DBI_DSN} || return $self->_throw('data source not defined'); # add 'dbi:' prefix if it's not there $dsn = "dbi:$dsn" unless $dsn =~ /^dbi:/i; $user = shift || delete $params->{username} || delete $params->{user} || delete $self->{_USER}; $pass = shift || delete $params->{password} || delete $params->{pass} || delete $self->{_PASS}; $user ||= ''; $pass ||= ''; # save connection data because we might need it later to do a tie() @$self{qw( _DSN _USER _PASS )} = ( $dsn, $user, $pass ); # reuse existing database handle if connection params match my $connect = join( ':', $dsn, $user, $pass ); return '' if $self->connected() && $self->{_DBH_CONNECT} eq $connect; # otherwise disconnect any existing database handle that we opened $self->disconnect(); # don't need DBI to automatically print errors because all calls go # via this plugin interface and we always check return values $params->{PrintError} = 0 unless defined $params->{PrintError}; $params->{RaiseError} = 0 unless defined $params->{RaiseError}; $self->{_DBH} = DBI->connect_cached( $dsn, $user, $pass, $params ) || return $self->_throw("DBI connect failed: $DBI::errstr"); # store the connection parameters $self->{_DBH_CONNECT} = $connect; } $have_tvr and reap( $self->{_DBH} ) and reap( $self->{_STH} ); return ''; } sub connected { my $self = $_[0]; return $self->{_DBH} && $self->{_DBH}->isa('DBI::db'); } #------------------------------------------------------------------------ # disconnect() # # Disconnects the current active database connection. #------------------------------------------------------------------------ sub disconnect { my $self = $_[0]; delete( $self->{_STH} ); # first DESTROY any queries $self->connected() and $self->{_DBH}->disconnect(); delete $self->{_DBH}; delete $self->{_DSN}; delete $self->{_USER}; delete $self->{_PASS}; delete $self->{_DBH_CONNECT}; return ''; } #------------------------------------------------------------------------ # tie( $table, $key ) # # Return a hash tied to a table in the database, indexed by the specified # key. #------------------------------------------------------------------------ sub tie { my $self = shift; my $params = ref $_[-1] eq 'HASH' ? pop(@_) : {}; my ( $table, $key, $klobs, $debug, %hash ); eval { require Tie::DBI }; $self->_throw("failed to load Tie::DBI module: $@") if $@; $table = shift || $params->{table} || $self->_throw('table not defined'); $key = shift || $params->{key} || $self->_throw('key not defined'); # Achtung der Klobberman! $klobs = $params->{clobber}; $klobs = $params->{CLOBBER} unless defined $klobs; # going the extra mile to allow user to use UPPER or lower case or # inherit internel debug flag set by connect() $debug = $params->{debug}; $debug = $params->{DEBUG} unless defined $debug; $debug = $self->{_DEBUG} unless defined $debug; tie %hash, 'Tie::DBI', { %$params, # any other Tie::DBI options like DEBUG, WARN, etc db => $self->{_DBH} || $self->{_DSN}, user => $self->{_USER}, password => $self->{_PASS}, table => $table, key => $key, CLOBBER => $klobs || 0, DEBUG => $debug || 0, }; return \%hash; } #------------------------------------------------------------------------ # prepare($sql) # # Prepare a query and store the live statement handle internally for # subsequent execute() calls. #------------------------------------------------------------------------ sub prepare { my ($self,@args) = @_; unless( @args and $args[0] and "" eq ref($args[0]) ) { return $self->_throw("prepare called without statement"); } my $sth = $self->dbh()->prepare(@args) || return $self->_throw( "DBI prepare failed: " . $self->dbh()->errstr ); # create wrapper object around handle to return to template client $sth = $QUERY->new($sth); $self->{_STH} = $sth; return $sth; } #------------------------------------------------------------------------ # execute() # # Calls execute() on the most recent statement created via prepare(). #------------------------------------------------------------------------ sub execute { my $self = shift; my @args = @_ == 1 && ref $_[0] eq 'ARRAY' ? @{ $_[0] } : @_; my $sth = $self->{_STH} || return $self->_throw('no query prepared'); $sth->execute(@args); } #------------------------------------------------------------------------ # query($sql, @params) # # Prepares and executes a SQL query. #------------------------------------------------------------------------ sub query { my ( $self, $sql, @args ) = @_; my @prep = ($sql); if( @args and $args[0] and ref($args[0]) eq 'HASH' ) { push(@prep, shift @args); } return $self->prepare(@prep)->execute(@args); } #------------------------------------------------------------------------ # do($sql, \%attr, @bind) # # Prepares and executes a SQL statement. #------------------------------------------------------------------------ sub do { my $self = shift; my @args = @_ == 1 && ref $_[0] eq 'ARRAY' ? @{ $_[0] } : @_; return $self->dbh()->do(@args) || $self->_throw( "DBI do failed: " . $self->dbh()->errstr ); } #------------------------------------------------------------------------ # quote($value [, $data_type ]) # # Returns a quoted string (correct for the connected database) from the # value passed in. #------------------------------------------------------------------------ sub quote { my ( $self, @quote_args ) = @_; return $self->dbh()->quote(@quote_args); } #------------------------------------------------------------------------ # dbh() # # Internal method to retrieve the database handle belonging to the # instance or attempt to create a new one using connect. #------------------------------------------------------------------------ sub dbh { my $self = $_[0]; $self->{_DBH} or $self->connect; return $self->{_DBH}; } #------------------------------------------------------------------------ # DESTROY # # Called automatically when the plugin object goes out of scope to # disconnect the database handle cleanly #------------------------------------------------------------------------ sub DESTROY { my $self = $_[0]; delete( $self->{_STH} ); # first DESTROY any queries $self->{_DBH}->disconnect() if ( $self->connected() && $self->{_DBH_CONNECT} ); } #------------------------------------------------------------------------ # _throw($error) # # Raise an error by throwing it via die() as a Template::Exception # object of type 'DBI'. #------------------------------------------------------------------------ sub _throw { my $self = shift; my $error = shift || croak "DBI throw() called without an error string"; # throw error as DBI exception die( Template::Exception->new( 'DBI', $error ) ); } sub fetch { my ( $self, $attr ) = @_; return $self->_throw("Cannot fetch attribute on not connected \$dbh") unless ( $self->connected() ); my $dbh = $_[0]->{_DBH}; local $@ = undef; my $value; eval { $value = $dbh->{$attr}; }; return $self->_throw($@) if ($@); return $value; } sub store { my ( $self, $attr, $value ) = @_; return $self->_throw("Cannot store attribute on not connected \$dbh") unless ( $self->connected() ); my $dbh = $_[0]->{_DBH}; local $@ = undef; eval { $dbh->{$attr} = $value; }; return $self->_throw($@) if ($@); return 1; } #======================================================================== # Template::Plugin::DBI::Query #======================================================================== package Template::Plugin::DBI::Query; use vars qw( $DEBUG $ITERATOR $AUTOLOAD ); use Scalar::Util qw(blessed); *DEBUG = \$Template::Plugin::DBI::DEBUG; *ITERATOR = \$Template::Plugin::DBI::ITERATOR; sub new { my ( $class, $sth ) = @_; my $self = bless( { _STH => $sth }, $class ); } sub execute { my $self = shift; my @args = @_ == 1 && ref $_[0] eq 'ARRAY' ? @{ $_[0] } : @_; $self->{_STH}->execute(@args) || return Template::Plugin::DBI->_throw( "execute failed: " . $self->{_STH}->errstr ); $ITERATOR->new($self); } sub DESTROY { undef $_[0]->{_STH}; } sub AUTOLOAD { my ( $self, @args ) = @_; die Template::Exception->new( 'DBI', "$self is not an object" ) unless ( blessed($self) ); die Template::Exception->new( 'DBI', "No statement handle" ) unless ( defined( $self->{_STH} ) ); ( my $name = $AUTOLOAD ) =~ s/.*://; return $self->{_STH}->$name(@args); } #======================================================================== # Template::Plugin::DBI::Iterator; #======================================================================== package Template::Plugin::DBI::Iterator; use Template::Iterator; use base qw( Template::Iterator ); use vars qw( $DEBUG ); *DEBUG = \$Template::Plugin::DBI::DEBUG; sub new { my ( $class, $sth, $params ) = @_; my $rows = $sth->rows(); my $self = bless { _STH => $sth, SIZE => $rows, MAX => $rows - 1, }, $class; return $self; } #------------------------------------------------------------------------ # get_first() # # Initialises iterator to read from statement handle. We maintain a # one-record lookahead buffer to allow us to detect if the current # record is the last in the series. #------------------------------------------------------------------------ sub get_first { my $self = shift; $self->{_STARTED} = 1; # set some status variables into $self @$self{qw( PREV ITEM FIRST LAST COUNT INDEX )} = ( undef, undef, 2, 0, 0, -1 ); # support 'number' as an alias for 'count' for backwards compatability $self->{NUMBER} = 0; print STDERR "get_first() called\n" if $DEBUG; # get the first row $self->_fetchrow(); print STDERR "get_first() calling get_next()\n" if $DEBUG; return $self->get_next(); } #------------------------------------------------------------------------ # get_next() # # Called to read remaining result records from statement handle. #------------------------------------------------------------------------ sub get_next { my $self = shift; my ( $data, $fixup ); # increment the 'index' and 'count' counts $self->{INDEX}++; $self->{COUNT}++; $self->{NUMBER}++; # 'number' is old name for 'count' # decrement the 'first-record' flag $self->{FIRST}-- if $self->{FIRST}; # we should have a row already cache in NEXT return ( undef, Template::Constants::STATUS_DONE ) unless $data = $self->{NEXT}; # set PREV to be current ITEM from last iteration $self->{PREV} = $self->{ITEM}; # look ahead to the next row so that the rowcache is refilled $self->_fetchrow(); $self->{ITEM} = $data; return ( $data, Template::Constants::STATUS_OK ); } sub get { my $self = shift; my ( $data, $error ); ( $data, $error ) = $self->{_STARTED} ? $self->get_next() : $self->get_first(); return $data; } sub get_all { my $self = shift; my $sth = $self->{_STH}; my $data = $sth->fetchall_arrayref( {} ); $self->throw( $sth->errstr ) if ( $sth->err() ); unshift( @$data, $self->{NEXT} ) if $self->{NEXT}; $self->{LAST} = 1; $self->{NEXT} = undef; return $data; } sub get_colnames { my $self = shift; my $sth = $self->{_STH}; my $error; my $data = $sth->{_STH}->{NAME_lc}; $self->throw( $sth->errstr ) if ( $sth->err() ); return $data; } sub get_COLnames { my $self = shift; my $sth = $self->{_STH}; my $data = $sth->{_STH}->{NAME_uc}; $self->throw( $sth->errstr ) if ( $sth->err() ); return $data; } sub get_all_list { my $self = shift; my $sth = $self->{_STH}; my $data = $sth->fetchall_arrayref(); $self->throw( $sth->errstr ) if ( $sth->err() ); if ( $self->{NEXT} ) { my $fetch_hash_key_name = $self->{_STH}->{FetchHashKeyName}; my @cols = @{ $self->{_STH}->{$fetch_hash_key_name} }; my @row = @{ $self->{NEXT} }[@cols]; unshift( @$data, \@row ); } $self->{LAST} = 1; $self->{NEXT} = undef; return $data; } sub rows { return $_[0]->{SIZE}; } sub fetch { my ( $self, $attr ) = @_; $self->{_STH}->FETCH($attr); } sub store { my ( $self, $attr, $value ) = @_; return $self->{_STH}->STORE( $attr, $value ); } #------------------------------------------------------------------------ # _fetchrow() # # Retrieve a record from the statement handle and store in row cache. #------------------------------------------------------------------------ sub _fetchrow { my $self = shift; my $sth = $self->{_STH}; my $data = $sth->fetchrow_hashref() || do { $self->{LAST} = 1; $self->{NEXT} = undef; return; }; $self->{NEXT} = $data; return; } 1; __END__ =head1 NAME Template::Plugin::DBI - Template interface to the DBI module =head1 SYNOPSIS Making an implicit database connection: # ...using positional arguments [% USE DBI('dbi:driver:dbname', 'user', 'pass') %] # ...using named parameters [% USE DBI( database = 'dbi:driver:dbname', username = 'user', password = 'pass' ) %] # ...using short named parameters (4 lzy ppl and bad typsits) [% USE DBI( db = 'driver:dbname', user = 'user', pass = 'pass' ) %] # ...or an existing DBI database handle [% USE DBI( dbh = my_dbh_ref ) %] Making explicit database connections: [% USE DBI %] [% DBI.connect(db, user, pass) %] ... [% DBI.connect(new_db, new_user, new_pass) %] ... [% DBI.disconnect %] # final disconnect is optional Making an automagical database connection using DBI_DSN environment variable: [% USE DBI %] Making database queries: # single step query [% FOREACH user = DBI.query('SELECT * FROM users') %] [% user.uid %] blah blah [% user.name %] etc. etc. [% END %] # two stage prepare/execute [% query = DBI.prepare('SELECT * FROM users WHERE uid = ?') %] [% FOREACH user = query.execute('sam') %] ... [% END %] [% FOREACH user = query.execute('abw') %] ... [% END %] Making non-SELECT statements: [% IF DBI.do("DELETE FROM users WHERE uid = '$uid'") %] The user '[% uid %]' was successfully deleted. [% END %] Using named DBI connections: [% USE one = DBI(...) %] [% USE two = DBI(...) %] [% FOREACH item = one.query("SELECT ...etc...") %] ... [% END %] [% FOREACH item = two.query("SELECT ...etc...") %] ... [% END %] Tieing to a database table (via Tie::DBI): [% people = DBI.tie('users', 'uid') %] [% me = people.abw %] # => SELECT * FROM users WHERE uid='abw' I am [% me.name %] # clobber option allows table updates (see Tie::DBI) [% people = DBI.tie('users', 'uid', clobber=1) %] [% people.abw.name = 'not a number' %] I am [% people.abw.name %] # I am a free man! =head1 DESCRIPTION This Template Toolkit plugin module provides an interface to the Perl DBI/DBD modules, allowing you to integrate SQL queries into your template documents. It also provides an interface via the Tie::DBI module (if installed on your system) so that you can access database records without having to embed any SQL in your templates. A DBI plugin object can be created as follows: [% USE DBI %] This creates an uninitialised DBI object. You can then open a connection to a database using the connect() method. [% DBI.connect('dbi:driver:dbname', 'user', 'pass') %] The DBI connection can be opened when the plugin is created by passing arguments to the constructor, called from the USE directive. [% USE DBI('dbi:driver:dbname', 'user', 'pass') %] You can also use named parameters to provide the data source connection string, user name and password. [% USE DBI(database => 'dbi:driver:dbname', username => 'user', password => 'pass') %] For backwards compatability with previous versions of this plugin, you can also spell 'database' as 'data_source'. [% USE DBI(data_source => 'dbi:driver:dbname', username => 'user', password => 'pass') %] Lazy Template hackers may prefer to use 'db', 'dsn' or 'connect' as a shorthand form of the 'database' parameter, and 'user' and 'pass' as shorthand forms of 'username' and 'password', respectively. You can also drop the 'dbi:' prefix from the database connect string because the plugin will add it on for you automagically. [% USE DBI(db => 'driver:dbname', user => 'user', pass => 'pass') %] Any additional DBI attributes can be specified as named parameters. The 'PrintError' attribute defaults to 0 unless explicitly set true. [% USE DBI(db, user, pass, ChopBlanks=1) %] An alternate variable name can be provided for the plugin as per regular Template Toolkit syntax: [% USE mydb = DBI('dbi:driver:dbname', 'user', 'pass') %] [% FOREACH item = mydb.query('SELECT * FROM users') %] ... [% END %] You can also specify the DBI plugin name in lower case if you prefer: [% USE dbi(dsn, user, pass) %] [% FOREACH item = dbi.query('SELECT * FROM users') %] ... [% END %] The disconnect() method can be called to explicitly disconnect the current database, but this generally shouldn't be necessary as it is called automatically when the plugin goes out of scope. You can call connect() at any time to open a connection to another database. The previous connection will be closed automatically. Internally, the DBI connect_cached() method is used instead of the connect() method. This allows for connection caching in a server environment, such as when the Template Toolkit is used from an Apache mod_perl handler. In such a case, simply enable the mod_env module and put in a line such as: SetEnv DBI_DSN "dbi:mysql:dbname;host=dbhost; user=uname;password=pword" (NOTE: the string shown here is split across 2 lines for the sake of reasonable page formatting, but you should specify it all as one long string with no spaces or newlines). You can then use the DBI plugin without any parameters or the need to explicitly call connect(). Once you've loaded a DBI plugin and opened a database connection using one of the techniques shown above, you can then make queries on the database using the familiar dotted notation: [% FOREACH user = DBI.query('SELECT * FROM users') %] [% user.uid %] blah blah [% user.name %] etc. etc. [% END %] The query() method prepares a query and executes it all in one go. If you want to repeat a query with different parameters then you can use a separate prepare/execute cycle. [% query = DBI.prepare('SELECT * FROM users WHERE uid = ?') %] [% FOREACH user = query.execute('sam') %] ... [% END %] [% FOREACH user = query.execute('abw') %] ... [% END %] The query() and execute() methods return an iterator object which manages the result set returned. You can save a reference to the iterator and access methods like size() to determine the number of rows returned by a query. [% users = DBI.query('SELECT * FROM users') %] [% users.size %] records returned or even [% DBI.query('SELECT * FROM users').size %] When used within a FOREACH loop, the iterator is always aliased to the special C variable. This makes it possible to do things like this: [% FOREACH user = DBI.query('SELECT * FROM users') %] [% loop.count %]/[% loop.size %]: [% user.name %] [% END %] to generate a result set of the form: 1/3: Jerry Garcia 2/3: Kurt Cobain 3/3: Freddie Mercury See L for further details on iterators and the methods that they implement. The DBI plugin also provides the do() method to execute non-SELECT statements like this: [% IF DBI.do("DELETE FROM users WHERE uid = '$uid'") %] The user '[% uid %]' was successfully deleted. [% END %] The plugin also allows you to create a tie to a table in the database using the Tie::DBI module. Simply call the tie() method, passing the name of the table and the primary key as arguments. [% people = DBI.tie('person', 'uid') %] You can then access records in the database table as if they were entries in the 'people' hash. My name is [% people.abw.name %] IMPORTANT NOTE: the XS Stash (Template::Stash::XS) does not currently support access to tied hashes. If you are using the XS stash and having problems then you should try enabling the regular stash instead. You can do this by setting $Template::Config::STASH to 'Template::Stash' before instantiating the Template object. =head1 OBJECT METHODS =head2 connect($database, $username, $password) Establishes a database connection. This method accepts both positional and named parameter syntax. e.g. [% DBI.connect( 'dbi:driver:dbname', 'timmy', 'sk8D00Dz' ) %] [% DBI.connect( database = 'dbi:driver:dbname' username = 'timmy' password = 'sk8D00Dz' ) %] The connect method allows you to connect to a data source explicitly. It can also be used to reconnect an exisiting object to a different data source. If you already have a database handle then you can instruct the plugin to reuse it by passing it as the 'dbh' parameter. [% DBI.connect( dbh = my_dbh_ref ) %] =head2 query($sql,[\%args],[@bind_values]) This method submits an SQL query to the database and creates an iterator object to return the results. This may be used directly in a FOREACH directive as shown below. Data is automatically fetched a row at a time from the query result set as required for memory efficiency. [% FOREACH user = DBI.query('SELECT * FROM users') %] Each [% user.field %] can be printed here [% END %] =head2 prepare($sql,[\%args]) Prepare a query for later execution. This returns a compiled query object (of the Template::Plugin::DBI::Query class) on which the execute() method can subsequently be called. [% query = DBI.prepare('SELECT * FROM users WHERE id = ?') %] =head2 execute(@bind_values) Execute a previously prepared query. This method should be called on the query object returned by the prepare() method. Returns an iterator object which can be used directly in a FOREACH directive. [% query = DBI.prepare('SELECT * FROM users WHERE manager = ?') %] [% FOREACH minion = query.execute('abw') %] [% minion.name %] [% END %] [% FOREACH minion = query.execute('sam') %] [% minion.name %] [% END %] =head2 do($sql,[\%attr,[@bind_values]]) The do() method executes a sql statement from which no records are returned. It will return true if the statement was successful [% IF DBI.do("DELETE FROM users WHERE uid = 'sam'") %] The user was successfully deleted. [% END %] =head2 tie($table, $key, \%args) Returns a reference to a hash array tied to a table in the database, implemented using the Tie::DBI module. You should pass the name of the table and the key field as arguments. [% people = DBI.tie('users', 'uid') %] Or if you prefer, you can use the 'table' and 'key' named parameters. [% people = DBI.tie(table='users', key='uid') %] In this example, the Tie::DBI module will convert the accesses into the 'people' hash into SQL queries of the form: SELECT * FROM users WHERE uid=? For example: [% me = people.abw %] The record returned can then be accessed just like a normal hash. I am [% me.name %] You can also do things like this to iterate through all the records in a table. [% FOREACH uid = people.keys.sort; person = people.$uid %] * [% person.id %] : [% person.name %] [% END %] With the 'clobber' (or 'CLOBBER') option set you can update the record and have those changes automatically permeated back into the database. [% people = DBI.tie('users', 'uid', clobber=1) %] [% people.abw.name = 'not a number' %] I am [% people.abw.name %] # I am a free man! And you can also add new records. [% people.newguy = { name = 'Nobby Newguy' ...other fields... } %] See L for further information on the 'CLOBBER' option. =head2 quote($value, $type) Calls the quote() method on the underlying DBI handle to quote the value specified in the appropriate manner for its type. =head2 dbh [% DBI.dbh() %] Return the database handle currently in use by the plugin. =head2 disconnect [% DBI.disconnect() %] Disconnects the current database. =head2 fetch [% DBI.fetch('Name') %] Fetches an attribute from the connected database handle. Throws an exception when not connected. =head2 store [% DBI.store('RowCacheSize',0) %] Stores an attribute in the connected database handle. Throws an exception when not connected. =head1 ITERATOR METHODS =head2 get_all [% allhash = result.get_all() %] Returns all (remaining) rows as a hash. =head2 get_all_list [% allhash = result.get_all_list() %] Returns all (remaining) rows as a list. =head2 rows Returns the number of affected rows of the executed statement. =head2 get_colnames Returns the lowercase column names (C<$sth> attribute C<< ->{NAME_lc} >>). =head2 get_COLnames Returns the uppercase column names (C<$sth> attribute C<< ->{NAME_uc} >>). =head2 fetch Fetches an attribute from the statement handle. [% result.fetch('FetchHashKeyName') %] =head2 store Stores an attribute to the statement handle. [% result.store('FetchHashKeyName','NAME_lc') %] =head1 AUTHORS The DBI plugin was originally written by Simon A Matthews, and distributed as a separate module. It was integrated into the Template Toolkit distribution for version 2.00 and includes contributions from Andy Wardley, Craig Barratt, Dave Hodgkinson and Rafael Kitover. Andy Wardley extracted it back into a separate distribution in May 2006. After that, in 2010 Jens Rehsack maintains this distribution. =head1 COPYRIGHT Copyright (C) 1999-2006 Simon Matthews, Andy Wardley. All Rights Reserved. Copyright (C) 2010 Jens Rehsack. All Rights Reserved This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L