Initial commit of intro

[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 preinstall.pl

Our first script, preinstall.pl reads our schema file and creates the tables in the database.

  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});

TODO TODO TODO TODO

Someone really ought to fix the bug causing dbicdh/SQLite/deploy/1/001-auto.sql to have the dbix_class_deploymenthandler_versions

Right now, you need to comment out the version table crap in the sql file , then run install, then uncomment it.

TODO TODO TODO TODO

=head2 dbicdh - Our migration scripts

Running preinstall.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 });

(We need it to either be nullable, or have a default - merely adding it to the add_columns line will not work)

Then run the following script:

  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 => 2,
     from_version => 1,
     to_version => 2,
      }
  );

  $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 deploy/001-auto.sql and deploy/001-auto.yml files are the state of the db as at that version.  The upgrade/1-2/001-auto.sql file is the most interesting one

  -- Convert schema '/home/jdobbie/Projects/intro/dbicdh/_source/deploy/1/001-auto.yml' to '/home/jdobbie/Projects/intro/dbicdh/_source/deploy/2/001-auto.yml':;

  ;
  BEGIN;

  ;
  ALTER TABLE cd ADD COLUMN isbn;

  ;

  COMMIT;