.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DBD::PgPP 3"
.TH DBD::PgPP 3 "2010-01-09" "perl v5.16.3" "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"
DBD::PgPP \- Pure Perl PostgreSQL driver for the DBI
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use DBI;
\&
\& my $dbh = DBI\->connect(\*(Aqdbi:PgPP:dbname=$dbname\*(Aq, \*(Aq\*(Aq, \*(Aq\*(Aq);
\&
\& # See the DBI module documentation for full details
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
DBD::PgPP is a pure-Perl client interface for the PostgreSQL database. This
module implements the network protocol that allows a client to communicate
with a PostgreSQL server, so you don't need an external PostgreSQL client
library like \fBlibpq\fR for it to work. That means this module enables you to
connect to PostgreSQL server from platforms where there's no PostgreSQL
port, or where installing PostgreSQL is prohibitively hard.
.SH "MODULE DOCUMENTATION"
.IX Header "MODULE DOCUMENTATION"
This documentation describes driver specific behavior and restrictions; it
does not attempt to describe everything you might need to use DBD::PgPP. In
particular, users are advised to be familiar with the \s-1DBI\s0 documentation.
.SH "THE DBI CLASS"
.IX Header "THE DBI CLASS"
.SS "\s-1DBI\s0 Class Methods"
.IX Subsection "DBI Class Methods"
.IP "\fBconnect\fR" 4
.IX Item "connect"
At a minimum, you need to use code like this to connect to the database:
.Sp
.Vb 1
\& $dbh = DBI\->connect(\*(Aqdbi:PgPP:dbname=$dbname\*(Aq, \*(Aq\*(Aq, \*(Aq\*(Aq);
.Ve
.Sp
This connects to the database \f(CW$dbname\fR on localhost without any user
authentication. This may well be sufficient for some PostgreSQL
installations.
.Sp
The following connect statement shows all possible parameters:
.Sp
.Vb 1
\& $dbh = DBI\->connect("dbi:PgPP:dbname=$dbname", $username, $password);
\&
\& $dbh = DBI\->connect("dbi:PgPP:dbname=$dbname;host=$host;port=$port",
\& $username, $password);
\&
\& $dbh = DBI\->connect("dbi:PgPP:dbname=$dbname;path=$path;port=$port",
\& $username, $password);
\&
\& parameter | hard coded default
\& \-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& dbname | current userid
\& host | localhost
\& port | 5432
\& path | /tmp
\& debug | undef
.Ve
.Sp
If a host is specified, the postmaster on this host needs to be started with
the \f(CW\*(C`\-i\*(C'\fR option (\s-1TCP/IP\s0 socket).
.Sp
For authentication with username and password appropriate entries have to be
made in pg_hba.conf. Please refer to the PostgreSQL documentation for
pg_hba.conf and pg_passwd for the various types of authentication.
.SH "DATABASE-HANDLE METHODS"
.IX Header "DATABASE-HANDLE METHODS"
.ie n .IP """last_insert_id""" 4
.el .IP "\f(CWlast_insert_id\fR" 4
.IX Item "last_insert_id"
.Vb 2
\& $rv = $dbh\->last_insert_id($catalog, $schema, $table, $field);
\& $rv = $dbh\->last_insert_id($catalog, $schema, $table, $field, \e%attr);
.Ve
.Sp
Attempts to return the id of the last value to be inserted into a table.
Since PostgreSQL uses the \f(CW\*(C`sequence\*(C'\fR type to implement such things, this
method finds a sequence's value using the \f(CW\*(C`CURRVAL()\*(C'\fR PostgreSQL function.
This will fail if the sequence has not yet been used in the current database
connection.
.Sp
DBD::PgPP ignores the \f(CW$catalog\fR and \f(CW$field\fR arguments are ignored in all
cases, but they're required by \s-1DBI\s0 itself.
.Sp
If you don't know the name of the applicable sequence for the table, you can
simply provide a table name (optionally qualified by a schema name), and
DBD::PgPP will attempt to work out which sequence will contain the correct
value:
.Sp
.Vb 7
\& $dbh\->do(q{CREATE TABLE t (id serial primary key, s text not null)});
\& my $sth = $dbh\->prepare(\*(AqINSERT INTO t (s) VALUES (?)\*(Aq);
\& for my $value (@values) {
\& $sth\->execute($value);
\& my $id = $dbh\->last_insert_id(undef, undef, \*(Aqt\*(Aq, undef);
\& print "Inserted $id: $value\en";
\& }
.Ve
.Sp
In most situations, that is the simplest approach. However, it requires the
table to have at least one column which is non-null and unique, and uses a
sequence as its default value. (If there is more than one such column, the
primary key is used.)
.Sp
If those requirements aren't met in your situation, you can alternatively
specify the sequence name directly:
.Sp
.Vb 12
\& $dbh\->do(q{CREATE SEQUENCE t_id_seq START 1});
\& $dbh\->do(q{CREATE TABLE t (
\& id int not null unique DEFAULT nextval(\*(Aqt_id_seq\*(Aq),
\& s text not null)});
\& my $sth = $dbh\->prepare(\*(AqINSERT INTO t (s) VALUES (?)\*(Aq);
\& for my $value (@values) {
\& $sth\->execute($value);
\& my $id = $dbh\->last_insert_id(undef, undef, undef, undef, {
\& sequence => \*(Aqt_id_seq\*(Aq,
\& });
\& print "Inserted $id: $value\en";
\& }
.Ve
.Sp
If you adopt the simpler approach, note that DBD::PgPP will have to issue
some queries to look things up in the system tables. DBD::PgPP will then
cache the appropriate sequence name for subsequent calls. Should you need
to disable this caching for some reason, you can supply a true value for the
attribute \f(CW\*(C`pgpp_cache\*(C'\fR:
.Sp
.Vb 3
\& my $id = $dbh\->last_insert_id(undef, undef, $table, undef, {
\& pgpp_cache => 0,
\& });
.Ve
.Sp
Please keep in mind that \f(CW\*(C`last_insert_id\*(C'\fR is far from foolproof, so make
your program uses it carefully. Specifically, \f(CW\*(C`last_insert_id\*(C'\fR should be
used only immediately after an insert to the table in question, and that
insert must not specify a value for the applicable column.
.SH "OTHER FUNCTIONS"
.IX Header "OTHER FUNCTIONS"
As of DBD::PgPP 0.06, you can use the following functions to determine the
version of the server to which a database handle is connected. Note the
unusual calling convention; it may be changed in the future.
.ie n .IP """DBD::PgPP::pgpp_server_identification($dbh)""" 4
.el .IP "\f(CWDBD::PgPP::pgpp_server_identification($dbh)\fR" 4
.IX Item "DBD::PgPP::pgpp_server_identification($dbh)"
The server's version identification string, as returned by the standard
\&\f(CW\*(C`version()\*(C'\fR function available in PostgreSQL 7.2 and above. If the server
doesn't support that function, returns an empty string.
.ie n .IP """DBD::PgPP::pgpp_server_version($dbh)""" 4
.el .IP "\f(CWDBD::PgPP::pgpp_server_version($dbh)\fR" 4
.IX Item "DBD::PgPP::pgpp_server_version($dbh)"
The server's version string, as parsed out of the return value of the
standard \f(CW\*(C`version()\*(C'\fR function available in PostgreSQL 7.2 and above. For
example, returns the string \f(CW8.3.5\fR if the server is release 8.3.5. If the
server doesn't support \f(CW\*(C`version()\*(C'\fR, returns the string \f(CW0.0.0\fR.
.ie n .IP """DBD::PgPP::pgpp_server_version_num($dbh)""" 4
.el .IP "\f(CWDBD::PgPP::pgpp_server_version_num($dbh)\fR" 4
.IX Item "DBD::PgPP::pgpp_server_version_num($dbh)"
A number representing the server's version number, as parsed out of the
return value of the standard \f(CW\*(C`version()\*(C'\fR function available in PostgreSQL
7.2 and above. For example, returns 80305 if the server is release 8.3.5.
If the server doesn't support \f(CW\*(C`version()\*(C'\fR, returns zero.
.SH "BUGS, LIMITATIONS, AND TODO"
.IX Header "BUGS, LIMITATIONS, AND TODO"
.IP "\(bu" 4
The \f(CW\*(C`debug\*(C'\fR \s-1DSN\s0 parameter is incorrectly global: if you enable it for one
database handle, it gets enabled for all database handles in the current
Perl interpreter. It should probably be removed entirely in favour of \s-1DBI\s0's
built-in and powerful tracing mechanism, but that's too hard to do in the
current architecture.
.IP "\(bu" 4
No support for Kerberos or \s-1SCM\s0 Credential authentication; and there's no
support for crypt authentication on some platforms.
.IP "\(bu" 4
Can't use \s-1SSL\s0 for encrypted connections.
.IP "\(bu" 4
Using multiple semicolon-separated queries in a single statement will cause
DBD::PgPP to fail in a way that requires you to reconnect to the server.
.IP "\(bu" 4
No support for \s-1COPY\s0, or \s-1LISTEN\s0 notifications, or for cancelling in-progress
queries. (There's also no support for the \*(L"explicit function call\*(R" part of
the protocol, but there's nothing you can do that way that isn't more easily
achieved by writing \s-1SQL\s0 to call the function.)
.IP "\(bu" 4
There's currently no way to get informed about any warnings PostgreSQL may
issue for your queries.
.IP "\(bu" 4
No support for \s-1BLOB\s0 data types or long objects.
.IP "\(bu" 4
Currently assumes that the Perl code and the database use the same encoding
for text; probably also assumes that the encoding uses eight bits per
character. Future versions are expected to support UTF\-8\-encoded Unicode
(in a way that's compatible with Perl's own string encodings).
.IP "\(bu" 4
You can't use any data type that (like bytea) requires \f(CW\*(C`$dbh\->quote\*(C'\fR to
use any syntax other than standard string literals. Using booleans and
numbers works to the extent that PostgreSQL supports string-ish syntax for
them, but that varies from one version to another. The only reliable way to
solve this and still support PostgreSQL 7.3 and below is to use the \s-1DBI\s0
\&\f(CW\*(C`bind_param\*(C'\fR mechanism and say which type you want; but typed bind_param
ignores the type at the moment.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
This module requires Perl 5.8 or higher. (If you want it to work under
earlier Perl versions, patches are welcome.)
.PP
The only module used (other than those which ship with supported Perl
versions) is \s-1DBI\s0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1DBI\s0, DBD::Pg,
<http://developer.postgresql.org/docs/postgres/protocol.html>
.SH "AUTHOR"
.IX Header "AUTHOR"
Hiroyuki \s-1OYAMA\s0 <oyama@module.jp>
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
Copyright (C) 2004 Hiroyuki \s-1OYAMA\s0. All rights reserved.
Copyright (C) 2004, 2005, 2009, 2010 Aaron Crane. All rights reserved.
.PP
DBD::PgPP is free software; you can redistribute it and/or modify it under
the terms of Perl itself, that is to say, under the terms of either:
.IP "\(bu" 4
The \s-1GNU\s0 General Public License as published by the Free Software Foundation;
either version 2, or (at your option) any later version, or
.IP "\(bu" 4
The \*(L"Artistic License\*(R" which comes with Perl.
y~or5J ={Eeu磝Qk ᯘG{?+]ן?wM3X^歌>{7پK>on\jy R g/=fOroNVv~Y+ NGuÝHWyw[eQʨSb> >}Gmx[o[<{Ϯ_qF vM IENDB`
