/ 
persist-0.3.1
/ Persist::Driver::DBI::PostgreSQL

NAME

Persist::Driver::DBI::PostgreSQL - Persist driver for DBD::Pg

SYNOPSIS

use Persist::Source;

$source = new Persist::Source('Persist::Driver::DBI::PostgreSQL',
                  'dbname=foo', 'foo', 'bar');

@conn = $source->new_source('newfoo', 'newbar');
$source->delete_source('newfoo');

# Use other Persist::Source methods ...

DESCRIPTION

This is a concrete driver for accessing a PostgreSQL database via DBI using the DBD::Pg driver. This class shouldn't be used directly, but only through a Persist::Source.

The rest of this POD document describes some of the capabilities and limitations of this driver.

$driver = new Persist::Driver::DBI::PostgreSQL($conn, $user, $pass)

Creates a new DBI connection using the given connection string $conn, username $user, and password $pass.

The connection is created with AutoCommit set, PrintError unset, and RaiseError set.

$driver->preprocess_filter($tables, $filter)

This method changes boolean values to literal strings 'true' and 'false' and also converts Persist style timestamps to PostgreSQL style dates.

$rows = $driver->insert($name, \%values)

This is a wrapper for the insert method of Persist::Driver::DBI which converts Persist style dates to PostgreSQL style and boolean values to literal strings 'true' and 'false'.

$rows = $driver->update($name, \%set [, $filter [, \@bindings ] ] )

This is a wrapper for the update method of Persist::Driver::DBI which converts Persist style dates to PostgreSQL style and boolean values to literal strings 'true' and 'false'.

$driver->first($handle)

This is a wrapper for the first method of Persist::Driver::DBI and converts PostgreSQL style dates to Persist style timestamps.

$driver->next($handle)

This is a wrapper for the first method of Persist::Driver::DBI and converts PostgreSQL style dates to Persist style timestamps.

$driver->is_dba

Determines if the current connection has DBA priveleges by checking the pg_catalog.pg_user table to see if the current user is able to both create databases (usecreatedb) and create users (usesuper). Such a user can be created in psql using the command:

CREATE USER username WITH PASSWORD 'password' CREATEDB CREATEUSER;

Or the following command-line can be used from the shell:

# createuser -a -d -P username

For such a user to be usable by this Persist driver should also have a database created by the same name.

@args = $driver->new_source($user, $pass)

Creates a new data source using the given username $user and password $pass and returns the connection string to connect to the new database. This will create a new PostgreSQL user with the given name and then a database of the same name. The user will not be permitted to create databases or users.

$success = $driver->delete_source($user)

Deletes the database and user associated with the username $user.

$success = $driver->create_table($name, $columns, $indexes)

Creates the table as described by the arguments. All PRIMARY, UNIQUE, and LINK keys will be added as constraints. See "INDEXES" for details on how these used. See "TYPES" for information on column types.

$success = $driver->delete_table($name)

Deletes the given table from the database.

%columns = $driver->columns($name)

Recreates the column definition used to create the table. This should work even if the Persist driver didn't create the table, as long as it understands all the types involved. This information is created by examining several pg_catalog tables.

See "TYPES" for details on what types are used.

@indexes = $driver->indexes($name)

Recreates the index definition used to create the table. This should work even if the Persist driver didn't create the table. This information is created by examining several pg_catalog tables.

See "INDEXES" for information on how indexes are mapped.

$value = $driver->sequence_value($table, $column)

Returns the last AUTONUMBER value used during an insert. An insert must have been performed since the database connection was created for this method to succeed.

@tables = $driver->tables

Uses the DBI tables method to fetch the tables in the current schema. This is a fix to Persist::Driver::DBI for PostgreSQL since some versions want to prefix all tables with ``public.'', which is unacceptable for the purposes of Persist.

TYPES

At this time, Persist types are mapped as this table indicates:

Persist Type                  PostgreSQL Type
VARCHAR                          varchar
INTEGER                          int4
AUTONUMBER                       serial
BOOLEAN                          bool
REAL                             float8
TIMESTAMP                        timestamptz

The opposite direction isn't quite as easy as serial is a pseudonym for int4 with an attached sequence. When mapping in the opposite direction, any int4 column is checked to see if it has an associated default value in a sequence. If so, then it is a AUTONUMBER. Otherwise, it is an INTEGER.

INDEXES

The index mapping is straightforward. Indexes are mapped as described in this table:

Persist Index                 PostgreSQL Type
PRIMARY                          PRIMARY KEY
UNIQUE                           UNIQUE
LINK                             FOREIGN KEY

The same mapping is applied in reverse.

SEE ALSO

Persist, Persist::Driver, Persist::Driver::DBI, Persist::Source, DBI, DBD::Pg

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@users.sourceforge.net>

COPYRIGHT AND LICENSE

Copyright (c) 2003, Andrew Sterling Hanenkamp
All rights reserved.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met:

  * Redistributions of source code must retain the above copyright 
    notice, this list of conditions and the following disclaimer.
  * Redistributions in binary form must reproduce the above copyright 
    notice, this list of conditions and the following disclaimer in 
    the documentation and/or other materials provided with the 
    distribution.
  * Neither the name of the Contentment nor the names of its 
    contributors may be used to endorse or promote products derived 
    from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.