=pod

=head1 NAME

DBIx::Migration::Pg - Seamless PostgreSQL database schema up- and downgrades

=head1 SYNOPSIS

  use DBIx::Migration::Pg ();

  # Create Pg migration object
  my $m = DBIx::Migration::Pg->new(
    dsn            => 'dbi:Pg:dbname=myapp.db;host=localhost;port=5432;user=postgres',
    tracking_table => 'myapp_migration',
    managed_schema => 'myapp'
  );

=head1 DESCRIPTION

PostgreSQL databases support
L<schemas|https://www.postgresql.org/docs/current/ddl-schemas.html>. A schema
can contain different kind of named objects like for example tables, data
types, functions, and so on.

An application that wants to use a PostgreSQL database can reserve one or more
schemas for use. From the perspective of a migration framework these schemas
are called managed schemas. The C<DBIx::Migration::Pg> class can cope with
single managed schema applications.  The default managed schema is the
C<public> schema. This schema usually exists. Considering the use case that
more than one application uses the same PostgreSQL database, the default value
should be changed for each application. At creation time of a
C<DBIx::Migration::Pg> object you may use the C<managed_schema> attribute to
overwrite the default managed schema.

For a PostgreSQL database you may set a tracking schema (the schema of your
tracking table) too. By default the tracking schema is the C<public> schema.
If you neither change this default nor the default of the tracking table a
clash will occur if more than one application uses the same PostgreSQL
database. At creation time of a C<DBIx::Migration::Pg> object you should either
overwrite the C<tracking_table> attribute and/or the C<tracking_schema>
attribute.

=head1 ACCESSORS

=over

=item $self->do_before

Get PostgreSQL database specific default list of SQL statements that are
executed before the migration transaction begins.  The default list contains a
single statement that assigns the managed schema to the C<search_path> option.

=item $self->do_while

Get PostgreSQL database specific default list of SQL statements that are
executed immediately after the migration transaction was enabled.  The default
list contains a single statement that locks the tracking table.

=item $self->managed_schema

Get schema that your application refers to.

=item $self->tracking_schema

Get schema that the tracking table belongs to.

=item $self->placeholders

Get map of placeholders. The map contains a single key value pair. The
C<dbix_migration_managed_schema> key refers to the C<managed_schema> value.

=back

=head1 METHODS

=over 

=item $self->create_tracking_table

Create the tracking table if it does not exist yet. Beforehand create the
tracking schema if it does not exist yet.

=item $self->quoted_tracking_table

Quote tracking table taking the tracking schema into consideration.

=back

=head1 COMPARISONS

There are more PostgreSQL database migration libraries on the CPAN. This
chapter tries to compare some of them. The content is work in progress.

  |                         | DBIx::Migration                 | App::Sqitch            |
  +-------------------------+---------------------------------+------------------------+
  | change                  | migration                       | change                 |
  | SQL script types        | up, down                        | deploy, revert, verify |
  | tracking                | tracking table                  | registry tables        |
  | dependency relationship | linear (numbered consecutively) | tree like (requires)   |

=head1 SEE ALSO

=over

=item * L<Liquibase managed schema and tracking schema|https://docs.liquibase.com/parameters/liquibase-schema-name.html>

=item * L<Mojo::Pg::Migrations>

=back

=cut
