[svn:DBD-Pg] r11487 - DBD-Pg/trunk

Author: turnstep
Date: Sat Jul  5 20:36:45 2008
New Revision: 11487

Modified:
   DBD-Pg/trunk/Pg.pm

Log:
Some documentation cleanup.


Modified: DBD-Pg/trunk/Pg.pm
==============================================================================
--- DBD-Pg/trunk/Pg.pm	(original)
+++ DBD-Pg/trunk/Pg.pm	Sat Jul  5 20:36:45 2008
@@ -1684,7 +1684,13 @@
   # For some advanced uses you may need PostgreSQL type values:
   use DBD::Pg qw(:pg_types);
 
-  # See the DBI module documentation for full details
+  # For asynchronous calls, import the async constants:
+  use DBD::Pg qw(:async);
+
+  $dbh->do('INSERT INTO mytable(a) VALUES (1)');
+
+  $sth = $dbh->prepare('INSERT INTO mytable(a) VALUES (?)');
+  $sth->execute();
 
 =head1 VERSION
 
@@ -1709,22 +1715,25 @@
 
 =item B<connect>
 
-To connect to a database with a minimum of parameters, use the following
-syntax:
+This method creates a database handle by connecting to a database, and is the DBI 
+equivalent of the "new" method. To connect to a Postgres database with a minimum of parameters, 
+use the following syntax:
 
-  $dbh = DBI->connect("dbi:Pg:dbname=$dbname", '', '');
+  $dbh = DBI->connect("dbi:Pg:dbname=$dbname", '', '', {AutoCommit => 0});
 
 This connects to the database named in the $dbname variable on the default port (usually 5432) 
 without any user authentication.
 
 The following connect statement shows almost all possible parameters:
 
-  $dbh = DBI->connect("dbi:Pg:dbname=$dbname;host=$host;port=$port;" .
-                      "options=$options", "$username", "$password",
-                      {AutoCommit => 0});
+  $dbh = DBI->connect("dbi:Pg:dbname=$dbname;host=$host;port=$port;options=$options",
+                      "$username",
+                      "$password",
+                      {AutoCommit => 0, RaiseError => 1, PrintError => 0}
+                     );
 
-If a parameter is not given, the PostgreSQL server will first look for 
-specific environment variables, and then use hard-coded defaults:
+If a parameter is not given, the connect() method will first look for 
+specific environment variables, and then fall back to hard-coded defaults:
 
   parameter  environment variable  hard coded default
   --------------------------------------------------
@@ -1738,12 +1747,11 @@
   service    PGSERVICE             (none)
   sslmode    PGSSLMODE             (none)
 
-* May also use the word C<db> or C<database>
+* May also use the aliases C<db> or C<database>
 
-For authentication with username and password, appropriate entries have to be
-made in the F<pg_hba.conf> file. If the username and password entries passed 
-via connect() are undefined (as opposed to being empty), DBI will use the 
-environment variables C<DBI_USER> and C<DBI_PASS> if they exists.
+If the username and password values passed via connect() are undefined (as opposed 
+to merely being empty strings), DBI will use the environment variables C<DBI_USER> 
+and C<DBI_PASS> if they exist.
 
 You can also connect by using a service connection file, which is named 
 "pg_service.conf." The location of this file can be controlled by 
@@ -1806,7 +1814,7 @@
 
   @data_sources = DBI->data_sources('Pg');
 
-This driver supports this method. Unless the environment variable C<DBI_DSN> is set, 
+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>.
@@ -1831,13 +1839,13 @@
 
   $rv = $h->err;
 
-Supported by this driver as proposed by DBI. For the connect method it returns
-C<PQstatus>, which is a number used by libpq. A value of 0 indicates no error 
-(CONNECTION_OK), while any other number indicates a failed connection. The only 
-number commonly seen is 1 (CONNECTION_BAD). See the libpq documentation for the 
+Returns the error code from the last method called. For the connect method it returns
+C<PQstatus>, which is a number used by libpq (the Postgres connection library). A value of 0 
+indicates no error (CONNECTION_OK), while any other number indicates a failed connection. The 
+only number commonly seen is 1 (CONNECTION_BAD). See the libpq documentation for the 
 complete list of return codes.
 
-In all other non-connect cases it returns the C<PQresultStatus> of the current
+In all other non-connect methods $h->err returns the C<PQresultStatus> of the current
 handle. This is a number used by libpq and is one of:
 
   0  Empty query string
@@ -1853,20 +1861,19 @@
 
   $str = $h->errstr;
 
-Supported by this driver as proposed by DBI. It returns the last error that was 
-reported by Postgres. This message is affected by the L</pg_error_level> setting.
+Returns the last error that was reported by Postgres. This message is affected 
+by the L</pg_error_level> setting.
 
 =item B<state>
 
   $str = $h->state;
 
-Supported by this driver. Returns a five-character "SQLSTATE" code.
-Success is indicated by a C<00000> code, which gets mapped to an 
-empty string by DBI. A code of C<S8006> indicates a connection failure, 
+Returns a five-character "SQLSTATE" code. Success is indicated by a C<00000> code, which 
+gets mapped to an empty string by DBI. A code of C<S8006> indicates a connection failure, 
 usually because the connection to the PostgreSQL server has been lost.
 
 While this method can be called as either $sth->state or $dbh->state, it 
-is usually clearer to always use the $dbh method.
+is usually clearer to always use $dbh->state.
 
 The list of codes used by PostgreSQL can be found at:
 L<http://www.postgresql.org/docs/current/static/errcodes-appendix.html>