lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod

   1 =head1 NAME
   2
   3 DBIx::Class::DeploymentHandler::Intro - Introduction to DBIx::Class::DeploymentHandler
   4
   5 =head1 Why DBIx::Class::DeploymentHandler is worth using
   6
   7
   8 =head1 Our Sample database
   9
  10 Follow L<DBIx::Class::Manual::Intro> except for the parts setting up the database.
  11 After you are done, You should have the following files.
  12
  13  MyDatabase/
  14  |-- Main
  15  |   |-- Result
  16  |   |   |-- Artist.pm
  17  |   |   |-- Cd.pm
  18  |   |   `-- Track.pm
  19  |   `-- ResultSet
  20  `-- Main.pm
  21
  22 =head1 install.pl
  23
  24 Our first script, C<install.pl> reads our schema file and creates the tables
  25 in the database.
  26
  27  #!perl
  28  use strict;
  29  use warnings;
  30  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  31  use FindBin;
  32  use lib "$FindBin::Bin/../lib";
  33  use MyDatabase::Main;
  34  my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
  35
  36  my $dh = DH->new({
  37       schema              => $schema,
  38       script_directory    => "$FindBin::Bin/dbicdh",
  39       databases           => 'SQLite',
  40       sql_translator_args => { add_drop_table => 0 },
  41       schema_version      => 1,
  42  });
  43
  44  $dh->prepare_install;
  45  $dh->install({ version => 1 });
  46
  47 =head2 dbicdh - Our migration scripts
  48
  49 Running C<install.pl> should create the following:
  50
  51  dbicdh/
  52  |-- SQLite
  53  |   `-- deploy
  54  |       `-- 1
  55  |           `-- 001-auto.sql
  56  `-- _source
  57      `-- deploy
  58          `-- 1
  59              `-- 001-auto.yml
  60
  61 =head3 001-auto.sql
  62
  63 DBIx::Class::DeploymentHandler automatically generates SQL from our schema
  64 that is suitable for SQLite
  65
  66 =head3 001-auto.yml
  67
  68 This contains all of the raw information about our schema that is then
  69 translated into the sql.
  70
  71 =head1 Upgrading
  72
  73 Add a line to MyDatabase/Main/Result/Cd.pm below
  74
  75  __PACKAGE__->add_columns(qw/ cdid artist title /);
  76
  77 with
  78
  79  __PACKAGE__->add_column(isbn => { is_nullable => 1 });
  80
  81 Aside: It must be nullable or have a default - otherwise the upgrade will
  82 fail for logical reasons.  To be clear, if you add a column to a database and
  83 it is not nullable and has no default, what will the existing rows contain
  84 for that column?
  85
  86 So here is our next script, C<upgrade.pl>:
  87
  88  #!perl
  89  use strict;
  90  use warnings;
  91  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  92  use FindBin;
  93  use lib "$FindBin::Bin/../lib";
  94  use MyDatabase::Main;
  95  my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
  96
  97  my $dh = DH->new({
  98     schema              => $schema,
  99     script_directory    => "$FindBin::Bin/dbicdh",
 100     databases           => 'SQLite',
 101     sql_translator_args => { add_drop_table => 0 },
 102  });
 103
 104  $dh->prepare_deploy;
 105  $dh->prepare_upgrade({ from_version => 1, to_version => 2});
 106  $dh->upgrade;
 107
 108 Our script directory now looks like:
 109
 110   dbicdh/
 111   |-- SQLite
 112   |   |-- deploy
 113   |   |   |-- 1
 114   |   |   |   `-- 001-auto.sql
 115   |   |   `-- 2
 116   |   |       `-- 001-auto.sql
 117   |   `-- upgrade
 118   |       `-- 1-2
 119   |           `-- 001-auto.sql
 120   `-- _source
 121       `-- deploy
 122           |-- 1
 123           |   `-- 001-auto.yml
 124           `-- 2
 125               `-- 001-auto.yml
 126
 127 The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
 128 state of the db as at that version.  The C<upgrade/1-2/001-auto.sql> file
 129 is the most interesting one; it is what gets your database from version 1 to 2.
 130