NAME

Module::Build::Database::PostgreSQL - PostgreSQL implementation for MBD

SYNOPSIS

In Build.PL :

 my $builder = Module::Build::Database->new(
     database_type => "PostgreSQL",
     database_options => {
         name   => "my_database_name",
         schema => "my_schema_name",
         # Extra items for scratch databases :
         append_to_conf => "text to add to postgresql.conf",
         after_create => q[create schema audit;],
     },
     database_extensions => {
         postgis     => { schema => "public", },
         # directory with postgis.sql and spatial_ref_sys.sql
         postgis_base => '/usr/local/share/postgresql/contrib'
     },
 );

DESCRIPTION

Postgres driver for Module::Build::Database.

OPTIONS

All of the options above may be changed via the Module::Build option handling, e.g.

  perl Build.PL --database_options name=my_name
  perl Build.PL --postgis_base=/usr/local/share/postgresql/contrib

The options are as follows ;

database_options

name

the name of the database (i.e. 'create database $name')

schema

the name of the schema to be managed by MBD

append_to_conf

extra options to append to postgresql.conf before starting test instances of postgres

after_create

extra SQL to run after running a 'create database' statement. Note that this will be run in several different situations :

1. during a dbtest (creating a test db)

2. during a dbfakeinstall (also creating a test db)

3. during an initial dbinstall; when the target database does not yet exist.

An example of using the after_create statement would be to create a second schema which will not be managed by MBD, but on which the MBD-managed schema depends.

database_extension

To specify a server side procedural language you can use the database_extension -> languages option, like so:

 my $builder = Module::Build::Database->new(
   database_extension => {
     languages => [ 'plperl', 'pltcl' ],
   },
 );

Trying to create languages to a patch will not work because they not stored in the main schema and will not be included in base.sql when you run Build dbdist.

This is also similar to

 after_create => 'create extension ...',

except it is executed on every dbinstall meaning you can use this to add extensions to existing database deployments.

postgis_base

Specify the directory containing postgis.sql and spatial_ref_sys.sql. If specified these SQL files will be loaded so that you can use PostGIS in your database.

leave_running

If set to true, and if you are not using a persistent scratch database (see next option), then the scratch database will not be stopped and torn down after running Build dbtest or Build dbfakeinstall.

scratch_database

You can use this option to specify the connection settings for a persistent scratch or temporary database instance, used by the Build dbtest and Build dbfakeinstall to test schema. IMPORTANT: the Build dbtest and Build dbfakeinstall will drop and re-create databases on the scratch instance with the same name as the database on your production instance so it is very important that if you use a persistent scratch database that it be dedicated to that task.

 my $builder = Module::Build::Database->new(
   scratch_database => {
     PGHOST => 'databasehost',
     PGPORT => '5555',
     PGUSER => 'dbuser',
   },
 );

If you specify any one of these keys for this option (PGHOST, PGPORT, PGUSER) then MBD will use a persistent scratch database. Any missing values will use the default.

You can also specify these settings using environment variables:

 % export MBD_SCRATCH_PGHOST=databasehost
 % export MBD_SCRATCH_PGPORT=5555
 % export MBD_SCRATCH_PGUSER=dbuser

By default this module will create its own scratch PostgreSQL instance that uses unix domain sockets for communication each time it needs one when you use the Build dbtest or Build dbfakeinstall commands. Situations where you might need to use a persistent scratch database:

1. The server and server binaries are hosted on a system different to the one that you are doing development

2. You are using MBD on Windows where unix domain sockets are not available

NOTES

The environment variables understood by psql: PGUSER, PGHOST and PGPORT will be used when connecting to a live database (for dbinstall and fakeinstall). PGDATABASE will be ignored; the name of the database should be specified in Build.PL instead.