Correct path used for DH schema info storage

[dbsrgits/DBIx-Class-DeploymentHandler.git] / lib / DBIx / Class / DeploymentHandler / Manual / Intro.pod

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.

 #!/usr/bin/env perl

 use strict;
 use warnings;
 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
 use Getopt::Long;
 use FindBin;
 use lib "$FindBin::Bin/../lib";
 use MyDatabase::Main;

 my $force_overwrite = 0;

 unless ( GetOptions( 'force_overwrite!' => \$force_overwrite ) ) {
     die "Invalid options";
 }

 my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb.db');

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

 $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

You may wish to turn on L<debug logging|DBIx::Class::DeploymentHandler/"LOGGING"> 
before running this script by setting the environment variable C<DBICDH_TRACE> to
C<1>.

=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/deploy/1/create_artists.pl>:

  sub {
     my $schema = shift;
     $schema->resultset('Artist')->populate([
        ['artistid', 'name'],
        [1,          'Marillion'],
        [2,          'The Moutain Goats'],
        [3,          '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?

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.

 our $VERSION = 2;

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

 #!/usr/bin/env 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.