Rework tutorial

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

=head1 NAME

DBIx::Class::DeploymentHandler::Intro - Introduction to DBIx::Class::DeploymentHandler

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


=head1 Our 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

=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 },
      schema_version      => 1,
 });

 $dh->prepare_install;
 $dh->install({ version => 1 });

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

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