The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

SVW / DBIx-Migration-0.23 / lib / DBIx / Migration / Pg.pod 

            

              
—
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

              
=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.
=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