.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Schema::Versioned 3pm"
.TH DBIx::Class::Schema::Versioned 3pm "2018-04-19" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::Schema::Versioned \- DBIx::Class::Schema plugin for Schema upgrades
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  package MyApp::Schema;
\&  use base qw/DBIx::Class::Schema/;
\&
\&  our $VERSION = 0.001;
\&
\&  # load MyApp::Schema::CD, MyApp::Schema::Book, MyApp::Schema::DVD
\&  _\|_PACKAGE_\|_\->load_classes(qw/CD Book DVD/);
\&
\&  _\|_PACKAGE_\|_\->load_components(qw/Schema::Versioned/);
\&  _\|_PACKAGE_\|_\->upgrade_directory(\*(Aq/path/to/upgrades/\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides methods to apply \s-1DDL\s0 changes to your database using \s-1SQL\s0
diff files. Normally these diff files would be created using
\&\*(L"create_ddl_dir\*(R" in DBIx::Class::Schema.
.PP
A table called \fIdbix_class_schema_versions\fR is created and maintained by the
module. This is used to determine which version your database is currently at.
Similarly the \f(CW$VERSION\fR in your \s-1DBIC\s0 schema class is used to determine the
current \s-1DBIC\s0 schema version.
.PP
The upgrade is initiated manually by calling \f(CW\*(C`upgrade\*(C'\fR on your schema object,
this will attempt to upgrade the database from its current version to the current
schema version using a diff from your \fIupgrade_directory\fR. If a suitable diff is
not found then no upgrade is possible.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DBIx::Class::DeploymentHandler is a much more powerful alternative to this
module.  Examples of things it can do that this module cannot do include
.IP "\(bu" 4
Downgrades in addition to upgrades
.IP "\(bu" 4
Multiple sql files per upgrade/downgrade/install
.IP "\(bu" 4
Perl scripts allowed for upgrade/downgrade/install
.IP "\(bu" 4
Just one set of files needed for upgrade, unlike this module where one might
need to generate \f(CW\*(C`factorial(scalar @versions)\*(C'\fR
.SH "GETTING STARTED"
.IX Header "GETTING STARTED"
Firstly you need to setup your schema class as per the \*(L"\s-1SYNOPSIS\*(R"\s0, make sure
you have specified an upgrade_directory and an initial \f(CW$VERSION\fR.
.PP
Then you'll need two scripts, one to create \s-1DDL\s0 files and diffs and another to perform
upgrades. Your creation script might look like a bit like this:
.PP
.Vb 4
\&  use strict;
\&  use Pod::Usage;
\&  use Getopt::Long;
\&  use MyApp::Schema;
\&
\&  my ( $preversion, $help );
\&  GetOptions(
\&    \*(Aqp|preversion:s\*(Aq  => \e$preversion,
\&  ) or die pod2usage;
\&
\&  my $schema = MyApp::Schema\->connect(
\&    $dsn,
\&    $user,
\&    $password,
\&  );
\&  my $sql_dir = \*(Aq./sql\*(Aq;
\&  my $version = $schema\->schema_version();
\&  $schema\->create_ddl_dir( \*(AqMySQL\*(Aq, $version, $sql_dir, $preversion );
.Ve
.PP
Then your upgrade script might look like so:
.PP
.Vb 2
\&  use strict;
\&  use MyApp::Schema;
\&
\&  my $schema = MyApp::Schema\->connect(
\&    $dsn,
\&    $user,
\&    $password,
\&  );
\&
\&  if (!$schema\->get_db_version()) {
\&    # schema is unversioned
\&    $schema\->deploy();
\&  } else {
\&    $schema\->upgrade();
\&  }
.Ve
.PP
The script above assumes that if the database is unversioned then it is empty
and we can safely deploy the \s-1DDL\s0 to it. However things are not always so simple.
.PP
if you want to initialise a pre-existing database where the \s-1DDL\s0 is not the same
as the \s-1DDL\s0 for your current schema version then you will need a diff which
converts the database's \s-1DDL\s0 to the current \s-1DDL.\s0 The best way to do this is
to get a dump of the database schema (without data) and save that in your
\&\s-1SQL\s0 directory as version 0.000 (the filename must be as with
\&\*(L"ddl_filename\*(R" in DBIx::Class::Schema) then create a diff using your create \s-1DDL\s0
script given above from version 0.000 to the current version. Then hand check
and if necessary edit the resulting diff to ensure that it will apply. Once you have
done all that you can do this:
.PP
.Vb 4
\&  if (!$schema\->get_db_version()) {
\&    # schema is unversioned
\&    $schema\->install("0.000");
\&  }
\&
\&  # this will now apply the 0.000 to current version diff
\&  $schema\->upgrade();
.Ve
.PP
In the case of an unversioned database the above code will create the
dbix_class_schema_versions table and write version 0.000 to it, then
upgrade will then apply the diff we talked about creating in the previous paragraph
and then you're good to go.
.SH "METHODS"
.IX Header "METHODS"
.SS "upgrade_directory"
.IX Subsection "upgrade_directory"
Use this to set the directory your upgrade files are stored in.
.SS "backup_directory"
.IX Subsection "backup_directory"
Use this to set the directory you want your backups stored in (note that backups
are disabled by default).
.SS "install"
.IX Subsection "install"
.ie n .IP "Arguments: $db_version" 4
.el .IP "Arguments: \f(CW$db_version\fR" 4
.IX Item "Arguments: $db_version"
.PP
Call this to initialise a previously unversioned database. The table 'dbix_class_schema_versions' will be created which will be used to store the database version.
.PP
Takes one argument which should be the version that the database is currently at. Defaults to the return value of \*(L"schema_version\*(R".
.PP
See \*(L"\s-1GETTING STARTED\*(R"\s0 for more details.
.SS "deploy"
.IX Subsection "deploy"
Same as \*(L"deploy\*(R" in DBIx::Class::Schema but also calls \f(CW\*(C`install\*(C'\fR.
.SS "create_upgrade_path"
.IX Subsection "create_upgrade_path"
.ie n .IP "Arguments: { upgrade_file => $file }" 4
.el .IP "Arguments: { upgrade_file => \f(CW$file\fR }" 4
.IX Item "Arguments: { upgrade_file => $file }"
.PP
Virtual method that should be overridden to create an upgrade file.
This is useful in the case of upgrading across multiple versions
to concatenate several files to create one upgrade file.
.PP
You'll probably want the db_version retrieved via \f(CW$self\fR\->get_db_version
and the schema_version which is retrieved via \f(CW$self\fR\->schema_version
.SS "ordered_schema_versions"
.IX Subsection "ordered_schema_versions"
.IP "Return Value: a list of version numbers, ordered from lowest to highest" 4
.IX Item "Return Value: a list of version numbers, ordered from lowest to highest"
.PP
Virtual method that should be overridden to return an ordered list
of schema versions. This is then used to produce a set of steps to
upgrade through to achieve the required schema version.
.PP
You may want the db_version retrieved via \f(CW$self\fR\->get_db_version
and the schema_version which is retrieved via \f(CW$self\fR\->schema_version
.SS "upgrade"
.IX Subsection "upgrade"
Call this to attempt to upgrade your database from the version it
is at to the version this \s-1DBIC\s0 schema is at. If they are the same
it does nothing.
.PP
It will call \*(L"ordered_schema_versions\*(R" to retrieve an ordered
list of schema versions (if ordered_schema_versions returns nothing
then it is assumed you can do the upgrade as a single step). It
then iterates through the list of versions between the current db
version and the schema version applying one update at a time until
all relevant updates are applied.
.PP
The individual update steps are performed by using
\&\*(L"upgrade_single_step\*(R", which will apply the update and also
update the dbix_class_schema_versions table.
.SS "upgrade_single_step"
.IX Subsection "upgrade_single_step"
.IP "Arguments: db_version \- the version currently within the db" 4
.IX Item "Arguments: db_version - the version currently within the db"
.PD 0
.IP "Arguments: target_version \- the version to upgrade to" 4
.IX Item "Arguments: target_version - the version to upgrade to"
.PD
.PP
Call this to attempt to upgrade your database from the
\&\fIdb_version\fR to the \fItarget_version\fR. If they are the same it
does nothing.
.PP
It requires an \s-1SQL\s0 diff file to exist in your \fIupgrade_directory\fR,
normally you will have created this using \*(L"create_ddl_dir\*(R" in DBIx::Class::Schema.
.PP
If successful the dbix_class_schema_versions table is updated with
the \fItarget_version\fR.
.PP
This method may be called repeatedly by the upgrade method to
upgrade through a series of updates.
.SS "do_upgrade"
.IX Subsection "do_upgrade"
This is an overwritable method used to run your upgrade. The freeform method
allows you to run your upgrade any way you please, you can call \f(CW\*(C`run_upgrade\*(C'\fR
any number of times to run the actual \s-1SQL\s0 commands, and in between you can
sandwich your data upgrading. For example, first run all the \fB\s-1CREATE\s0\fR
commands, then migrate your data from old to new tables/formats, then
issue the \s-1DROP\s0 commands when you are finished. Will run the whole file as it is by default.
.SS "run_upgrade"
.IX Subsection "run_upgrade"
.Vb 1
\& $self\->run_upgrade(qr/create/i);
.Ve
.PP
Runs a set of \s-1SQL\s0 statements matching a passed in regular expression. The
idea is that this method can be called any number of times from your
\&\f(CW\*(C`do_upgrade\*(C'\fR method, running whichever commands you specify via the
regex in the parameter. Probably won't work unless called from the overridable
do_upgrade method.
.SS "apply_statement"
.IX Subsection "apply_statement"
Takes an \s-1SQL\s0 statement and runs it. Override this if you want to handle errors
differently.
.SS "get_db_version"
.IX Subsection "get_db_version"
Returns the version that your database is currently at. This is determined by the values in the
dbix_class_schema_versions table that \f(CW\*(C`upgrade\*(C'\fR and \f(CW\*(C`install\*(C'\fR write to.
.SS "schema_version"
.IX Subsection "schema_version"
Returns the current schema class' \f(CW$VERSION\fR
.SS "backup"
.IX Subsection "backup"
This is an overwritable method which is called just before the upgrade, to
allow you to make a backup of the database. Per default this method attempts
to call \f(CW\*(C`$self\->storage\->backup\*(C'\fR, to run the standard backup on each
database type.
.PP
This method should return the name of the backup file, if appropriate..
.PP
This method is disabled by default. Set \f(CW$schema\fR\->\fIdo_backup\fR\|(1) to enable it.
.SS "connection"
.IX Subsection "connection"
Overloaded method. This checks the \s-1DBIC\s0 schema version against the \s-1DB\s0 version and
warns if they are not the same or if the \s-1DB\s0 is unversioned. It also provides
compatibility between the old versions table (SchemaVersions) and the new one
(dbix_class_schema_versions).
.PP
To avoid the checks on connect, set the environment var \s-1DBIC_NO_VERSION_CHECK\s0 or alternatively you can set the ignore_version attr in the forth argument like so:
.PP
.Vb 6
\&  my $schema = MyApp::Schema\->connect(
\&    $dsn,
\&    $user,
\&    $password,
\&    { ignore_version => 1 },
\&  );
.Ve
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.