Author: turnstep
Date: Wed Jul 23 17:51:13 2008
New Revision: 11580
Modified:
DBD-Pg/trunk/.perlcriticrc
DBD-Pg/trunk/Changes
DBD-Pg/trunk/Pg.pm
Log:
Make data_sources return additional args, if given.
Lots of documentation cleanups and improvements.
Modified: DBD-Pg/trunk/.perlcriticrc
==============================================================================
--- DBD-Pg/trunk/.perlcriticrc (original)
+++ DBD-Pg/trunk/.perlcriticrc Wed Jul 23 17:51:13 2008
@@ -2,7 +2,7 @@
profile-strictness = quiet
[Documentation::PodSpelling]
-stop_words = ActiveKids AutoCommit boolean Bunce CachedKids ChildHandles
ChopBlanks CompatMode CursorName DBD DBI Datatype dbdpg enum ErrCount
FetchHashKeyName HandleError HandleSetErr InactiveDestroy LongReadLen
LongTruncOk Mergl Momjian Mullane NULLABLE OID PgBouncer pgend pglibpq pglogin
pgprefix pgquote pgstart perl Postgres PostgreSQL PrintError PrintWarn README
RaiseError RowCache RowCacheSize SQL SQLSTATE SSL STDIN STDERR STDOUT Sabino
Savepoints ShowErrorStatement TaintIn TaintOut TraceLevel UTF Username
afterwards arrayrefs attr autocommit backend bitmask bytea cancelled datatype
dbd dbh errstr fd filename getfd getline hashref largeobject len libpq lseg
pgbuiltin pgsql runtime savepoint savepoints schemas sslmode tablename
tablespace tablespaces tuple typename username varchar undef Perlish arrayref
datatypes bool func PID dr
+stop_words = ActiveKids AutoCommit boolean Bunce CachedKids ChildHandles
ChopBlanks CompatMode CursorName DBD DBI Datatype dbdpg enum ErrCount
FetchHashKeyName HandleError HandleSetErr InactiveDestroy LongReadLen
LongTruncOk Mergl Momjian Mullane NULLABLE OID ParamValues ParamTypes PgBouncer
pgend pglibpq pglogin pgprefix pgquote pgstart perl Postgres PostgreSQL
PrintError PrintWarn README RaiseError RowCache RowCacheSize RowsInCache SQL
SQLSTATE SSL STDIN STDERR STDOUT Sabino Savepoints ShowErrorStatement TaintIn
TaintOut TraceLevel UTF Username afterwards arrayrefs attr autocommit backend
bitmask bytea cancelled datatype dbd dbh errstr fd filename getfd getline
hashref largeobject len libpq lseg pgbuiltin pgsql runtime savepoint savepoints
schemas sslmode tablename tablespace tablespaces tuple typename username
varchar undef Perlish arrayref datatypes bool func PID dr
[-Bangs::ProhibitCommentedOutCode]
[-Bangs::ProhibitFlagComments]
Modified: DBD-Pg/trunk/Changes
==============================================================================
--- DBD-Pg/trunk/Changes (original)
+++ DBD-Pg/trunk/Changes Wed Jul 23 17:51:13 2008
@@ -2,7 +2,7 @@
2.8.7
- - Modify test scripts to work better on freebsd boxes.
+ - Modify test scripts to work better on FreeBSD boxes.
- Documentation improvements.
2.8.6 Released July 21, 2008 (subversion r11558)
Modified: DBD-Pg/trunk/Pg.pm
==============================================================================
--- DBD-Pg/trunk/Pg.pm (original)
+++ DBD-Pg/trunk/Pg.pm Wed Jul 23 17:51:13 2008
@@ -170,12 +170,14 @@
if (length $attr) {
$connstring .= ";$attr";
}
+
my $dbh = DBD::Pg::dr::connect($drh, $connstring) or return
undef;
$dbh->{AutoCommit}=1;
my $SQL = 'SELECT pg_catalog.quote_ident(datname) FROM
pg_catalog.pg_database ORDER BY 1';
my $sth = $dbh->prepare($SQL);
$sth->execute() or die $DBI::errstr;
- my @sources = map { "dbi:Pg:dbname=$_->[0]" }
@{$sth->fetchall_arrayref()};
+ $attr and $attr = ";$attr";
+ my @sources = map { "dbi:Pg:dbname=$_->[0]$attr" }
@{$sth->fetchall_arrayref()};
$dbh->disconnect;
return @sources;
}
@@ -1823,17 +1825,23 @@
=item B<data_sources>
@data_sources = DBI->data_sources('Pg');
+ @data_sources = $dbh->data_sources();
Returns a list of available databases. Unless the environment variable
C<DBI_DSN> is set,
a connection will be attempted to the database C<template1>. The normal
connection
environment variables also apply, such as C<PGHOST>, C<PGPORT>, C<DBI_USER>,
C<DBI_PASS>, and C<PGSERVICE>.
-You can also pass in options to add to the connection string as the second
argument
-to the C<data_sources> method. For example, to specify an alternate port and
host:
+You can also pass in options to add to the connection string For example, to
specify
+an alternate port and host:
@data_sources = DBI->data_sources('Pg', 'port=5824;host=example.com');
+ or:
+
+ @data_sources = $dbh->data_sources('port=5824;host=example.com');
+
+
=back
=head1 METHODS COMMON TO ALL HANDLES
@@ -2492,16 +2500,18 @@
=item B<do>
- $rv = $dbh->do($statement, \%attr, @bind_values);
+ $rv = $dbh->do($statement);
+ $rv = $dbh->do($statement, \%attr);
+ $rv = $dbh->do($statement, \%attr, @bind_values);
Prepare and execute a single statement. Returns the number of rows affected if
the
query was successful, returns undef if an error occurred, and returns -1 if
the
number of rows is unknown or not available. Note that this method will return
'0E0' instead
-of 0 for 'no rows were affected', in order to always return a true value if no
error.
+of 0 for 'no rows were affected', in order to always return a true value if no
error occurred.
-If neither attr nor bind_values is given, the query will be sent directly
-to the server without the overhead of creating a statement handle and
-running prepare and execute.
+If neither C<\%attr> nor C<@bind_values> is given, the query will be sent
directly
+to the server without the overhead of internally creating a statement handle
and
+running prepare and execute, for a measurable speed increase.
Note that an empty statement (a string with no length) will not be passed to
the server; if you want a simple test, use "SELECT 123" or the ping()
@@ -2509,15 +2519,15 @@
=item B<last_insert_id>
- $rv = $dbh->last_insert_id($catalog, $schema, $table, $field);
- $rv = $dbh->last_insert_id($catalog, $schema, $table, $field, \%attr);
+ $rv = $dbh->last_insert_id(undef, $schema, $table, undef);
+ $rv = $dbh->last_insert_id(undef, $schema, $table, undef, {sequence =>
$seqname});
Attempts to return the id of the last value to be inserted into a table.
You can either provide a sequence name (preferred) or provide a table
name with optional schema, and DBD::Pg will attempt to find the sequence
itself.
-The $catalog and $field arguments are always ignored. The current value of the
-sequence is returned by a call to the C<CURRVAL()> PostgreSQL function. This
will
-fail if the sequence has not yet been used in the current database connection.
+The current value of the sequence is returned by a call to the C<CURRVAL()>
+PostgreSQL function. This will fail if the sequence has not yet been used in
the
+current database connection.
If you do not know the name of the sequence, you can provide a table name and
DBD::Pg will attempt to return the correct value. To do this, there must be at
@@ -2565,7 +2575,7 @@
=item B<commit>
- $rc = $dbh->commit;
+ $rv = $dbh->commit;
Issues a COMMIT to the server, indicating that the current transaction is
finished and that
all changes made will be visible to other processes. If AutoCommit is enabled,
then
@@ -2574,7 +2584,7 @@
=item B<rollback>
- $rc = $dbh->rollback;
+ $rv = $dbh->rollback;
Issues a ROLLBACK to the server, which discards any changes made in the
current transaction. If AutoCommit
is enabled, then a warning is given and no ROLLBACK is issued. Returns true on
success, and
@@ -2649,7 +2659,7 @@
=item B<ping>
- $rc = $dbh->ping;
+ $rv = $dbh->ping;
This C<ping> method is used to check the validity of a database handle. The
value returned is
either 0, indicating that the connection is no longer valid, or a positive
integer, indicating
@@ -2667,7 +2677,7 @@
=item B<pg_ping>
- $rc = $dbh->pg_ping;
+ $rv = $dbh->pg_ping;
This is a DBD::Pg-specific extension to the C<ping> command. This will check
the
validity of a database handle in exactly the same way as C<ping>, but instead
of
@@ -2823,7 +2833,11 @@
=item B<primary_key>
-Supported by this driver as proposed by DBI.
+ @key_column_names = $dbh->primary_key(undef, $schema, $table);
+
+Simple interface to the L</primary_key_info> method. Returns a list of the
column names that
+comprise the primary key of the specified table. The list is in primary key
column sequence
+order. If there is no primary key then an empty list is returned.
=item B<foreign_key_info>
@@ -2838,6 +2852,17 @@
keys that have no named constraint (where the referenced column only has
an unique index) will return C<undef> for the "UK_NAME" field.
+=item B<statistics_info>
+
+ $sth = $dbh->statistics_info( undef, $schema, $table, $unique_only, $quick );
+
+Returns a statement handle that can be fetched from to give statistics
information
+on a specific table and its indexes. The c<$table> argument is mandatory. The
+C<$schema> argument is optional but recommended. The C<$unique_only> argument,
if true,
+causes only information about unique indexes to be returned. The C<$quick>
argument is
+not used by DBD::Pg. For information on the rows returned, please see the DBI
+documentation.
+
=item B<tables>
@names = $dbh->tables( $catalog, $schema, $table, $type, \%attr );
@@ -2987,6 +3012,13 @@
Exactly the same as L</selectrow_array>, except that it returns a reference to
an hash, by internal use of
the L</fetchrow_hashref> method.
+=item B<clone>
+
+ $other_dbh = $dbh->clone();
+
+Creates a copy of the database handle by connecting with the same parameters
as the original
+handle, then trying to merge the attributes. See the DBI documentation for
complete usage.
+
=back
=head2 Database Handle Attributes
@@ -3008,24 +3040,13 @@
DBD::Pg specific attribute. If true, boolean values will be returned
as the characters 't' and 'f' instead of '1' and '0'.
-=item B<Driver> (handle)
-
-Implemented by DBI, no driver-specific impact.
-
=item B<Name> (string, read-only)
-The default DBI method is overridden by a driver specific method that returns
-only the database name. Anything else from the connection string is stripped
-off. Note that, in contrast to the DBI specs, the DBD::Pg implementation for
-this method is read-only.
-
-=item B<RowCacheSize> (integer)
-
-Implemented by DBI, not used by this driver.
+Returns the name of the current database.
=item B<Username> (string, read-only)
-Supported by this driver as proposed by DBI.
+Returns the name of the user connected to the database.
=item B<pg_enable_utf8> (boolean)
@@ -3036,14 +3057,6 @@
B<NB>: This attribute is experimental and may be subject to change.
-=item B<pg_INV_READ> (integer, read-only)
-
-Constant to be used for the mode in C<lo_creat> and C<lo_open>.
-
-=item B<pg_INV_WRITE> (integer, read-only)
-
-Constant to be used for the mode in C<lo_creat> and C<lo_open>.
-
=item B<pg_errorlevel> (integer)
DBD::Pg specific attribute. Sets the amount of information returned by the
server's
@@ -3119,19 +3132,6 @@
DBD::Pg specific attribute. Returns the process id (PID) of the
backend server process handling the connection.
-=item B<pg_standard_conforming_strings> (boolean, read-only)
-
-DBD::Pg specific attribute. Returns if the server is currently using
-standard conforming strings or not. Only available if the target
-server is version 8.2 or better.
-
-=item B<pg_async_status> (integer, read-only)
-
-DBD::Pg specific attribute. Returns the current status of an asynchronous
-command. 0 indicates no asynchronous command is in progress, 1 indicates that
-an asynchronous command has started and -1 indicated that an asynchronous
command
-has been cancelled.
-
=item B<pg_prepare_now> (boolean)
DBD::Pg specific attribute. Default is off. If true, then the C<prepare()>
method will
@@ -3154,6 +3154,38 @@
DBD::Pg specific attribute. Defaults to false. If false, arrays returned from
the server will
not be changed into a Perl arrayref, but remain as a string.
+=item B<pg_async_status> (integer, read-only)
+
+DBD::Pg specific attribute. Returns the current status of an asynchronous
+command. 0 indicates no asynchronous command is in progress, 1 indicates that
+an asynchronous command has started and -1 indicated that an asynchronous
command
+has been cancelled.
+
+=item B<pg_standard_conforming_strings> (boolean, read-only)
+
+DBD::Pg specific attribute. Returns true if the server is currently using
+standard conforming strings. Only available if the target
+server is version 8.2 or better.
+
+=item B<pg_INV_READ> (integer, read-only)
+
+Constant to be used for the mode in C<lo_creat> and C<lo_open>.
+
+=item B<pg_INV_WRITE> (integer, read-only)
+
+Constant to be used for the mode in C<lo_creat> and C<lo_open>.
+
+=item B<Driver> (handle)
+
+Holds the handle of the parent driver. The only recommended use for this is to
find the name
+of the driver using:
+
+ $dbh->{Driver}->{Name}
+
+=item B<RowCacheSize> (integer)
+
+Not used for DBD::Pg
+
=back
=head1 DBI STATEMENT HANDLE OBJECTS
@@ -3164,6 +3196,8 @@
=item B<bind_param>
+ $rv = $sth->bind_param($param_num, $bind_value);
+ $rv = $sth->bind_param($param_num, $bind_value, $bind_type);
$rv = $sth->bind_param($param_num, $bind_value, \%attr);
Allows the user to bind a value and/or a data type to a placeholder. This is
@@ -3291,7 +3325,13 @@
=item B<bind_param_array>
-Supported by this driver as proposed by DBI.
+
+ $rv = $sth->bind_param_array($param_num, $array_ref_or_value)
+ $rv = $sth->bind_param_array($param_num, $array_ref_or_value, $bind_type)
+ $rv = $sth->bind_param_array($param_num, $array_ref_or_value, \%attr)
+
+Binds an array of values to a placeholder, so that each is used in turn by a
call
+to the L<execute_array> method.
=item B<execute>
@@ -3328,66 +3368,138 @@
=item B<execute_array>
-Supported by this driver as proposed by DBI.
+ $tuples = $sth->execute_array() or die $sth->errstr;
+ $tuples = $sth->execute_array(\%attr) or die $sth->errstr;
+ $tuples = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr;
+
+ ($tuples, $rows) = $sth->execute_array(\%attr) or die $sth->errstr;
+ ($tuples, $rows) = $sth->execute_array(\%attr, @bind_values) or die
$sth->errstr;
+
+Execute a prepared statement once for each item in a passed-in hashref, or
items that
+were previously bound via the L</bind_param_array> method. See the DBI
documentation
+for more details.
=item B<execute_for_fetch>
-Supported by this driver as proposed by DBI.
+ $tuples = $sth->execute_for_fetch($fetch_tuple_sub);
+ $tuples = $sth->execute_for_fetch($fetch_tuple_sub, [EMAIL PROTECTED]);
+
+ ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub);
+ ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub, [EMAIL
PROTECTED]);
+
+Used internally by the L</execute_array> method, and rarely used directly. See
the
+DBI documentation for more details.
=item B<fetchrow_arrayref>
$ary_ref = $sth->fetchrow_arrayref;
-Supported by this driver as proposed by DBI.
+Fetches the next row of data from the statement handle, and returns a
reference to an array
+holding the column values. Any columns that are NULL are returned as undef
within the array.
+
+If there are no more rows or if an error occurs, the this method return undef.
You should
+check $sth->err afterwards (or use the L</RaiseError> attribute) to discover
if the undef returned
+was due to an error.
+
+Note that the same array reference is returned for each fetch, so don't store
the reference and
+then use it after a later fetch. Also, the elements of the array are also
reused for each row,
+so take care if you want to take a reference to an element. See also
L</bind_columns>.
=item B<fetchrow_array>
@ary = $sth->fetchrow_array;
-Supported by this driver as proposed by DBI.
+Similar to the L</fetchrow_arryref> method, but returns a list of column
information rather than
+a reference to a list. Do not use this in a scalar context.
=item B<fetchrow_hashref>
$hash_ref = $sth->fetchrow_hashref;
+ $hash_ref = $sth->fetchrow_hashref($name);
-Supported by this driver as proposed by DBI.
+Fetches the next row of data and returns a hashref containing the name of the
columns as the keys
+and the data itself as the values. Any NULL value is returned as as undef
value.
+
+If there are no more rows or if an error occurs, the this method return undef.
You should
+check $sth->err afterwards (or use the L</RaiseError> attribute) to discover
if the undef returned
+was due to an error.
+
+The optional C<$name> argument should be either C<NAME>, C<NAME_lc> or
C<NAME_uc>, and indicates
+what sort of transformation to make to the keys in the hash.
=item B<fetchall_arrayref>
- $tbl_ary_ref = $sth->fetchall_arrayref;
+ $tbl_ary_ref = $sth->fetchall_arrayref();
+ $tbl_ary_ref = $sth->fetchall_arrayref( $slice );
+ $tbl_ary_ref = $sth->fetchall_arrayref( $slice, $max_rows );
-Implemented by DBI, no driver-specific impact.
+Returns a reference to an array of arrays that contains all the remaining rows
to be fetched from the
+statement handle. If there are no more rows, an empty arrayref will be
returned. If an error occurs,
+the data read in so far will be returned. Because of this, you should always
check C<$sth->err> after
+calling this method, unless L</RaiseError> has been enabled.
+
+If $slice is an array reference, fetchall_arrayref uses the
L<fetchrow_arrayref> method to fetch each
+row as an array ref. If the $slice array is not empty then it is used as a
slice to select individual
+columns by perl array index number (starting at 0, unlike column and parameter
numbers which start at 1).
+
+With no parameters, or if $slice is undefined, fetchall_arrayref acts as if
passed an empty array ref.
+
+If $slice is a hash reference, fetchall_arrayref uses L</fetchrow_hashref> to
fetch each row as a hash reference.
+
+See the DBI documentation for a complete discussion.
+
+=item B<fetchall_arrayref>
+
+ $hash_ref = $sth->fetchall_hashref($key_field);
+
+Returns a hashref containing all rows to be fetched from the statement handle.
See the DBI documentation for
+a full discussion.
=item B<finish>
- $rc = $sth->finish;
+ $rv = $sth->finish;
-Supported by this driver as proposed by DBI.
+Indicates to DBI that you are finished with the statement handle and are not
going to use it again. Only needed
+when you have not fetched all the possible rows.
=item B<rows>
$rv = $sth->rows;
-Supported by this driver as proposed by DBI. In contrast to many other drivers
-the number of rows is available immediately after executing the statement.
+Returns the number of rows returned by the last query. In contrast to many
other drivers,
+the number of rows is available immediately after calling C<$sth->execute>.
Note that
+the L</execute> method itself returns the number of rows itself, which means
that this
+method is rarely needed.
=item B<bind_col>
- $rc = $sth->bind_col($column_number, \$var_to_bind, \%attr);
+ $rc = $sth->bind_col($column_number, \$var_to_bind);
+ $rc = $sth->bind_col($column_number, \$var_to_bind, \%attr );
+ $rc = $sth->bind_col($column_number, \$var_to_bind, $bind_type );
-Supported by this driver as proposed by DBI.
+Binds a Perl variable and/or some attributes to an output column of a SELECT
statement.
+Column numbers count up from 1. You do not need to bind output columns in
order to fetch data.
+
+See the DBI documentation for a discussion of the optional parameters
C<\%attr> and C<$bind_type>
=item B<bind_columns>
- $rc = $sth->bind_columns(\%attr, @list_of_refs_to_vars_to_bind);
+ $rv = $sth->bind_columns(@list_of_refs_to_vars_to_bind);
-Supported by this driver as proposed by DBI.
+Calls the L</bind_col> method for each column in the SELECT statement, using
the supplied list.
=item B<dump_results>
$rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);
-Implemented by DBI, no driver-specific impact.
+Fetches all the rows from the statement handle, calls C<DBI::neat_list> for
each row, and
+prints the results to C<$fh> (which defaults to STDOUT). Rows are separated by
C<$lsep> (which defaults
+to a newline). Columns are separated by C<$fsep> (which defaults to a comma).
The C<$maxlen> controls
+how wide the output can be, and defaults to 35.
+
+This method is designed as a handy utility for prototyping and testing
queries. Since it uses
+"neat_list" to format and edit the string for reading by humans, it is not
recommended
+for data transfer applications.
=item B<blob_read>
@@ -3577,6 +3689,10 @@
DBD::Pg specific attribute. Indicates the current behavior for asynchronous
queries. See the section
on L</Asynchronous Constants> for more information.
+=item B<RowsInCache>
+
+Not used by DBD::Pg
+
=back
=head1 FURTHER INFORMATION
