Quick docs and tests for ->last_insert_id, which will fall back to ->…

…last_insert_id, as there is no easy way to track statement-specific last_insert_id

Pg.pm

@@ -3762,6 +3762,14 @@ Note that this method is quite slow because it need additional information from
 server for every column that is simple reference. Consider to use L</pg_canonical_ids>
 instead.
 
+=head3 B<last_insert_id>
+
+  $rv = $sth->last_insert_id(undef, $schema, $table, undef);
+  $rv = $sth->last_insert_id(undef, $schema, $table, undef, {sequence => $seqname});
+
+This is simply an alternative way to return the same information as
+C<< $dbh->last_insert_id >>.
+
 =head2 Statement Handle Attributes
 
 =head3 B<NUM_OF_FIELDS> (integer, read-only)

t/03smethod.t

@@ -21,12 +21,14 @@ my $dbh = connect_database();
 if (! $dbh) {
     plan skip_all => 'Connection to database failed, cannot continue testing';
 }
-plan tests => 136;
+plan tests => 146;
 
 isnt ($dbh, undef, 'Connect to database for statement handle method testing');
 
 my ($SQL, $sth, $sth2, $result, @results, $expected, $rows, $t);
 
+my ($schema,$schema2,$schema3) = ('dbd_pg_testschema', 'dbd_pg_testschema2', 'dbd_pg_testschema3');
+
 #
 # Test of the prepare flags
 #
@@ -810,6 +812,87 @@ $sth->finish;
     $sth->finish;
 }
 
+#
+# Test of the statement handle methods "pg_canonical_ids"
+#
+
+$t='Statement handle method "last_insert_id" fails when no arguments are given';
+$dbh->rollback();
+$sth = $dbh->prepare('SELECT 1');
+eval {
+    $sth->last_insert_id(undef,undef,undef,undef);
+};
+like ($@, qr{last_insert_id.*least}, $t);
+
+$t='Statement handle method "last_insert_id" fails when given a non-existent sequence';
+eval {
+    $sth->last_insert_id(undef,undef,undef,undef,{sequence=>'dbd_pg_nonexistentsequence_test'});
+};
+is ($dbh->state, '42P01', $t);
+
+$t='Statement handle method "last_insert_id" fails when given a non-existent table';
+$dbh->rollback();
+$sth = $dbh->prepare('SELECT 1');
+eval {
+    $sth->last_insert_id(undef,undef,'dbd_pg_nonexistenttable_test',undef);
+};
+like ($@, qr{not find}, $t);
+
+$t='Statement handle method "last_insert_id" fails when given an arrayref as last argument';
+$dbh->rollback();
+$sth = $dbh->prepare('SELECT 1');
+eval {
+    $sth->last_insert_id(undef,undef,'dbd_pg_nonexistenttable_test',undef,[]);
+};
+like ($@, qr{last_insert_id.*hashref}, $t);
+
+$t='Statement handle method "last_insert_id" works when given an empty sequence argument';
+$dbh->rollback();
+$sth = $dbh->prepare('SELECT 1');
+eval {
+    $sth->last_insert_id(undef,undef,'dbd_pg_test',undef,{sequence=>''});
+};
+is ($@, q{}, $t);
+
+$t='Statement handle method "last_insert_id" fails when given a table with no primary key';
+$dbh->rollback();
+$sth = $dbh->prepare('CREATE TEMP TABLE dbd_pg_test_temp(a int)');
+$sth->execute();
+eval {
+    $sth->last_insert_id(undef,undef,'dbd_pg_test_temp',undef);
+};
+like ($@, qr{last_insert_id}, $t);
+
+my $parent = 'dbd_pg_test_parent';
+my $kid = 'dbd_pg_test_inherit';
+$dbh->do("CREATE TABLE $schema.$parent(id SERIAL primary key)");
+$dbh->do("CREATE TABLE $schema.$kid (foo text) INHERITS ($parent)");
+$sth = $dbh->prepare("INSERT INTO $parent DEFAULT VALUES");
+$sth->execute();
+
+$t='Statement handle method "last_insert_id" works for a normal table';
+$result = '';
+eval {
+    $result = $sth->last_insert_id(undef,undef,$parent,undef);
+};
+is ($@, q{}, $t);
+
+$t='Statement handle method "last_insert_id" returns correct value for a normal table';
+is ($result, 1, $t);
+
+$sth = $dbh->prepare("INSERT INTO $kid DEFAULT VALUES");
+$sth->execute();
+
+$t='Statement handle method "last_insert_id" works for an inherited table';
+$result = '';
+eval {
+    $result = $sth->last_insert_id(undef,undef,$kid,undef);
+};
+is ($@, q{}, $t);
+
+$t='Statement handle method "last_insert_id" returns correct value for an inheriteda table';
+is ($result, 2, $t);
+
 
 cleanup_database($dbh,'test');
 $dbh->rollback();