.\" Automatically generated by Pod::Man 4.11 (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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBIx::Class::DeploymentHandler::Manual::Intro 3pm"
.TH DBIx::Class::DeploymentHandler::Manual::Intro 3pm "2019-11-03" "perl v5.30.0" "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::DeploymentHandler::Manual::Intro \- Introduction to DBIx::Class::DeploymentHandler
.SH "Why is DBIx::Class::DeploymentHandler worth using?"
.IX Header "Why is DBIx::Class::DeploymentHandler worth using?"
The most obvious reasons for using DBIx::Class::DeploymentHandler are
that it can run multiple \s-1SQL\s0 scripts as well as Perl scripts, unlike
DBIx::Class::Schema::Versioned, which only allows for a single \s-1SQL\s0 script.
It is also extremely extensible, and is an opportunity for a break from
backwards compatibility, so some regrettable decisions are avoided.
.SH "Sample database"
.IX Header "Sample database"
Follow DBIx::Class::Manual::Intro except for the parts setting up the
database.  After you are done, You should have the following files.
.PP
.Vb 8
\& MyDatabase/
\& |\-\- Main
\& |   |\-\- Result
\& |   |   |\-\- Artist.pm
\& |   |   |\-\- Cd.pm
\& |   |   \`\-\- Track.pm
\& |   \`\-\- ResultSet
\& \`\-\- Main.pm
.Ve
.PP
Add a line like the following in your MyDatabase::Main file:
.PP
.Vb 1
\& our $VERSION = 1;
.Ve
.PP
or if you are using a newer Perl you can use the prettier syntax:
.PP
.Vb 1
\& package MyDatabase::Main 1;
.Ve
.PP
By default DBIx::Class::DeploymentHandler only uses integers for versions,
this makes versioning much simpler for figuring out what version is next
(or previous.) However, if you are using decimal numbers for versioning,
you will need to create a separate DeploymentHandler class, as per
DBIx::Class::DeploymentHandler::Cookbook::CustomResultSource, and
set the VersionHandler class_name from Monotonic to ExplicitVersions or
DatabaseToSchemaVersions, as these handle version numbers as strings instead
of integers.
.SH "install.pl"
.IX Header "install.pl"
Our first script, \f(CW\*(C`install.pl\*(C'\fR reads our schema file and creates the tables
in the database.
.PP
.Vb 1
\& #!/usr/bin/env perl
\&
\& use strict;
\& use warnings;
\& use aliased \*(AqDBIx::Class::DeploymentHandler\*(Aq => \*(AqDH\*(Aq;
\& use Getopt::Long;
\& use FindBin;
\& use lib "$FindBin::Bin/../lib";
\& use MyDatabase::Main;
\&
\& my $force_overwrite = 0;
\&
\& unless ( GetOptions( \*(Aqforce_overwrite!\*(Aq => \e$force_overwrite ) ) {
\&     die "Invalid options";
\& }
\&
\& my $schema = MyDatabase::Main\->connect(\*(Aqdbi:SQLite:mydb.db\*(Aq);
\&
\& my $dh = DH\->new(
\&     {
\&         schema              => $schema,
\&         script_directory    => "$FindBin::Bin/../dbicdh",
\&         databases           => \*(AqSQLite\*(Aq,
\&         sql_translator_args => { add_drop_table => 0 },
\&         force_overwrite     => $force_overwrite,
\&     }
\& );
\&
\& $dh\->prepare_install;
\& $dh\->install;
.Ve
.SS "dbicdh \- Our migration scripts"
.IX Subsection "dbicdh - Our migration scripts"
Running \f(CW\*(C`install.pl\*(C'\fR should create the following:
.PP
.Vb 9
\& dbicdh/
\& |\-\- SQLite
\& |   \`\-\- deploy
\& |       \`\-\- 1
\& |           \`\-\- 001\-auto.sql
\& \`\-\- _source
\&     \`\-\- deploy
\&         \`\-\- 1
\&             \`\-\- 001\-auto.yml
.Ve
.PP
You may wish to turn on debug logging 
before running this script by setting the environment variable \f(CW\*(C`DBICDH_TRACE\*(C'\fR to
\&\f(CW1\fR.
.PP
\fI001\-auto.sql\fR
.IX Subsection "001-auto.sql"
.PP
DBIx::Class::DeploymentHandler automatically generates \s-1SQL\s0 from our schema
that is suitable for SQLite
.PP
\fI001\-auto.yml\fR
.IX Subsection "001-auto.yml"
.PP
This contains all of the raw information about our schema that is then
translated into the sql.
.PP
\fIPopulation\fR
.IX Subsection "Population"
.PP
To truly take advantage of all DBIx::Class::DeploymentHandler offers, you
should probably be using it for population.  To do that all you need to do
is create a file called \f(CW\*(C`dbicdh/_common/deploy/1/create_artists.pl\*(C'\fR:
.PP
.Vb 9
\&  sub {
\&     my $schema = shift;
\&     $schema\->resultset(\*(AqArtist\*(Aq)\->populate([
\&        [\*(Aqartistid\*(Aq, \*(Aqname\*(Aq],
\&        [1,          \*(AqMarillion\*(Aq],
\&        [2,          \*(AqThe Moutain Goats\*(Aq],
\&        [3,          \*(AqLadyhawke\*(Aq],
\&     ]);
\&  };
.Ve
.SH "Upgrading"
.IX Header "Upgrading"
Add a line to MyDatabase/Main/Result/Cd.pm below
.PP
.Vb 1
\& _\|_PACKAGE_\|_\->add_columns(qw/ cdid artist title /);
.Ve
.PP
with
.PP
.Vb 1
\& _\|_PACKAGE_\|_\->add_column(isbn => { is_nullable => 1 });
.Ve
.PP
Aside: It must be nullable or have a default \- otherwise the upgrade will
fail for logical reasons.  To be clear, if you add a column to a database and
it is not nullable and has no default, what will the existing rows contain
for that column?
.PP
Now you need to modify the schema version in your MyDatabase::Main file to
tell DBIx::Class::DeploymentHandler the new schema version number. You will
want to remember the earlier advice about integer version numbers.
.PP
.Vb 1
\& our $VERSION = 2;
.Ve
.PP
So here is our next script, \f(CW\*(C`upgrade.pl\*(C'\fR:
.PP
.Vb 8
\& #!/usr/bin/env perl
\& use strict;
\& use warnings;
\& use aliased \*(AqDBIx::Class::DeploymentHandler\*(Aq => \*(AqDH\*(Aq;
\& use FindBin;
\& use lib "$FindBin::Bin/../lib";
\& use MyDatabase::Main;
\& my $schema = MyDatabase::Main\->connect(\*(Aqdbi:SQLite:mydb\*(Aq);
\&
\& my $dh = DH\->new({
\&    schema              => $schema,
\&    script_directory    => "$FindBin::Bin/../dbicdh",
\&    databases           => \*(AqSQLite\*(Aq,
\&    sql_translator_args => { add_drop_table => 0 },
\& });
\&
\& $dh\->prepare_deploy;
\& $dh\->prepare_upgrade({ from_version => 1, to_version => 2});
\& $dh\->upgrade;
.Ve
.PP
Our script directory now looks like:
.PP
.Vb 10
\&  dbicdh/
\&  |\-\- SQLite
\&  |   |\-\- deploy
\&  |   |   |\-\- 1
\&  |   |   |   \`\-\- 001\-auto.sql
\&  |   |   \`\-\- 2
\&  |   |       \`\-\- 001\-auto.sql
\&  |   \`\-\- upgrade
\&  |       \`\-\- 1\-2
\&  |           \`\-\- 001\-auto.sql
\&  \`\-\- _source
\&      \`\-\- deploy
\&          |\-\- 1
\&          |   \`\-\- 001\-auto.yml
\&          \`\-\- 2
\&              \`\-\- 001\-auto.yml
.Ve
.PP
The new \f(CW\*(C`deploy/001\-auto.sql\*(C'\fR and \f(CW\*(C`deploy/001\-auto.yml\*(C'\fR files are the
state of the db as at that version.  The \f(CW\*(C`upgrade/1\-2/001\-auto.sql\*(C'\fR file
is the most interesting one; it is what gets your database from version 1 to 2.
.PP
And again, you can create a Perl file like we did previously with the
deploy stage.
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Axel \*(L"fREW\*(R" Schmidt <frioux+cpan@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2019 by Arthur Axel \*(L"fREW\*(R" Schmidt.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.