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

   1 package DBIx::Class::DeploymentHandler::Manual::Intro
   2
   3 # ABSTRACT: Introduction to DBIx::Class::DeploymentHandler
   4
   5 =pod
   6
   7 =head1 Why is DBIx::Class::DeploymentHandler worth using?
   8
   9 The most obvious reasons for using DBIx::Class::DeploymentHandler are
  10 that it can run multiple SQL scripts as well as Perl scripts, unlike
  11 DBIx::Class::Schema::Versioned, which only allows for a single SQL script.
  12 It is also extremely extensible, and is an opportunity for a break from
  13 backwards compatibility, so some regrettable decisions are avoided.
  14
  15 =head1 Sample database
  16
  17 Follow L<DBIx::Class::Manual::Intro> except for the parts setting up the
  18 database.  After you are done, You should have the following files.
  19
  20  MyDatabase/
  21  |-- Main
  22  |   |-- Result
  23  |   |   |-- Artist.pm
  24  |   |   |-- Cd.pm
  25  |   |   `-- Track.pm
  26  |   `-- ResultSet
  27  `-- Main.pm
  28
  29 Add a line like the following in your MyDatabase::Main file:
  30
  31  our $VERSION = 1;
  32
  33 or if you are using a newer Perl you can use the prettier syntax:
  34
  35  package MyDatabase::Main 1;
  36
  37 By default DBIx::Class::DeploymentHandler only uses integers for versions,
  38 this makes versioning much simpler for figuring out what version is next
  39 (or previous.)
  40
  41 =head1 install.pl
  42
  43 Our first script, C<install.pl> reads our schema file and creates the tables
  44 in the database.
  45
  46  #!/usr/bin/env perl
  47
  48  use strict;
  49  use warnings;
  50  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  51  use Getopt::Long;
  52  use FindBin;
  53  use lib "$FindBin::Bin/../lib";
  54  use MyDatabase::Main;
  55
  56  my $force_overwrite = 0;
  57
  58  unless ( GetOptions( 'force_overwrite!' => \$force_overwrite ) ) {
  59      die "Invalid options";
  60  }
  61
  62  my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb.db');
  63
  64  my $dh = DH->new(
  65      {
  66          schema              => $schema,
  67          script_directory    => "$FindBin::Bin/../dbicdh",
  68          databases           => 'SQLite',
  69          sql_translator_args => { add_drop_table => 0 },
  70          force_overwrite     => $force_overwrite,
  71      }
  72  );
  73
  74  $dh->prepare_install;
  75  $dh->install;
  76
  77 =head2 dbicdh - Our migration scripts
  78
  79 Running C<install.pl> should create the following:
  80
  81  dbicdh/
  82  |-- SQLite
  83  |   `-- deploy
  84  |       `-- 1
  85  |           `-- 001-auto.sql
  86  `-- _source
  87      `-- deploy
  88          `-- 1
  89              `-- 001-auto.yml
  90
  91 =head3 001-auto.sql
  92
  93 DBIx::Class::DeploymentHandler automatically generates SQL from our schema
  94 that is suitable for SQLite
  95
  96 =head3 001-auto.yml
  97
  98 This contains all of the raw information about our schema that is then
  99 translated into the sql.
 100
 101 =head3 Population
 102
 103 To truly take advantage of all DBIx::Class::DeploymentHandler offers, you
 104 should probably be using it for population.  To do that all you need to do
 105 is create a file called C<dbicdh/_common/deploy/1/create_artists.pl>:
 106
 107   sub {
 108      my $schema = shift;
 109      $schema->resultset('Artist')->populate([
 110         ['artistid', 'name'],
 111         [1,          'Marillion'],
 112         [2,          'The Moutain Goats'],
 113         [3,          'Ladyhawke'],
 114      ]);
 115   };
 116
 117 =head1 Upgrading
 118
 119 Add a line to MyDatabase/Main/Result/Cd.pm below
 120
 121  __PACKAGE__->add_columns(qw/ cdid artist title /);
 122
 123 with
 124
 125  __PACKAGE__->add_column(isbn => { is_nullable => 1 });
 126
 127 Aside: It must be nullable or have a default - otherwise the upgrade will
 128 fail for logical reasons.  To be clear, if you add a column to a database and
 129 it is not nullable and has no default, what will the existing rows contain
 130 for that column?
 131
 132 Now you need to modify the schema version in your MyDatabase::Main file to
 133 tell DBIx::Class::DeploymentHandler the new schema version number. You will
 134 want to remember the earlier advice about integer version numbers.
 135
 136  our $VERSION = 2;
 137
 138 So here is our next script, C<upgrade.pl>:
 139
 140  #!/usr/bin/env perl
 141  use strict;
 142  use warnings;
 143  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
 144  use FindBin;
 145  use lib "$FindBin::Bin/../lib";
 146  use MyDatabase::Main;
 147  my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
 148
 149  my $dh = DH->new({
 150     schema              => $schema,
 151     script_directory    => "$FindBin::Bin/dbicdh",
 152     databases           => 'SQLite',
 153     sql_translator_args => { add_drop_table => 0 },
 154  });
 155
 156  $dh->prepare_deploy;
 157  $dh->prepare_upgrade({ from_version => 1, to_version => 2});
 158  $dh->upgrade;
 159
 160 Our script directory now looks like:
 161
 162   dbicdh/
 163   |-- SQLite
 164   |   |-- deploy
 165   |   |   |-- 1
 166   |   |   |   `-- 001-auto.sql
 167   |   |   `-- 2
 168   |   |       `-- 001-auto.sql
 169   |   `-- upgrade
 170   |       `-- 1-2
 171   |           `-- 001-auto.sql
 172   `-- _source
 173       `-- deploy
 174           |-- 1
 175           |   `-- 001-auto.yml
 176           `-- 2
 177               `-- 001-auto.yml
 178
 179 The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
 180 state of the db as at that version.  The C<upgrade/1-2/001-auto.sql> file
 181 is the most interesting one; it is what gets your database from version 1 to 2.
 182
 183 And again, you can create a Perl file like we did previously with the
 184 deploy stage.
 185