package DBIx::Class::DeploymentHandler::Manual::Intro

# ABSTRACT: Introduction to DBIx::Class::DeploymentHandler

=pod

=head1 Why is DBIx::Class::DeploymentHandler worth using?

The most obvious reasons for using DBIx::Class::DeploymentHandler are
that it can run multiple SQL scripts as well as Perl scripts, unlike
DBIx::Class::Schema::Versioned, which only allows for a single SQL script.
It is also extremely extensible, and is an opportunity for a break from
backwards compatibility, so some regrettable decisions are avoided.

=head1 Sample database

Follow L<DBIx::Class::Manual::Intro> except for the parts setting up the
database.  After you are done, You should have the following files.

 MyDatabase/
 |-- Main
 |   |-- Result
 |   |   |-- Artist.pm
 |   |   |-- Cd.pm
 |   |   `-- Track.pm
 |   `-- ResultSet
 `-- Main.pm

Add a line like the following in your MyDatabase::Main file:

 our $VERSION = 1;

or if you are using a newer Perl you can use the prettier syntax:

 package MyDatabase::Main 1;

By default DBIx::Class::DeploymentHandler only uses integers for versions,
this makes versioning much simpler for figuring out what version is next
(or previous.)

=head1 install.pl

Our first script, C<install.pl> reads our schema file and creates the tables
in the database.

 #!perl
 use strict;
 use warnings;
 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
 use FindBin;
 use lib "$FindBin::Bin/../lib";
 use MyDatabase::Main;
 my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');

 my $dh = DH->new({
      schema              => $schema,
      script_directory    => "$FindBin::Bin/dbicdh",
      databases           => 'SQLite',
      sql_translator_args => { add_drop_table => 0 },
 });

 $dh->prepare_install;
 $dh->install;

=head2 dbicdh - Our migration scripts

Running C<install.pl> should create the following:

 dbicdh/
 |-- SQLite
 |   `-- deploy
 |       `-- 1
 |           `-- 001-auto.sql
 `-- _source
     `-- deploy
         `-- 1
             `-- 001-auto.yml

=head3 001-auto.sql

DBIx::Class::DeploymentHandler automatically generates SQL from our schema
that is suitable for SQLite

=head3 001-auto.yml

This contains all of the raw information about our schema that is then
translated into the sql.

=head3 Population

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 C<dbicdh/_common/install/1/create_artists.pl>:

 sub {
    my $schema = shift;
    $schema->resultset('User')->populate([
       ['name'],
       ['Marillion'],
       ['The Moutain Goats'],
       ['Ladyhawke'],
    ]);
 };

=head1 Upgrading

Add a line to MyDatabase/Main/Result/Cd.pm below

 __PACKAGE__->add_columns(qw/ cdid artist title /);

with

 __PACKAGE__->add_column(isbn => { is_nullable => 1 });

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?

So here is our next script, C<upgrade.pl>:

 #!perl
 use strict;
 use warnings;
 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
 use FindBin;
 use lib "$FindBin::Bin/../lib";
 use MyDatabase::Main;
 my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');

 my $dh = DH->new({
    schema              => $schema,
    script_directory    => "$FindBin::Bin/dbicdh",
    databases           => 'SQLite',
    sql_translator_args => { add_drop_table => 0 },
 });

 $dh->prepare_deploy;
 $dh->prepare_upgrade({ from_version => 1, to_version => 2});
 $dh->upgrade;

Our script directory now looks like:

  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

The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
state of the db as at that version.  The C<upgrade/1-2/001-auto.sql> file
is the most interesting one; it is what gets your database from version 1 to 2.

And again, you can create a Perl file like we did previously with the
deploy stage.