install/5.005/DBD-Pg-1.22-fixvercmp/Pg.pm

   1
   2 #  $Id: Pg.pm,v 1.1 2004-04-29 09:21:28 ivan Exp $
   3 #
   4 #  Copyright (c) 1997,1998,1999,2000 Edmund Mergl
   5 #  Copyright (c) 2002 Jeffrey W. Baker
   6 #  Portions Copyright (c) 1994,1995,1996,1997 Tim Bunce
   7 #
   8 #  You may distribute under the terms of either the GNU General Public
   9 #  License or the Artistic License, as specified in the Perl README file.
  10
  11
  12 require 5.004;
  13
  14 $DBD::Pg::VERSION = '1.22';
  15
  16 {
  17     package DBD::Pg;
  18
  19     use DBI ();
  20     use DynaLoader ();
  21     use Exporter ();
  22     @ISA = qw(DynaLoader Exporter);
  23
  24     %EXPORT_TAGS = (
  25         pg_types => [ qw(
  26            PG_BOOL PG_BYTEA PG_CHAR PG_INT8 PG_INT2 PG_INT4 PG_TEXT PG_OID
  27            PG_FLOAT4 PG_FLOAT8 PG_ABSTIME PG_RELTIME PG_TINTERVAL PG_BPCHAR
  28            PG_VARCHAR PG_DATE PG_TIME PG_DATETIME PG_TIMESPAN PG_TIMESTAMP
  29         )]);
  30
  31     Exporter::export_ok_tags('pg_types');
  32
  33     require_version DBI 1.00;
  34
  35     bootstrap DBD::Pg $VERSION;
  36
  37     $err = 0;           # holds error code   for DBI::err
  38     $errstr = "";       # holds error string for DBI::errstr
  39     $drh = undef;       # holds driver handle once initialized
  40
  41     sub driver{
  42         return $drh if $drh;
  43         my($class, $attr) = @_;
  44
  45         $class .= "::dr";
  46
  47         # not a 'my' since we use it above to prevent multiple drivers
  48
  49         $drh = DBI::_new_drh($class, {
  50             'Name' => 'Pg',
  51             'Version' => $VERSION,
  52             'Err'    => \$DBD::Pg::err,
  53             'Errstr' => \$DBD::Pg::errstr,
  54             'Attribution' => 'PostgreSQL DBD by Edmund Mergl',
  55         });
  56
  57         $drh;
  58     }
  59
  60     ## Used by both the dr and db packages
  61     sub pg_server_version {
  62                 my $dbh = shift;
  63                 return $dbh->{pg_server_version} if defined $dbh->{pg_server_version};
  64         my ($version) = $dbh->selectrow_array("SELECT version();");
  65         return 0 unless $version =~ /^PostgreSQL ([\d\.]+)/;
  66         $dbh{pg_server_version} = $1;
  67         return $dbh{pg_server_version};
  68         }
  69
  70     sub pg_use_catalog {
  71       my $dbh = shift;
  72       my $version = DBD::Pg::pg_server_version($dbh);
  73       $version =~ /^(\d+\.\d+)/;
  74       return $1 < 7.3 ? "" : "pg_catalog.";
  75     }
  76
  77     1;
  78 }
  79
  80
  81 {   package DBD::Pg::dr; # ====== DRIVER ======
  82     use strict;
  83
  84     sub data_sources {
  85         my $drh = shift;
  86         my $dbh = DBD::Pg::dr::connect($drh, 'dbname=template1') or return undef;
  87         $dbh->{AutoCommit} = 1;
  88         my $CATALOG = DBD::Pg::pg_use_catalog($dbh);
  89         my $sth = $dbh->prepare("SELECT datname FROM ${CATALOG}pg_database ORDER BY datname");
  90         $sth->execute or return undef;
  91         my (@sources, @datname);
  92         while (@datname = $sth->fetchrow_array) {
  93             push @sources, "dbi:Pg:dbname=$datname[0]";
  94         }
  95         $sth->finish;
  96         $dbh->disconnect;
  97         return @sources;
  98     }
  99
 100
 101     sub connect {
 102         my($drh, $dbname, $user, $auth)= @_;
 103
 104         # create a 'blank' dbh
 105
 106         my $Name = $dbname;
 107         $Name =~ s/^.*dbname\s*=\s*//;
 108         $Name =~ s/\s*;.*$//;
 109
 110         $user = "" unless defined($user);
 111         $auth = "" unless defined($auth);
 112
 113         $user = $ENV{DBI_USER} if $user eq "";
 114         $auth = $ENV{DBI_PASS} if $auth eq "";
 115
 116         $user = "" unless defined($user);
 117         $auth = "" unless defined($auth);
 118
 119         my($dbh) = DBI::_new_dbh($drh, {
 120             'Name' => $Name,
 121             'User' => $user, 'CURRENT_USER' => $user,
 122         });
 123
 124         # Connect to the database..
 125         DBD::Pg::db::_login($dbh, $dbname, $user, $auth) or return undef;
 126
 127         $dbh;
 128     }
 129
 130 }
 131
 132
 133 {   package DBD::Pg::db; # ====== DATABASE ======
 134     use strict;
 135     use Carp ();
 136
 137     sub prepare {
 138         my($dbh, $statement, @attribs)= @_;
 139
 140         # create a 'blank' sth
 141
 142         my $sth = DBI::_new_sth($dbh, {
 143             'Statement' => $statement,
 144         });
 145
 146         DBD::Pg::st::_prepare($sth, $statement, @attribs) or return undef;
 147
 148         $sth;
 149     }
 150
 151
 152     sub ping {
 153         my($dbh) = @_;
 154
 155         local $SIG{__WARN__} = sub { } if $dbh->{PrintError};
 156         local $dbh->{RaiseError} = 0 if $dbh->{RaiseError};
 157         my $ret = DBD::Pg::db::_ping($dbh);
 158
 159         return $ret;
 160     }
 161
 162         # Column expected in statement handle returned.
 163         # table_cat, table_schem, table_name, column_name, data_type, type_name,
 164         # column_size, buffer_length, DECIMAL_DIGITS, NUM_PREC_RADIX, NULLABLE,
 165         # REMARKS, COLUMN_DEF, SQL_DATA_TYPE, SQL_DATETIME_SUB, CHAR_OCTET_LENGTH,
 166         # ORDINAL_POSITION, IS_NULLABLE
 167         # The result set is ordered by TABLE_CAT, TABLE_SCHEM,
 168         # TABLE_NAME and ORDINAL_POSITION.
 169
 170         sub column_info {
 171                 my ($dbh) = shift;
 172                 my @attrs = @_;
 173                 # my ($dbh, $catalog, $schema, $table, $column) = @_;
 174                 my $CATALOG = DBD::Pg::pg_use_catalog($dbh);
 175
 176                 my @wh = ();
 177                 my @flds = qw/catname n.nspname c.relname a.attname/;
 178
 179                 for my $idx (0 .. $#attrs) {
 180                         next if ($flds[$idx] eq 'catname'); # Skip catalog
 181                         if(defined $attrs[$idx] and length $attrs[$idx]) {
 182                                 # Insure that the value is enclosed in single quotes.
 183                                 $attrs[$idx] =~ s/^'?(\w+)'?$/'$1'/;
 184                                 if ($attrs[$idx] =~ m/[,%]/) {
 185                                         # contains a meta character.
 186                                         push( @wh, q{( } . join ( " OR "
 187                                                 , map { m/\%/
 188                                                         ? qq{$flds[$idx] ILIKE $_ }
 189                                                         : qq{$flds[$idx]    = $_ }
 190                                                         } (split /,/, $attrs[$idx]) )
 191                                                         . q{ )}
 192                                                 );
 193                                 }
 194                                 else {
 195                                         push( @wh, qq{$flds[$idx] = $attrs[$idx]} );
 196                                 }
 197                         }
 198                 }
 199
 200                 my $wh = ""; # ();
 201                 $wh = join( " AND ", '', @wh ) if (@wh);
 202                 my $version = DBD::Pg::pg_server_version($dbh);
 203                 $version =~ /^(\d+\.\d+)/;
 204                 $version = $1;
 205                 my $showschema = $version < 7.3 ? "NULL::text" : "n.nspname";
 206                 my $schemajoin = $version < 7.3 ? "" : "LEFT JOIN pg_catalog.pg_namespace n ON (n.oid = c.relnamespace)";
 207                 my $col_info_sql = qq{
 208                         SELECT
 209                                   NULL::text    AS "TABLE_CAT"
 210                                 , $showschema   AS "TABLE_SCHEM"
 211                                 , c.relname             AS "TABLE_NAME"
 212                                 , a.attname             AS "COLUMN_NAME"
 213                                 , t.typname             AS "DATA_TYPE"
 214                                 , NULL::text    AS "TYPE_NAME"
 215                                 , a.attlen              AS "COLUMN_SIZE"
 216                                 , NULL::text    AS "BUFFER_LENGTH"
 217                                 , NULL::text    AS "DECIMAL_DIGITS"
 218                                 , NULL::text    AS "NUM_PREC_RADIX"
 219                                 , a.attnotnull  AS "NULLABLE"
 220                                 , NULL::text    AS "REMARKS"
 221                                 , a.atthasdef   AS "COLUMN_DEF"
 222                                 , NULL::text    AS "SQL_DATA_TYPE"
 223                                 , NULL::text    AS "SQL_DATETIME_SUB"
 224                                 , NULL::text    AS "CHAR_OCTET_LENGTH"
 225                                 , a.attnum              AS "ORDINAL_POSITION"
 226                                 , a.attnotnull  AS "IS_NULLABLE"
 227                                 , a.atttypmod   as atttypmod
 228                                 , a.attnotnull  as attnotnull
 229                                 , a.atthasdef   as atthasdef
 230                                 , a.attnum              as attnum
 231                         FROM
 232                                   ${CATALOG}pg_attribute        a
 233                                 , ${CATALOG}pg_type             t
 234                                 , ${CATALOG}pg_class            c
 235                                 $schemajoin
 236                         WHERE
 237                                         a.attrelid = c.oid
 238                                 AND a.attnum  >= 0
 239                                 AND t.oid      = a.atttypid
 240                                 AND c.relkind  in ('r','v')
 241                                 $wh
 242                         ORDER BY 2, 3, 4
 243                 };
 244
 245                 my $sth = $dbh->prepare( $col_info_sql ) or return undef;
 246                 $sth->execute();
 247
 248                 return $sth;
 249         }
 250
 251         sub primary_key_info {
 252         my $dbh = shift;
 253                 my ($catalog, $schema, $table) = @_;
 254                 my @attrs = @_;
 255         my $CATALOG = DBD::Pg::pg_use_catalog($dbh);
 256
 257                 # TABLE_CAT:, TABLE_SCHEM:, TABLE_NAME:, COLUMN_NAME:, KEY_SEQ:
 258                 # , PK_NAME:
 259
 260                 my @wh = (); my @dat = ();  # Used to hold data for the attributes.
 261
 262                 my $version = DBD::Pg::pg_server_version($dbh);
 263                 $version =~ /^(\d+\.\d+)/;
 264                 $version = $1;
 265
 266                 my @flds = qw/catname u.usename bc.relname/;
 267                 $flds[1] = 'n.nspname' unless ($version < 7.3);
 268
 269                 for my $idx (0 .. $#attrs) {
 270                         next if ($flds[$idx] eq 'catname'); # Skip catalog
 271                         if(defined $attrs[$idx] and length $attrs[$idx]) {
 272                                 if ($attrs[$idx] =~ m/[,%_?]/) {
 273                                         # contains a meta character.
 274                                         push( @wh, q{( } . join ( " OR "
 275                                                 , map { push(@dat, $_);
 276                                                         m/[%_?]/
 277                                                         ? qq{$flds[$idx] iLIKE ? }
 278                                                         : qq{$flds[$idx]    = ?  }
 279                                                         } (split /,/, $attrs[$idx]) )
 280                                                         . q{ )}
 281                                                 );
 282                                 }
 283                                 else {
 284                                         push( @dat, $attrs[$idx] );
 285                                         push( @wh, qq{$flds[$idx] = ? } );
 286                                 }
 287                         }
 288                 }
 289
 290                 my $wh = '';
 291                 $wh = join( " AND ", '', @wh ) if (@wh);
 292
 293                 # Base primary key selection query borrowed from phpPgAdmin.
 294                 my $showschema = $version < 7.3 ? "NULL::text" : "n.nspname";
 295                 my $schemajoin = $version < 7.3 ? "" : "LEFT JOIN pg_catalog.pg_namespace n ON (n.oid = bc.relnamespace)";
 296                 my $pri_key_sql = qq{
 297                         SELECT
 298                                 NULL::text              AS "TABLE_CAT"
 299                                 , $showschema   AS "TABLE_SCHEM"
 300                                 , bc.relname    AS "TABLE_NAME"
 301                                 , a.attname             AS "COLUMN_NAME"
 302                                 , a.attnum              AS "KEY_SEQ"
 303                                 , ic.relname    AS "PK_NAME"
 304                         FROM
 305                                 ${CATALOG}pg_index i
 306                                 , ${CATALOG}pg_attribute a
 307                                 , ${CATALOG}pg_class ic
 308                                 , ${CATALOG}pg_class bc
 309                                 $schemajoin
 310                         WHERE
 311                                 i.indrelid = bc.oid
 312                         AND i.indexrelid = ic.oid
 313                         AND
 314                         (
 315                                 i.indkey[0] = a.attnum
 316                                 OR
 317                                 i.indkey[1] = a.attnum
 318                                 OR
 319                                 i.indkey[2] = a.attnum
 320                                 OR
 321                                 i.indkey[3] = a.attnum
 322                                 OR
 323                                 i.indkey[4] = a.attnum
 324                                 OR
 325                                 i.indkey[5] = a.attnum
 326                                 OR
 327                                 i.indkey[6] = a.attnum
 328                                 OR
 329                                 i.indkey[7] = a.attnum
 330                                 OR
 331                                 i.indkey[8] = a.attnum
 332                                 OR
 333                                 i.indkey[9] = a.attnum
 334                                 OR
 335                                 i.indkey[10] = a.attnum
 336                                 OR
 337                                 i.indkey[11] = a.attnum
 338                                 OR
 339                                 i.indkey[12] = a.attnum
 340                         )
 341                         AND a.attrelid = bc.oid
 342                         AND i.indproc = '0'::oid
 343                         AND i.indisprimary = 't'
 344                         $wh
 345                         ORDER BY 2, 3, 5
 346                 };
 347
 348         my $sth = $dbh->prepare( $pri_key_sql ) or return undef;
 349         $sth->execute(@dat);
 350
 351         return $sth;
 352         }
 353
 354     sub foreign_key_info {
 355         # todo: verify schema work as expected
 356         # add code to handle multiple-column keys correctly
 357         # return something nicer for pre-7.3?
 358         # try to clean up SQL, perl code
 359         # create a test script?
 360
 361         my $dbh = shift;
 362         my ($pk_catalog, $pk_schema, $pk_table,
 363                 $fk_catalog, $fk_schema, $fk_table) = @_;
 364
 365         # this query doesn't work for Postgres before 7.3
 366         my $version = $dbh->pg_server_version;
 367         $version =~ /^(\d+)\.(\d)/;
 368         return undef if ($1.$2 < 73);
 369
 370         # Used to hold data for the attributes.
 371         my @dat = ();
 372
 373         # SQL to find primary/unique keys of a table
 374         my $pkey_sql = qq{
 375         SELECT
 376         NULL::text AS PKTABLE_CAT,
 377         pknam.nspname AS PKTABLE_SCHEM,
 378         pkc.relname AS PKTABLE_NAME,
 379         pka.attname AS PKCOLUMN_NAME,
 380         NULL::text AS FKTABLE_CAT,
 381         NULL::text AS FKTABLE_SCHEM,
 382         NULL::text AS FKTABLE_NAME,
 383         NULL::text AS FKCOLUMN_NAME,
 384         pkcon.conkey[1] AS KEY_SEQ,
 385         CASE
 386                 WHEN pkcon.confupdtype = 'c' THEN 0
 387                 WHEN pkcon.confupdtype = 'r' THEN 1
 388                 WHEN pkcon.confupdtype = 'n' THEN 2
 389                 WHEN pkcon.confupdtype = 'a' THEN 3
 390                 WHEN pkcon.confupdtype = 'd' THEN 4
 391                 END AS UPDATE_RULE,
 392         CASE
 393                 WHEN pkcon.confdeltype = 'c' THEN 0
 394                 WHEN pkcon.confdeltype = 'r' THEN 1
 395                 WHEN pkcon.confdeltype = 'n' THEN 2
 396                 WHEN pkcon.confdeltype = 'a' THEN 3
 397                 WHEN pkcon.confdeltype = 'd' THEN 4
 398                 END AS DELETE_RULE,
 399         NULL::text AS FK_NAME,
 400         pkcon.conname AS PK_NAME,
 401         CASE
 402                 WHEN pkcon.condeferrable = 'f' THEN 7
 403                 WHEN pkcon.condeferred = 't' THEN 6
 404                 WHEN pkcon.condeferred = 'f' THEN 5
 405                 END AS DEFERRABILITY,
 406         CASE
 407                 WHEN pkcon.contype = 'p' THEN 'PRIMARY'
 408                 WHEN pkcon.contype = 'u' THEN 'UNIQUE'
 409                 END AS UNIQUE_OR_PRIMARY
 410         FROM
 411                 pg_constraint AS pkcon
 412         JOIN
 413                 pg_class pkc ON pkc.oid=pkcon.conrelid
 414         JOIN
 415                 pg_namespace pknam ON pkcon.connamespace=pknam.oid
 416         JOIN
 417                 pg_attribute pka ON pka.attnum=pkcon.conkey[1] AND pka.attrelid=pkc.oid
 418         };
 419
 420         # SQL to find foreign keys of a table
 421         my $fkey_sql = qq{
 422         SELECT
 423         NULL::text AS PKTABLE_CAT,
 424         pknam.nspname AS PKTABLE_SCHEM,
 425         pkc.relname AS PKTABLE_NAME,
 426         pka.attname AS PKCOLUMN_NAME,
 427         NULL::text AS FKTABLE_CAT,
 428         fknam.nspname AS FKTABLE_SCHEM,
 429         fkc.relname AS FKTABLE_NAME,
 430         fka.attname AS FKCOLUMN_NAME,
 431         fkcon.conkey[1] AS KEY_SEQ,
 432         CASE
 433                 WHEN fkcon.confupdtype = 'c' THEN 0
 434                 WHEN fkcon.confupdtype = 'r' THEN 1
 435                 WHEN fkcon.confupdtype = 'n' THEN 2
 436                 WHEN fkcon.confupdtype = 'a' THEN 3
 437                 WHEN fkcon.confupdtype = 'd' THEN 4
 438                 END AS UPDATE_RULE,
 439         CASE
 440                 WHEN fkcon.confdeltype = 'c' THEN 0
 441                 WHEN fkcon.confdeltype = 'r' THEN 1
 442                 WHEN fkcon.confdeltype = 'n' THEN 2
 443                 WHEN fkcon.confdeltype = 'a' THEN 3
 444                 WHEN fkcon.confdeltype = 'd' THEN 4
 445                 END AS DELETE_RULE,
 446         fkcon.conname AS FK_NAME,
 447         pkcon.conname AS PK_NAME,
 448         CASE
 449                 WHEN fkcon.condeferrable = 'f' THEN 7
 450                 WHEN fkcon.condeferred = 't' THEN 6
 451                 WHEN fkcon.condeferred = 'f' THEN 5
 452                 END AS DEFERRABILITY,
 453         CASE
 454                 WHEN pkcon.contype = 'p' THEN 'PRIMARY'
 455                 WHEN pkcon.contype = 'u' THEN 'UNIQUE'
 456                 END AS UNIQUE_OR_PRIMARY
 457         FROM
 458                 pg_constraint AS fkcon
 459         JOIN
 460                 pg_constraint AS pkcon ON fkcon.confrelid=pkcon.conrelid
 461                         AND fkcon.confkey=pkcon.conkey
 462         JOIN
 463                 pg_class fkc ON fkc.oid=fkcon.conrelid
 464         JOIN
 465                 pg_class pkc ON pkc.oid=fkcon.confrelid
 466         JOIN
 467                 pg_namespace pknam ON pkcon.connamespace=pknam.oid
 468         JOIN
 469                 pg_namespace fknam ON fkcon.connamespace=fknam.oid
 470         JOIN
 471                 pg_attribute fka ON fka.attnum=fkcon.conkey[1] AND fka.attrelid=fkc.oid
 472         JOIN
 473                 pg_attribute pka ON pka.attnum=pkcon.conkey[1] AND pka.attrelid=pkc.oid
 474         };
 475
 476         # if schema are provided, use this SQL
 477         my $pk_schema_sql = " AND pknam.nspname = ? ";
 478         my $fk_schema_sql = " AND fknam.nspname = ? ";
 479
 480         my $key_sql;
 481
 482         # if $fk_table: generate SQL stub, which will be same
 483         # whether or not $pk_table supplied
 484         if ($fk_table)
 485         {
 486                 $key_sql = $fkey_sql . qq{
 487                 WHERE
 488                         fkc.relname = ?
 489                 };
 490                 push @dat, $fk_table;
 491
 492                 if ($fk_schema)
 493                 {
 494                         $key_sql .= $fk_schema_sql;
 495                         push @dat,$fk_schema;
 496                 }
 497         }
 498
 499         # if $fk_table and $pk_table: (defined by DBI, not SQL/CLI)
 500         # return foreign key of $fk_table that refers to $pk_table
 501         # (if any)
 502         if ($pk_table and $fk_table)
 503         {
 504                 $key_sql .= qq{
 505                 AND
 506                         pkc.relname = ?
 507                 };
 508                 push @dat, $pk_table;
 509
 510                 if ($pk_schema)
 511                 {
 512                         $key_sql .= $pk_schema_sql;
 513                         push @dat,$pk_schema;
 514                 }
 515         }
 516
 517         # if $fk_table but no $pk_table:
 518         # return all foreign keys of $fk_table, and all
 519         # primary keys of tables to which $fk_table refers
 520         if (!$pk_table and $fk_table)
 521         {
 522                 # find primary/unique keys referenced by $fk_table
 523                 # (this one is a little tricky)
 524                 $key_sql .= ' UNION ' . $pkey_sql . qq{
 525                 WHERE
 526                         pkcon.conname IN
 527                 (
 528                 SELECT
 529                         pkcon.conname
 530                 FROM
 531                         pg_constraint AS fkcon
 532                 JOIN
 533                         pg_constraint AS pkcon ON fkcon.confrelid=pkcon.conrelid AND
 534                                         fkcon.confkey=pkcon.conkey
 535                 JOIN
 536                         pg_class fkc ON fkc.oid=fkcon.conrelid
 537                 WHERE
 538                         fkc.relname = ?
 539                 )
 540                 };
 541                 push @dat, $fk_table;
 542
 543                 if ($fk_schema)
 544                 {
 545                         $key_sql .= $pk_schema_sql;
 546                         push @dat,$fk_schema;
 547                 }
 548         }
 549
 550         # if $pk_table but no $fk_table:
 551         # return primary key of $pk_table and all foreign keys
 552         # that reference $pk_table
 553         # question: what about unique keys?
 554         # (DBI and SQL/CLI both state to omit unique keys)
 555
 556         if ($pk_table and !$fk_table)
 557         {
 558                 # find primary key (only!) of $pk_table
 559                 $key_sql = $pkey_sql . qq{
 560                 WHERE
 561                         pkc.relname = ?
 562                 AND
 563                         pkcon.contype = 'p'
 564                 };
 565                 @dat = ($pk_table);
 566
 567                 if ($pk_schema)
 568                 {
 569                         $key_sql .= $pk_schema_sql;
 570                         push @dat,$pk_schema;
 571                 }
 572
 573                 # find all foreign keys that reference $pk_table
 574                 $key_sql .= 'UNION ' . $fkey_sql . qq{
 575                 WHERE
 576                         pkc.relname = ?
 577                 AND
 578                         pkcon.contype = 'p'
 579                 };
 580                 push @dat, $pk_table;
 581
 582                 if ($pk_schema)
 583                 {
 584                         $key_sql .= $fk_schema_sql;
 585                         push @dat,$pk_schema;
 586                 }
 587         }
 588
 589         return undef unless $key_sql;
 590         my $sth = $dbh->prepare( $key_sql ) or
 591                 return undef;
 592         $sth->execute(@dat);
 593
 594         return $sth;
 595     }
 596
 597
 598     sub table_info {         # DBI spec: TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TABLE_TYPE, REMARKS
 599         my $dbh = shift;
 600                 my ($catalog, $schema, $table, $type) = @_;
 601                 my @attrs = @_;
 602
 603                 my $tbl_sql = ();
 604
 605         my $version = DBD::Pg::pg_server_version($dbh);
 606         $version =~ /^(\d+\.\d+)/;
 607         $version = $1;
 608         my $CATALOG = DBD::Pg::pg_use_catalog($dbh);
 609
 610                 if ( # Rules 19a
 611                             (defined $catalog and $catalog eq '%')
 612                         and (defined $schema  and $schema  eq  '')
 613                         and (defined $table   and $table   eq  '')
 614                         ) {
 615                                 $tbl_sql = q{
 616                                         SELECT
 617                                            NULL::text    AS "TABLE_CAT"
 618                                          , NULL::text    AS "TABLE_SCHEM"
 619                                          , NULL::text    AS "TABLE_NAME"
 620                                          , NULL::text    AS "TABLE_TYPE"
 621                                          , NULL::text    AS "REMARKS"
 622                                         };
 623                 }
 624                 elsif (# Rules 19b
 625                             (defined $catalog and $catalog eq  '')
 626                         and (defined $schema  and $schema  eq '%')
 627                         and (defined $table   and $table   eq  '')
 628                         ) {
 629                                 $tbl_sql = ($version < 7.3) ? q{
 630                                         SELECT
 631                                            NULL::text    AS "TABLE_CAT"
 632                                          , NULL::text    AS "TABLE_SCHEM"
 633                                          , NULL::text    AS "TABLE_NAME"
 634                                          , NULL::text    AS "TABLE_TYPE"
 635                                          , NULL::text    AS "REMARKS"
 636                     } : q{
 637                                         SELECT
 638                                            NULL::text    AS "TABLE_CAT"
 639                                          , n.nspname     AS "TABLE_SCHEM"
 640                                          , NULL::text    AS "TABLE_NAME"
 641                                          , NULL::text    AS "TABLE_TYPE"
 642                                          , NULL::text    AS "REMARKS"
 643                                         FROM pg_catalog.pg_namespace n
 644                                         ORDER BY 1
 645                                         };
 646                 }
 647                 elsif (# Rules 19c
 648                             (defined $catalog and $catalog eq  '')
 649                         and (defined $schema  and $schema  eq  '')
 650                         and (defined $table   and $table   eq  '')
 651                         and (defined $type    and $type    eq  '%')
 652                         ) {
 653                                 # From the postgresql 7.2.1 manual 3.5 pg_class
 654                                 #  'r' = ordinary table
 655                                 #, 'i' = index
 656                                 #, 'S' = sequence
 657                                 #, 'v' = view
 658                                 #, 's' = special
 659                                 #, 't' = secondary TOAST table
 660                                 $tbl_sql = q{
 661                                         SELECT
 662                                            NULL::text    AS "TABLE_CAT"
 663                                          , NULL::text    AS "TABLE_SCHEM"
 664                                          , NULL::text    AS "TABLE_NAME"
 665                                          , 'table'       AS "TABLE_TYPE"
 666                                          , 'ordinary table - r'    AS "REMARKS"
 667                                         union
 668                                         SELECT
 669                                            NULL::text    AS "TABLE_CAT"
 670                                          , NULL::text    AS "TABLE_SCHEM"
 671                                          , NULL::text    AS "TABLE_NAME"
 672                                          , 'index'       AS "TABLE_TYPE"
 673                                          , 'index - i'    AS "REMARKS"
 674                                         union
 675                                         SELECT
 676                                            NULL::text    AS "TABLE_CAT"
 677                                          , NULL::text    AS "TABLE_SCHEM"
 678                                          , NULL::text    AS "TABLE_NAME"
 679                                          , 'sequence'     AS "TABLE_TYPE"
 680                                          , 'sequence - S'    AS "REMARKS"
 681                                         union
 682                                         SELECT
 683                                            NULL::text    AS "TABLE_CAT"
 684                                          , NULL::text    AS "TABLE_SCHEM"
 685                                          , NULL::text    AS "TABLE_NAME"
 686                                          , 'view'       AS "TABLE_TYPE"
 687                                          , 'view - v'    AS "REMARKS"
 688                                         union
 689                                         SELECT
 690                                            NULL::text    AS "TABLE_CAT"
 691                                          , NULL::text    AS "TABLE_SCHEM"
 692                                          , NULL::text    AS "TABLE_NAME"
 693                                          , 'special'       AS "TABLE_TYPE"
 694                                          , 'special - s'    AS "REMARKS"
 695                                         union
 696                                         SELECT
 697                                            NULL::text    AS "TABLE_CAT"
 698                                          , NULL::text    AS "TABLE_SCHEM"
 699                                          , NULL::text    AS "TABLE_NAME"
 700                                          , 'secondary'   AS "TABLE_TYPE"
 701                                          , 'secondary TOAST table - t'    AS "REMARKS"
 702                                 };
 703                 }
 704                 else {
 705                                 # Default SQL
 706                                 my $showschema = $version < 7.3 ? "NULL::text" : "n.nspname";
 707                                 my $schemajoin = $version < 7.3 ? "" : "LEFT JOIN pg_catalog.pg_namespace n ON (n.oid = c.relnamespace)";
 708                                 my $schemacase = $version < 7.3 ? "CASE WHEN c.relname ~ '^pg_' THEN 'SYSTEM TABLE' ELSE 'TABLE' END" :
 709                                         "CASE WHEN n.nspname ~ '^pg_' THEN 'SYSTEM TABLE' ELSE 'TABLE' END";
 710                                 $tbl_sql = qq{
 711                                 SELECT NULL::text    AS "TABLE_CAT"
 712                                          , $showschema   AS "TABLE_SCHEM"
 713                                          , c.relname     AS "TABLE_NAME"
 714                                          , CASE
 715                                                  WHEN c.relkind = 'v' THEN 'VIEW'
 716                                                  ELSE $schemacase
 717                                                 END                      AS "TABLE_TYPE"
 718                                          , d.description AS "REMARKS"
 719                                 FROM ${CATALOG}pg_user          AS u
 720                                    , ${CATALOG}pg_class         AS c
 721                                          LEFT JOIN
 722                                          ${CATALOG}pg_description       AS d
 723                                                 ON (c.relfilenode = d.objoid AND d.objsubid = 0)
 724                                 $schemajoin
 725                                 WHERE
 726                                           ((c.relkind     =  'r'
 727                                   AND c.relhasrules =  FALSE) OR
 728                                           (c.relkind     =  'v'
 729                                   AND c.relhasrules =  TRUE))
 730                                   AND c.relname     !~ '^xin[vx][0-9]+'
 731                                   AND c.relowner    =  u.usesysid
 732                                 ORDER BY 1, 2, 3
 733                                 };
 734
 735                         # Did we receive any arguments?
 736                         if (@attrs) {
 737                                 my @wh = ();
 738                                 my @flds = qw/catname n.nspname c.relname c.relkind/;
 739
 740                                 for my $idx (0 .. $#attrs) {
 741                                         next if ($flds[$idx] eq 'catname'); # Skip catalog
 742                                         if(defined $attrs[$idx] and length $attrs[$idx]) {
 743                                                 # Change the "name" of the types to the real value.
 744                                                 if ($flds[$idx]  =~ m/relkind/) {
 745                                                         $attrs[$idx] =~ s/^\'?table\'?/'r'/i;
 746                                                         $attrs[$idx] =~ s/^\'?index\'?/'i'/i;
 747                                                         $attrs[$idx] =~ s/^\'?sequence\'?/'S'/i;
 748                                                         $attrs[$idx] =~ s/^\'?view\'?/'v'/i;
 749                                                         $attrs[$idx] =~ s/^\'?special\'?/'s'/i;
 750                                                         $attrs[$idx] =~ s/^\'?secondary\'?/'t'/i;
 751                                                 }
 752                                                 # Insure that the value is enclosed in single quotes.
 753                                                 $attrs[$idx] =~ s/^'?(\w+)'?$/'$1'/;
 754                                                 if ($attrs[$idx] =~ m/[,%]/) {
 755                                                         # contains a meta character.
 756                                                         push( @wh, q{( } . join ( " OR "
 757                                                                 , map { m/\%/
 758                                                                         ? qq{$flds[$idx] LIKE $_ }
 759                                                                         : qq{$flds[$idx]    = $_ }
 760                                                                         } (split /,/, $attrs[$idx]) )
 761                                                                         . q{ )}
 762                                                                 );
 763                                                 }
 764                                                 else {
 765                                                         push( @wh, qq{$flds[$idx] = $attrs[$idx]} );
 766                                                 }
 767                                         }
 768                                 }
 769
 770                                 my $wh = ();
 771                                 if (@wh) {
 772                                         $wh = join( " AND ",'', @wh );
 773                                         $tbl_sql = qq{
 774                                         SELECT NULL::text    AS "TABLE_CAT"
 775                                                  , $showschema   AS "TABLE_SCHEM"
 776                                                  , c.relname     AS "TABLE_NAME"
 777                                                  , CASE
 778                                                          WHEN c.relkind = 'r' THEN
 779                                                                 CASE WHEN n.nspname ~ '^pg_' THEN 'SYSTEM TABLE' ELSE 'TABLE' END
 780                                                          WHEN c.relkind = 'v' THEN 'VIEW'
 781                                                          WHEN c.relkind = 'i' THEN 'INDEX'
 782                                                          WHEN c.relkind = 'S' THEN 'SEQUENCE'
 783                                                          WHEN c.relkind = 's' THEN 'SPECIAL'
 784                                                          WHEN c.relkind = 't' THEN 'SECONDARY'
 785                                                          ELSE 'UNKNOWN'
 786                                                         END                      AS "TABLE_TYPE"
 787                                                  , d.description AS "REMARKS"
 788                                         FROM ${CATALOG}pg_class         AS c
 789                                                 LEFT JOIN
 790                                                  ${CATALOG}pg_description       AS d
 791                                                         ON (c.relfilenode = d.objoid AND d.objsubid = 0)
 792                                                 $schemajoin
 793                                         WHERE
 794                                                   c.relname     !~ '^xin[vx][0-9]+'
 795                                           $wh
 796                                         ORDER BY 2, 3
 797                                         };
 798                                 }
 799                         }
 800                 }
 801
 802         my $sth = $dbh->prepare( $tbl_sql ) or return undef;
 803         $sth->execute();
 804
 805         return $sth;
 806     }
 807
 808
 809     sub tables {
 810         my($dbh) = @_;
 811         my $version = DBD::Pg::pg_server_version($dbh);
 812         $version =~ /^(\d+\.\d+)/;
 813         $version = $1;
 814         my $SQL = ($version < 7.3) ?
 815             "SELECT relname  AS \"TABLE_NAME\"
 816             FROM   pg_class
 817             WHERE  relkind = 'r'
 818             AND    relname !~ '^pg_'
 819             AND    relname !~ '^xin[vx][0-9]+'
 820             ORDER BY 1" :
 821             "SELECT n.nspname AS \"SCHEMA_NAME\", c.relname  AS \"TABLE_NAME\"
 822             FROM   pg_catalog.pg_class c
 823             LEFT JOIN pg_catalog.pg_namespace n ON (n.oid = c.relnamespace)
 824             WHERE  c.relkind = 'r'
 825             AND n.nspname NOT IN ('pg_catalog', 'pg_toast')
 826             AND pg_catalog.pg_table_is_visible(c.oid)
 827             ORDER BY 1,2";
 828         my $sth = $dbh->prepare($SQL) or return undef;
 829         $sth->execute or return undef;
 830         my (@tables, @relname);
 831         while (@relname = $sth->fetchrow_array) {
 832             push @tables, $version < 7.3 ? $relname[0] : "$relname[0].$relname[1]";
 833         }
 834         $sth->finish;
 835
 836         return @tables;
 837     }
 838
 839
 840     sub table_attributes {
 841         my ($dbh, $table) = @_;
 842         my $CATALOG = DBD::Pg::pg_use_catalog($dbh);
 843         my $result = [];
 844         my $attrs  = $dbh->selectall_arrayref(
 845              "select a.attname, t.typname, a.attlen, a.atttypmod, a.attnotnull, a.atthasdef, a.attnum
 846               from ${CATALOG}pg_attribute a,
 847                    ${CATALOG}pg_class     c,
 848                    ${CATALOG}pg_type      t
 849               where c.relname  = ?
 850                 and a.attrelid = c.oid
 851                 and a.attnum  >= 0
 852                 and t.oid      = a.atttypid
 853                 order by 1
 854              ", undef, $table);
 855
 856         return $result unless scalar(@$attrs);
 857
 858         # Select the array value for tables primary key.
 859         my $pk_key_sql = qq{SELECT pg_index.indkey
 860                             FROM   ${CATALOG}pg_class, ${CATALOG}pg_index
 861                             WHERE
 862                                    pg_class.oid          = pg_index.indrelid
 863                             AND    pg_class.relname      = '$table'
 864                             AND    pg_index.indisprimary = 't'
 865                         };
 866         # Expand this (returned as a string) a real array.
 867         my @pk = ();
 868     my $pkeys = $dbh->selectrow_array( $pk_key_sql );
 869     if (defined $pkeys) {
 870         foreach (split( /\s+/, $pkeys))
 871             {
 872                     push @pk, $_;
 873             }
 874     }
 875         my $pk_bt =
 876                 (@pk)   ? "AND    pg_attribute.attnum in (" . join ( ", ", @pk ) . ")"
 877                         : "";
 878
 879         # Get the primary key
 880         my $pri_key = $dbh->selectcol_arrayref("SELECT pg_attribute.attname
 881                                                FROM   ${CATALOG}pg_class, ${CATALOG}pg_attribute, ${CATALOG}pg_index
 882                                                WHERE  pg_class.oid          = pg_attribute.attrelid
 883                                                AND    pg_class.oid          = pg_index.indrelid
 884                                                $pk_bt
 885                                                AND    pg_index.indisprimary = 't'
 886                                                AND    pg_class.relname      = ?
 887                                                ORDER BY pg_attribute.attnum
 888                                                ", undef, $table );
 889         $pri_key = [] unless $pri_key;
 890
 891         foreach my $attr (reverse @$attrs) {
 892             my ($col_name, $col_type, $size, $mod, $notnull, $hasdef, $attnum) = @$attr;
 893             my $col_size = do {
 894                 if ($size > 0) {
 895                     $size;
 896                 } elsif ($mod > 0xffff) {
 897                     my $prec = ($mod & 0xffff) - 4;
 898                     $mod >>= 16;
 899                     my $dig = $mod;
 900                     $dig;
 901                 } elsif ($mod >= 4) {
 902                     $mod - 4;
 903                 } else {
 904                     $mod;
 905                 }
 906             };
 907
 908             # Get the default value, if any
 909             my ($default) = $dbh->selectrow_array("SELECT adsrc FROM ${CATALOG}pg_attrdef WHERE  adnum = $attnum") if -1 == $attnum;
 910             $default = '' unless $default;
 911
 912             # Test for any constraints
 913             # Note: as of PostgreSQL 7.3 pg_relcheck has been replaced
 914             # by pg_constraint. To maintain compatibility, check
 915             # version number and execute appropriate query.
 916
 917             my $version = pg_server_version( $dbh );
 918
 919             my $con_query = $version < 7.3
 920              ? "SELECT rcsrc FROM pg_relcheck WHERE rcname = '${table}_$col_name'"
 921              : "SELECT consrc FROM pg_catalog.pg_constraint WHERE contype = 'c' AND conname = '${table}_$col_name'";
 922             my ($constraint) = $dbh->selectrow_array($con_query);
 923             $constraint = '' unless $constraint;
 924
 925             # Check to see if this is the primary key
 926             my $is_primary_key = scalar(grep { /^$col_name$/i } @$pri_key) ? 1 : 0;
 927
 928             push @$result,
 929                 { NAME        => $col_name,
 930                   TYPE        => $col_type,
 931                   SIZE        => $col_size,
 932                   NOTNULL     => $notnull,
 933                   DEFAULT     => $default,
 934                   CONSTRAINT  => $constraint,
 935                   PRIMARY_KEY => $is_primary_key,
 936                 };
 937         }
 938
 939         return $result;
 940     }
 941
 942
 943     sub type_info_all {
 944         my ($dbh) = @_;
 945
 946         #my $names = {
 947     #      TYPE_NAME            => 0,
 948     #      DATA_TYPE            => 1,
 949     #      PRECISION            => 2,
 950     #      LITERAL_PREFIX       => 3,
 951     #      LITERAL_SUFFIX       => 4,
 952     #      CREATE_PARAMS                => 5,
 953     #      NULLABLE             => 6,
 954     #      CASE_SENSITIVE       => 7,
 955     #      SEARCHABLE           => 8,
 956     #      UNSIGNED_ATTRIBUTE   => 9,
 957     #      MONEY                        =>10,
 958     #      AUTO_INCREMENT       =>11,
 959     #      LOCAL_TYPE_NAME      =>12,
 960     #      MINIMUM_SCALE                =>13,
 961     #      MAXIMUM_SCALE                =>14,
 962     #    };
 963
 964         my $names = {
 965         TYPE_NAME         => 0,
 966         DATA_TYPE         => 1,
 967         COLUMN_SIZE       => 2,     # was PRECISION originally
 968         LITERAL_PREFIX    => 3,
 969         LITERAL_SUFFIX    => 4,
 970         CREATE_PARAMS     => 5,
 971         NULLABLE          => 6,
 972         CASE_SENSITIVE    => 7,
 973         SEARCHABLE        => 8,
 974         UNSIGNED_ATTRIBUTE=> 9,
 975         FIXED_PREC_SCALE  => 10,    # was MONEY originally
 976         AUTO_UNIQUE_VALUE => 11,    # was AUTO_INCREMENT originally
 977         LOCAL_TYPE_NAME   => 12,
 978         MINIMUM_SCALE     => 13,
 979         MAXIMUM_SCALE     => 14,
 980         NUM_PREC_RADIX    => 15,
 981     };
 982
 983
 984         #  typname       |typlen|typprtlen|    SQL92
 985         #  --------------+------+---------+    -------
 986         #  bool          |     1|        1|    BOOLEAN
 987         #  text          |    -1|       -1|    like VARCHAR, but automatic storage allocation
 988         #  bpchar        |    -1|       -1|    CHARACTER(n)    bp=blank padded
 989         #  varchar       |    -1|       -1|    VARCHAR(n)
 990         #  int2          |     2|        5|    SMALLINT
 991         #  int4          |     4|       10|    INTEGER
 992         #  int8          |     8|       20|    /
 993         #  money         |     4|       24|    /
 994         #  float4        |     4|       12|    FLOAT(p)   for p<7=float4, for p<16=float8
 995         #  float8        |     8|       24|    REAL
 996         #  abstime       |     4|       20|    /
 997         #  reltime       |     4|       20|    /
 998         #  tinterval     |    12|       47|    /
 999         #  date          |     4|       10|    /
1000         #  time          |     8|       16|    /
1001         #  datetime      |     8|       47|    /
1002         #  timespan      |    12|       47|    INTERVAL
1003         #  timestamp     |     4|       19|    TIMESTAMP
1004         #  --------------+------+---------+
1005
1006         # DBI type definitions / PostgreSQL definitions     # type needs to be DBI-specific (not pg_type)
1007         #
1008         # SQL_ALL_TYPES  0
1009         # SQL_CHAR       1      1042 bpchar
1010         # SQL_NUMERIC    2       700 float4
1011         # SQL_DECIMAL    3       700 float4
1012         # SQL_INTEGER    4        23 int4
1013         # SQL_SMALLINT   5        21 int2
1014         # SQL_FLOAT      6       700 float4
1015         # SQL_REAL       7       701 float8
1016         # SQL_DOUBLE     8        20 int8
1017         # SQL_DATE       9      1082 date
1018         # SQL_TIME      10      1083 time
1019         # SQL_TIMESTAMP 11      1296 timestamp
1020         # SQL_VARCHAR   12      1043 varchar
1021
1022         my $ti = [
1023           $names,
1024           # name          type  prec  prefix suffix  create params null case se unsign mon  incr       local   min    max
1025           #
1026           [ 'bytea',        -2, 4096,  '\'',  '\'',           undef, 1, '1', 3, undef, '0', '0',     'BYTEA', undef, undef, undef ],
1027           [ 'bool',          0,    1,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0',   'BOOLEAN', undef, undef, undef ],
1028           [ 'int8',          8,   20, undef, undef,           undef, 1, '0', 2,   '0', '0', '0',   'LONGINT', undef, undef, undef ],
1029           [ 'int2',          5,    5, undef, undef,           undef, 1, '0', 2,   '0', '0', '0',  'SMALLINT', undef, undef, undef ],
1030           [ 'int4',          4,   10, undef, undef,           undef, 1, '0', 2,   '0', '0', '0',   'INTEGER', undef, undef, undef ],
1031           [ 'text',         12, 4096,  '\'',  '\'',           undef, 1, '1', 3, undef, '0', '0',      'TEXT', undef, undef, undef ],
1032           [ 'float4',        6,   12, undef, undef,     'precision', 1, '0', 2,   '0', '0', '0',     'FLOAT', undef, undef, undef ],
1033           [ 'float8',        7,   24, undef, undef,     'precision', 1, '0', 2,   '0', '0', '0',      'REAL', undef, undef, undef ],
1034           [ 'abstime',      10,   20,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0',   'ABSTIME', undef, undef, undef ],
1035           [ 'reltime',      10,   20,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0',   'RELTIME', undef, undef, undef ],
1036           [ 'tinterval',    11,   47,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0', 'TINTERVAL', undef, undef, undef ],
1037           [ 'money',         0,   24, undef, undef,           undef, 1, '0', 2, undef, '1', '0',     'MONEY', undef, undef, undef ],
1038           [ 'bpchar',        1, 4096,  '\'',  '\'',    'max length', 1, '1', 3, undef, '0', '0', 'CHARACTER', undef, undef, undef ],
1039           [ 'bpchar',       12, 4096,  '\'',  '\'',    'max length', 1, '1', 3, undef, '0', '0', 'CHARACTER', undef, undef, undef ],
1040           [ 'varchar',      12, 4096,  '\'',  '\'',    'max length', 1, '1', 3, undef, '0', '0',   'VARCHAR', undef, undef, undef ],
1041           [ 'date',          9,   10,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0',      'DATE', undef, undef, undef ],
1042           [ 'time',         10,   16,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0',      'TIME', undef, undef, undef ],
1043           [ 'datetime',     11,   47,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0',  'DATETIME', undef, undef, undef ],
1044           [ 'timespan',     11,   47,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0',  'INTERVAL', undef, undef, undef ],
1045           [ 'timestamp',    10,   19,  '\'',  '\'',           undef, 1, '0', 2, undef, '0', '0', 'TIMESTAMP', undef, undef, undef ]
1046           #
1047           # intentionally omitted: char, all geometric types, all array types
1048         ];
1049         return $ti;
1050     }
1051
1052
1053     # Characters that need to be escaped by quote().
1054     my %esc = ( "'"  => '\\047', # '\\' . sprintf("%03o", ord("'")), # ISO SQL 2
1055                 '\\' => '\\134', # '\\' . sprintf("%03o", ord("\\")),
1056               );
1057
1058     # Set up lookup for SQL types we don't want to escape.
1059     my %no_escape = map { $_ => 1 }
1060       DBI::SQL_INTEGER, DBI::SQL_SMALLINT, DBI::SQL_DECIMAL,
1061       DBI::SQL_FLOAT, DBI::SQL_REAL, DBI::SQL_DOUBLE, DBI::SQL_NUMERIC;
1062
1063     sub quote {
1064         my ($dbh, $str, $data_type) = @_;
1065         return "NULL" unless defined $str;
1066                 return $str if $data_type && $no_escape{$data_type};
1067
1068         $dbh->DBI::set_err(1, "Use of SQL_BINARY invalid in quote()")
1069           if $data_type && $data_type == DBI::SQL_BINARY;
1070
1071                 $str =~ s/(['\\\0])/$esc{$1}/g;
1072                 return "'$str'";
1073     }
1074
1075 }    # end of package DBD::Pg::db
1076
1077 {   package DBD::Pg::st; # ====== STATEMENT ======
1078
1079     # all done in XS
1080
1081 }
1082
1083 1;
1084
1085 __END__
1086
1087 =head1 NAME
1088
1089 DBD::Pg - PostgreSQL database driver for the DBI module
1090
1091 =head1 SYNOPSIS
1092
1093   use DBI;
1094
1095   $dbh = DBI->connect("dbi:Pg:dbname=$dbname", "", "");
1096
1097   # for some advanced uses you may need PostgreSQL type values:
1098   use DBD::Oracle qw(:pg_types);
1099
1100   # See the DBI module documentation for full details
1101
1102 =head1 DESCRIPTION
1103
1104 DBD::Pg is a Perl module which works with the DBI module to provide access to
1105 PostgreSQL databases.
1106
1107 =head1 MODULE DOCUMENTATION
1108
1109 This documentation describes driver specific behavior and restrictions. It is
1110 not supposed to be used as the only reference for the user. In any case
1111 consult the DBI documentation first!
1112
1113 =head1 THE DBI CLASS
1114
1115 =head2 DBI Class Methods
1116
1117 =over 4
1118
1119 =item B<connect>
1120
1121 To connect to a database with a minimum of parameters, use the following
1122 syntax:
1123
1124   $dbh = DBI->connect("dbi:Pg:dbname=$dbname", "", "");
1125
1126 This connects to the database $dbname at localhost without any user
1127 authentication. This is sufficient for the defaults of PostgreSQL.
1128
1129 The following connect statement shows all possible parameters:
1130
1131   $dbh = DBI->connect("dbi:Pg:dbname=$dbname;host=$host;port=$port;" .
1132                       "options=$options;tty=$tty", "$username", "$password");
1133
1134 If a parameter is undefined PostgreSQL first looks for specific environment
1135 variables and then it uses hard coded defaults:
1136
1137     parameter  environment variable  hard coded default
1138     --------------------------------------------------
1139     dbname     PGDATABASE            current userid
1140     host       PGHOST                localhost
1141     port       PGPORT                5432
1142     options    PGOPTIONS             ""
1143     tty        PGTTY                 ""
1144     username   PGUSER                current userid
1145     password   PGPASSWORD            ""
1146
1147 If a host is specified, the postmaster on this host needs to be started with
1148 the C<-i> option (TCP/IP sockets).
1149
1150 The options parameter specifies runtime options for the Postgres
1151 backend. Common usage is to increase the number of buffers with the C<-B>
1152 option. Also important is the C<-F> option, which disables automatic fsync()
1153 call after each transaction. For further details please refer to the
1154 L<postgres>.
1155
1156 For authentication with username and password appropriate entries have to be
1157 made in pg_hba.conf. Please refer to the L<pg_hba.conf> and the L<pg_passwd>
1158 for the different types of authentication. Note that for these two parameters
1159 DBI distinguishes between empty and undefined. If these parameters are
1160 undefined DBI substitutes the values of the environment variables DBI_USER and
1161 DBI_PASS if present.
1162
1163 =item B<available_drivers>
1164
1165   @driver_names = DBI->available_drivers;
1166
1167 Implemented by DBI, no driver-specific impact.
1168
1169 =item B<data_sources>
1170
1171   @data_sources = DBI->data_sources('Pg');
1172
1173 The driver supports this method. Note that the necessary database connection to
1174 the database template1 will be done on the localhost without any
1175 user-authentication. Other preferences can only be set with the environment
1176 variables PGHOST, DBI_USER and DBI_PASS.
1177
1178 =item B<trace>
1179
1180   DBI->trace($trace_level, $trace_file)
1181
1182 Implemented by DBI, no driver-specific impact.
1183
1184 =back
1185
1186 =head2 DBI Dynamic Attributes
1187
1188 See Common Methods.
1189
1190 =head1 METHODS COMMON TO ALL HANDLES
1191
1192 =over 4
1193
1194 =item B<err>
1195
1196   $rv = $h->err;
1197
1198 Supported by the driver as proposed by DBI. For the connect method it returns
1199 PQstatus. In all other cases it returns PQresultStatus of the current handle.
1200
1201 =item B<errstr>
1202
1203   $str = $h->errstr;
1204
1205 Supported by the driver as proposed by DBI. It returns the PQerrorMessage
1206 related to the current handle.
1207
1208 =item B<state>
1209
1210   $str = $h->state;
1211
1212 This driver does not (yet) support the state method.
1213
1214 =item B<trace>
1215
1216   $h->trace($trace_level, $trace_filename);
1217
1218 Implemented by DBI, no driver-specific impact.
1219
1220 =item B<trace_msg>
1221
1222   $h->trace_msg($message_text);
1223
1224 Implemented by DBI, no driver-specific impact.
1225
1226 =item B<func>
1227
1228 This driver supports a variety of driver specific functions accessible via the
1229 func interface:
1230
1231   $attrs = $dbh->func($table, 'table_attributes');
1232
1233 This method returns for the given table a reference to an array of hashes:
1234
1235   NAME        attribute name
1236   TYPE        attribute type
1237   SIZE        attribute size (-1 for variable size)
1238   NULLABLE    flag nullable
1239   DEFAULT     default value
1240   CONSTRAINT  constraint
1241   PRIMARY_KEY flag is_primary_key
1242
1243   $lobjId = $dbh->func($mode, 'lo_creat');
1244
1245 Creates a new large object and returns the object-id. $mode is a bit-mask
1246 describing different attributes of the new object. Use the following
1247 constants:
1248
1249   $dbh->{pg_INV_WRITE}
1250   $dbh->{pg_INV_READ}
1251
1252 Upon failure it returns undef.
1253
1254   $lobj_fd = $dbh->func($lobjId, $mode, 'lo_open');
1255
1256 Opens an existing large object and returns an object-descriptor for use in
1257 subsequent lo_* calls. For the mode bits see lo_create. Returns undef upon
1258 failure. Note that 0 is a perfectly correct object descriptor!
1259
1260   $nbytes = $dbh->func($lobj_fd, $buf, $len, 'lo_write');
1261
1262 Writes $len bytes of $buf into the large object $lobj_fd. Returns the number
1263 of bytes written and undef upon failure.
1264
1265   $nbytes = $dbh->func($lobj_fd, $buf, $len, 'lo_read');
1266
1267 Reads $len bytes into $buf from large object $lobj_fd. Returns the number of
1268 bytes read and undef upon failure.
1269
1270   $loc = $dbh->func($lobj_fd, $offset, $whence, 'lo_lseek');
1271
1272 Change the current read or write location on the large object
1273 $obj_id. Currently $whence can only be 0 (L_SET). Returns the current location
1274 and undef upon failure.
1275
1276   $loc = $dbh->func($lobj_fd, 'lo_tell');
1277
1278 Returns the current read or write location on the large object $lobj_fd and
1279 undef upon failure.
1280
1281   $lobj_fd = $dbh->func($lobj_fd, 'lo_close');
1282
1283 Closes an existing large object. Returns true upon success and false upon
1284 failure.
1285
1286   $lobj_fd = $dbh->func($lobj_fd, 'lo_unlink');
1287
1288 Deletes an existing large object. Returns true upon success and false upon
1289 failure.
1290
1291   $lobjId = $dbh->func($filename, 'lo_import');
1292
1293 Imports a Unix file as large object and returns the object id of the new
1294 object or undef upon failure.
1295
1296   $ret = $dbh->func($lobjId, 'lo_export', 'filename');
1297
1298 Exports a large object into a Unix file. Returns false upon failure, true
1299 otherwise.
1300
1301   $ret = $dbh->func($line, 'putline');
1302
1303 Used together with the SQL-command 'COPY table FROM STDIN' to copy large
1304 amount of data into a table avoiding the overhead of using single
1305 insert commands. The application must explicitly send the two characters "\."
1306 to indicate to the backend that it has finished sending its data. See test.pl
1307 for an example on how to use this function.
1308
1309   $ret = $dbh->func($buffer, length, 'getline');
1310
1311 Used together with the SQL-command 'COPY table TO STDOUT' to dump a complete
1312 table. See test.pl for an example on how to use this function.
1313
1314   $ret = $dbh->func('pg_notifies');
1315
1316 Returns either undef or a reference to two-element array [ $table,
1317 $backend_pid ] of asynchronous notifications received.
1318
1319   $fd = $dbh->func('getfd');
1320
1321 Returns fd of the actual connection to server. Can be used with select() and
1322 func('pg_notifies').
1323
1324 =back
1325
1326 =head1 ATTRIBUTES COMMON TO ALL HANDLES
1327
1328 =over 4
1329
1330 =item B<Warn> (boolean, inherited)
1331
1332 Implemented by DBI, no driver-specific impact.
1333
1334 =item B<Active> (boolean, read-only)
1335
1336 Supported by the driver as proposed by DBI. A database handle is active while
1337 it is connected and statement handle is active until it is finished.
1338
1339 =item B<Kids> (integer, read-only)
1340
1341 Implemented by DBI, no driver-specific impact.
1342
1343 =item B<ActiveKids> (integer, read-only)
1344
1345 Implemented by DBI, no driver-specific impact.
1346
1347 =item B<CachedKids> (hash ref)
1348
1349 Implemented by DBI, no driver-specific impact.
1350
1351 =item B<CompatMode> (boolean, inherited)
1352
1353 Not used by this driver.
1354
1355 =item B<InactiveDestroy> (boolean)
1356
1357 Implemented by DBI, no driver-specific impact.
1358
1359 =item B<PrintError> (boolean, inherited)
1360
1361 Implemented by DBI, no driver-specific impact.
1362
1363 =item B<RaiseError> (boolean, inherited)
1364
1365 Implemented by DBI, no driver-specific impact.
1366
1367 =item B<HandleError> (boolean, inherited)
1368
1369 Implemented by DBI, no driver-specific impact.
1370
1371 =item B<ChopBlanks> (boolean, inherited)
1372
1373 Supported by the driver as proposed by DBI. This method is similar to the
1374 SQL-function RTRIM.
1375
1376 =item B<LongReadLen> (integer, inherited)
1377
1378 Implemented by DBI, not used by the driver.
1379
1380 =item B<LongTruncOk> (boolean, inherited)
1381
1382 Implemented by DBI, not used by the driver.
1383
1384 =item B<Taint> (boolean, inherited)
1385
1386 Implemented by DBI, no driver-specific impact.
1387
1388 =item B<private_*>
1389
1390 Implemented by DBI, no driver-specific impact.
1391
1392 =back
1393
1394 =head1 DBI DATABASE HANDLE OBJECTS
1395
1396 =head2 Database Handle Methods
1397
1398 =over 4
1399
1400 =item B<selectrow_array>
1401
1402   @row_ary = $dbh->selectrow_array($statement, \%attr, @bind_values);
1403
1404 Implemented by DBI, no driver-specific impact.
1405
1406 =item B<selectrow_arrayref>
1407
1408   $ary_ref = $dbh->selectrow_arrayref($statement, \%attr, @bind_values);
1409
1410 Implemented by DBI, no driver-specific impact.
1411
1412 =item B<selectrow_hashref>
1413
1414   $hash_ref = $dbh->selectrow_hashref($statement, \%attr, @bind_values);
1415
1416 Implemented by DBI, no driver-specific impact.
1417
1418 =item B<selectall_arrayref>
1419
1420   $ary_ref = $dbh->selectall_arrayref($statement, \%attr, @bind_values);
1421
1422 Implemented by DBI, no driver-specific impact.
1423
1424 =item B<selectall_hashref>
1425
1426   $hash_ref = $dbh->selectall_hashref($statement, $key_field);
1427
1428 Implemented by DBI, no driver-specific impact.
1429
1430 =item B<selectcol_arrayref>
1431
1432   $ary_ref = $dbh->selectcol_arrayref($statement, \%attr, @bind_values);
1433
1434 Implemented by DBI, no driver-specific impact.
1435
1436 =item B<prepare>
1437
1438   $sth = $dbh->prepare($statement, \%attr);
1439
1440 PostgreSQL does not have the concept of preparing a statement. Hence the
1441 prepare method just stores the statement after checking for place-holders. No
1442 information about the statement is available after preparing it.
1443
1444 =item B<prepare_cached>
1445
1446   $sth = $dbh->prepare_cached($statement, \%attr);
1447
1448 Implemented by DBI, no driver-specific impact. This method is not useful for
1449 this driver, because preparing a statement has no database interaction.
1450
1451 =item B<do>
1452
1453   $rv  = $dbh->do($statement, \%attr, @bind_values);
1454
1455 Implemented by DBI, no driver-specific impact. See the notes for the execute
1456 method elsewhere in this document.
1457
1458 =item B<commit>
1459
1460   $rc  = $dbh->commit;
1461
1462 Supported by the driver as proposed by DBI. See also the notes about
1463 B<Transactions> elsewhere in this document.
1464
1465 =item B<rollback>
1466
1467   $rc  = $dbh->rollback;
1468
1469 Supported by the driver as proposed by DBI. See also the notes about
1470 B<Transactions> elsewhere in this document.
1471
1472 =item B<disconnect>
1473
1474   $rc  = $dbh->disconnect;
1475
1476 Supported by the driver as proposed by DBI.
1477
1478 =item B<ping>
1479
1480   $rc = $dbh->ping;
1481
1482 This driver supports the ping-method, which can be used to check the validity
1483 of a database-handle. The ping method issues an empty query and checks the
1484 result status.
1485
1486 =item B<table_info>
1487
1488   $sth = $dbh->table_info;
1489
1490 Supported by the driver as proposed by DBI. This method returns all tables and
1491 views which are owned by the current user. It does not select any indexes and
1492 sequences. Also System tables are not selected. As TABLE_QUALIFIER the reltype
1493 attribute is returned and the REMARKS are undefined.
1494
1495 =item B<foreign_key_info>
1496
1497   $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table,
1498                                  $fk_catalog, $fk_schema, $fk_table );
1499
1500 Supported by the driver as proposed by DBI. Unimplemented for Postgres
1501 servers before 7.3 (returns undef).  Currently only returns information
1502 about first column of any multiple-column keys.
1503
1504 =item B<tables>
1505
1506   @names = $dbh->tables;
1507
1508 Supported by the driver as proposed by DBI. This method returns all tables and
1509 views which are owned by the current user. It does not select any indexes and
1510 sequences, or system tables.
1511
1512 =item B<type_info_all>
1513
1514   $type_info_all = $dbh->type_info_all;
1515
1516 Supported by the driver as proposed by DBI. Only for SQL data-types and for
1517 frequently used data-types information is provided. The mapping between the
1518 PostgreSQL typename and the SQL92 data-type (if possible) has been done
1519 according to the following table:
1520
1521         +---------------+------------------------------------+
1522         | typname       | SQL92                              |
1523         |---------------+------------------------------------|
1524         | bool          | BOOL                               |
1525         | text          | /                                  |
1526         | bpchar        | CHAR(n)                            |
1527         | varchar       | VARCHAR(n)                         |
1528         | int2          | SMALLINT                           |
1529         | int4          | INT                                |
1530         | int8          | /                                  |
1531         | money         | /                                  |
1532         | float4        | FLOAT(p)   p<7=float4, p<16=float8 |
1533         | float8        | REAL                               |
1534         | abstime       | /                                  |
1535         | reltime       | /                                  |
1536         | tinterval     | /                                  |
1537         | date          | /                                  |
1538         | time          | /                                  |
1539         | datetime      | /                                  |
1540         | timespan      | TINTERVAL                          |
1541         | timestamp     | TIMESTAMP                          |
1542         +---------------+------------------------------------+
1543
1544 For further details concerning the PostgreSQL specific data-types please read
1545 the L<pgbuiltin>.
1546
1547 =item B<type_info>
1548
1549   @type_info = $dbh->type_info($data_type);
1550
1551 Implemented by DBI, no driver-specific impact.
1552
1553 =item B<quote>
1554
1555   $sql = $dbh->quote($value, $data_type);
1556
1557 This module implements its own quote method. In addition to the DBI method it
1558 also doubles the backslash, because PostgreSQL treats a backslash as an escape
1559 character.
1560
1561 B<NOTE:> The undocumented (and invalid) support for the C<SQL_BINARY> data
1562 type is officially deprecated. Use C<PG_BYTEA> with C<bind_param()> instead:
1563
1564   $rv = $sth->bind_param($param_num, $bind_value,
1565                          { pg_type => DBD::Pg::PG_BYTEA });
1566
1567 =back
1568
1569 =head2 Database Handle Attributes
1570
1571 =over 4
1572
1573 =item B<AutoCommit>  (boolean)
1574
1575 Supported by the driver as proposed by DBI. According to the classification of
1576 DBI, PostgreSQL is a database, in which a transaction must be explicitly
1577 started. Without starting a transaction, every change to the database becomes
1578 immediately permanent. The default of AutoCommit is on, which corresponds to
1579 the default behavior of PostgreSQL. When setting AutoCommit to off, a
1580 transaction will be started and every commit or rollback will automatically
1581 start a new transaction. For details see the notes about B<Transactions>
1582 elsewhere in this document.
1583
1584 =item B<Driver>  (handle)
1585
1586 Implemented by DBI, no driver-specific impact.
1587
1588 =item B<Name>  (string, read-only)
1589
1590 The default method of DBI is overridden by a driver specific method, which
1591 returns only the database name. Anything else from the connection string is
1592 stripped off. Note, that here the method is read-only in contrast to the DBI
1593 specs.
1594
1595 =item B<RowCacheSize>  (integer)
1596
1597 Implemented by DBI, not used by the driver.
1598
1599 =item B<pg_auto_escape> (boolean)
1600
1601 PostgreSQL specific attribute. If true, then quotes and backslashes in all
1602 parameters will be escaped in the following way:
1603
1604   escape quote with a quote (SQL)
1605   escape backslash with a backslash
1606
1607 The default is on. Note, that PostgreSQL also accepts quotes, which are
1608 escaped by a backslash. Any other ASCII character can be used directly in a
1609 string constant.
1610
1611 =item B<pg_enable_utf8> (boolean)
1612
1613 PostgreSQL specific attribute.  If true, then the utf8 flag will be
1614 turned for returned character data (if the data is valid utf8).  For
1615 details about the utf8 flag, see L<Encode>.  This is only relevant under
1616 perl 5.8 and higher.
1617
1618 B<NB>: This attribute is experimental and may be subject to change.
1619
1620 =item B<pg_INV_READ> (integer, read-only)
1621
1622 Constant to be used for the mode in lo_creat and lo_open.
1623
1624 =item B<pg_INV_WRITE> (integer, read-only)
1625
1626 Constant to be used for the mode in lo_creat and lo_open.
1627
1628 =back
1629
1630 =head1 DBI STATEMENT HANDLE OBJECTS
1631
1632 =head2 Statement Handle Methods
1633
1634 =over 4
1635
1636 =item B<bind_param>
1637
1638   $rv = $sth->bind_param($param_num, $bind_value, \%attr);
1639
1640 Supported by the driver as proposed by DBI.
1641
1642 B<NOTE:> The undocumented (and invalid) support for the C<SQL_BINARY>
1643 SQL type is officially deprecated. Use C<PG_BYTEA> instead:
1644
1645   $rv = $sth->bind_param($param_num, $bind_value,
1646                          { pg_type => DBD::Pg::PG_BYTEA });
1647
1648 =item B<bind_param_inout>
1649
1650 Not supported by this driver.
1651
1652 =item B<execute>
1653
1654   $rv = $sth->execute(@bind_values);
1655
1656 Supported by the driver as proposed by DBI. In addition to 'UPDATE', 'DELETE',
1657 'INSERT' statements, for which it returns always the number of affected rows,
1658 the execute method can also be used for 'SELECT ... INTO table' statements.
1659
1660 =item B<fetchrow_arrayref>
1661
1662   $ary_ref = $sth->fetchrow_arrayref;
1663
1664 Supported by the driver as proposed by DBI.
1665
1666 =item B<fetchrow_array>
1667
1668   @ary = $sth->fetchrow_array;
1669
1670 Supported by the driver as proposed by DBI.
1671
1672 =item B<fetchrow_hashref>
1673
1674   $hash_ref = $sth->fetchrow_hashref;
1675
1676 Supported by the driver as proposed by DBI.
1677
1678 =item B<fetchall_arrayref>
1679
1680   $tbl_ary_ref = $sth->fetchall_arrayref;
1681
1682 Implemented by DBI, no driver-specific impact.
1683
1684 =item B<finish>
1685
1686   $rc = $sth->finish;
1687
1688 Supported by the driver as proposed by DBI.
1689
1690 =item B<rows>
1691
1692   $rv = $sth->rows;
1693
1694 Supported by the driver as proposed by DBI. In contrast to many other drivers
1695 the number of rows is available immediately after executing the statement.
1696
1697 =item B<bind_col>
1698
1699   $rc = $sth->bind_col($column_number, \$var_to_bind, \%attr);
1700
1701 Supported by the driver as proposed by DBI.
1702
1703 =item B<bind_columns>
1704
1705   $rc = $sth->bind_columns(\%attr, @list_of_refs_to_vars_to_bind);
1706
1707 Supported by the driver as proposed by DBI.
1708
1709 =item B<dump_results>
1710
1711   $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);
1712
1713 Implemented by DBI, no driver-specific impact.
1714
1715 =item B<blob_read>
1716
1717   $blob = $sth->blob_read($id, $offset, $len);
1718
1719 Supported by this driver as proposed by DBI. Implemented by DBI but not
1720 documented, so this method might change.
1721
1722 This method seems to be heavily influenced by the current implementation of
1723 blobs in Oracle. Nevertheless we try to be as compatible as possible. Whereas
1724 Oracle suffers from the limitation that blobs are related to tables and every
1725 table can have only one blob (data-type LONG), PostgreSQL handles its blobs
1726 independent of any table by using so called object identifiers. This explains
1727 why the blob_read method is blessed into the STATEMENT package and not part of
1728 the DATABASE package. Here the field parameter has been used to handle this
1729 object identifier. The offset and len parameter may be set to zero, in which
1730 case the driver fetches the whole blob at once.
1731
1732 Starting with PostgreSQL-6.5 every access to a blob has to be put into a
1733 transaction. This holds even for a read-only access.
1734
1735 See also the PostgreSQL-specific functions concerning blobs which are
1736 available via the func-interface.
1737
1738 For further information and examples about blobs, please read the chapter
1739 about Large Objects in the PostgreSQL Programmer's Guide.
1740
1741 =back
1742
1743 =head2 Statement Handle Attributes
1744
1745 =over 4
1746
1747 =item B<NUM_OF_FIELDS>  (integer, read-only)
1748
1749 Implemented by DBI, no driver-specific impact.
1750
1751 =item B<NUM_OF_PARAMS>  (integer, read-only)
1752
1753 Implemented by DBI, no driver-specific impact.
1754
1755 =item B<NAME>  (array-ref, read-only)
1756
1757 Supported by the driver as proposed by DBI.
1758
1759 =item B<NAME_lc>  (array-ref, read-only)
1760
1761 Implemented by DBI, no driver-specific impact.
1762
1763 =item B<NAME_uc>  (array-ref, read-only)
1764
1765 Implemented by DBI, no driver-specific impact.
1766
1767 =item B<TYPE>  (array-ref, read-only)
1768
1769 Supported by the driver as proposed by DBI, with the restriction, that the
1770 types are PostgreSQL specific data-types which do not correspond to
1771 international standards.
1772
1773 =item B<PRECISION>  (array-ref, read-only)
1774
1775 Not supported by the driver.
1776
1777 =item B<SCALE>  (array-ref, read-only)
1778
1779 Not supported by the driver.
1780
1781 =item B<NULLABLE>  (array-ref, read-only)
1782
1783 Not supported by the driver.
1784
1785 =item B<CursorName>  (string, read-only)
1786
1787 Not supported by the driver. See the note about B<Cursors> elsewhere in this
1788 document.
1789
1790 =item B<Statement>  (string, read-only)
1791
1792 Supported by the driver as proposed by DBI.
1793
1794 =item B<RowCache>  (integer, read-only)
1795
1796 Not supported by the driver.
1797
1798 =item B<pg_size>  (array-ref, read-only)
1799
1800 PostgreSQL specific attribute. It returns a reference to an array of integer
1801 values for each column. The integer shows the size of the column in
1802 bytes. Variable length columns are indicated by -1.
1803
1804 =item B<pg_type>  (hash-ref, read-only)
1805
1806 PostgreSQL specific attribute. It returns a reference to an array of strings
1807 for each column. The string shows the name of the data_type.
1808
1809 =item B<pg_oid_status> (integer, read-only)
1810
1811 PostgreSQL specific attribute. It returns the OID of the last INSERT command.
1812
1813 =item B<pg_cmd_status> (integer, read-only)
1814
1815 PostgreSQL specific attribute. It returns the type of the last
1816 command. Possible types are: INSERT, DELETE, UPDATE, SELECT.
1817
1818 =back
1819
1820 =head1 FURTHER INFORMATION
1821
1822 =head2 Transactions
1823
1824 The transaction behavior is now controlled with the attribute AutoCommit. For
1825 a complete definition of AutoCommit please refer to the DBI documentation.
1826
1827 According to the DBI specification the default for AutoCommit is TRUE. In this
1828 mode, any change to the database becomes valid immediately. Any 'begin',
1829 'commit' or 'rollback' statement will be rejected.
1830
1831 If AutoCommit is switched-off, immediately a transaction will be started by
1832 issuing a 'begin' statement. Any 'commit' or 'rollback' will start a new
1833 transaction. A disconnect will issue a 'rollback' statement.
1834
1835 =head2 Large Objects
1836
1837 The driver supports all large-objects related functions provided by libpq via
1838 the func-interface. Please note, that starting with PostgreSQL 6.5 any access
1839 to a large object - even read-only - has to be put into a transaction!
1840
1841 =head2 Cursors
1842
1843 Although PostgreSQL has a cursor concept, it has not been used in the current
1844 implementation. Cursors in PostgreSQL can only be used inside a transaction
1845 block. Because only one transaction block at a time is allowed, this would
1846 have implied the restriction, not to use any nested SELECT statements. Hence
1847 the execute method fetches all data at once into data structures located in
1848 the frontend application. This has to be considered when selecting large
1849 amounts of data!
1850
1851 =head2 Data-Type bool
1852
1853 The current implementation of PostgreSQL returns 't' for true and 'f' for
1854 false. From the Perl point of view a rather unfortunate choice. The DBD::Pg
1855 module translates the result for the data-type bool in a perl-ish like manner:
1856 'f' -> '0' and 't' -> '1'. This way the application does not have to check the
1857 database-specific returned values for the data-type bool, because Perl treats
1858 '0' as false and '1' as true.
1859
1860 Boolean values can be passed to PostgreSQL as TRUE, 't', 'true', 'y', 'yes' or
1861 '1' for true and FALSE, 'f', 'false', 'n', 'no' or '0' for false.
1862
1863 =head2 Schema support
1864
1865 PostgreSQL version 7.3 introduced schema support. Note that the PostgreSQL
1866 schema concept may differ to that of other databases. Please refer to the
1867 PostgreSQL documentation for more details.
1868
1869 Currently DBD::Pg does not provide explicit support for PostgreSQL schemas.
1870 However, schema functionality may be used without any restrictions by
1871 explicitly addressing schema objects, e.g.
1872
1873   my $res = $dbh->selectall_arrayref("SELECT * FROM my_schema.my_table");
1874
1875 or by manipulating the schema search path with SET search_path, e.g.
1876
1877   $dbh->do("SET search_path TO my_schema, public");
1878
1879 B<NOTE:> If you create an object with the same name as a PostgreSQL system
1880 object (as contained in the pg_catalog schema) and explicitly set the search
1881 path so that pg_catalog comes after the new object's schema, some DBD::Pg
1882 methods (particularly those querying PostgreSQL system objects) may fail.
1883 This problem should be fixed in a future release of DBD::Pg. Creating objects
1884 with the same name as system objects (or beginning with 'pg_') is not
1885 recommended practice and should be avoided in any case.
1886
1887 =head1 SEE ALSO
1888
1889 L<DBI>
1890
1891 =head1 AUTHORS
1892
1893 DBI and DBD-Oracle by Tim Bunce (Tim.Bunce@ig.co.uk)
1894
1895 DBD-Pg by Edmund Mergl (E.Mergl@bawue.de) and Jeffrey W. Baker
1896 (jwbaker@acm.org). By David Wheeler <david@wheeler.net>, Jason
1897 Stewart <jason@openinformatics.com> and Bruce Momjian
1898 <pgman@candle.pha.pa.us> after v1.13.
1899
1900 Major parts of this package have been copied from DBI and DBD-Oracle.
1901
1902 =head1 COPYRIGHT
1903
1904 The DBD::Pg module is free software. You may distribute under the terms of
1905 either the GNU General Public License or the Artistic License, as specified in
1906 the Perl README file.
1907
1908 =head1 ACKNOWLEDGMENTS
1909
1910 See also B<DBI/ACKNOWLEDGMENTS>.
1911
1912 =cut
1913