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 You may wish to turn on L<debug logging|DBIx::Class::DeploymentHandler/"LOGGING">
  92 before running this script by setting the environment variable C<DBICDH_TRACE> to
  93 C<1>.
  94
  95 =head3 001-auto.sql
  96
  97 DBIx::Class::DeploymentHandler automatically generates SQL from our schema
  98 that is suitable for SQLite
  99
 100 =head3 001-auto.yml
 101
 102 This contains all of the raw information about our schema that is then
 103 translated into the sql.
 104
 105 =head3 Population
 106
 107 To truly take advantage of all DBIx::Class::DeploymentHandler offers, you
 108 should probably be using it for population.  To do that all you need to do
 109 is create a file called C<dbicdh/_common/deploy/1/create_artists.pl>:
 110
 111   sub {
 112      my $schema = shift;
 113      $schema->resultset('Artist')->populate([
 114         ['artistid', 'name'],
 115         [1,          'Marillion'],
 116         [2,          'The Moutain Goats'],
 117         [3,          'Ladyhawke'],
 118      ]);
 119   };
 120
 121 =head1 Upgrading
 122
 123 Add a line to MyDatabase/Main/Result/Cd.pm below
 124
 125  __PACKAGE__->add_columns(qw/ cdid artist title /);
 126
 127 with
 128
 129  __PACKAGE__->add_column(isbn => { is_nullable => 1 });
 130
 131 Aside: It must be nullable or have a default - otherwise the upgrade will
 132 fail for logical reasons.  To be clear, if you add a column to a database and
 133 it is not nullable and has no default, what will the existing rows contain
 134 for that column?
 135
 136 Now you need to modify the schema version in your MyDatabase::Main file to
 137 tell DBIx::Class::DeploymentHandler the new schema version number. You will
 138 want to remember the earlier advice about integer version numbers.
 139
 140  our $VERSION = 2;
 141
 142 So here is our next script, C<upgrade.pl>:
 143
 144  #!/usr/bin/env perl
 145  use strict;
 146  use warnings;
 147  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
 148  use FindBin;
 149  use lib "$FindBin::Bin/../lib";
 150  use MyDatabase::Main;
 151  my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
 152
 153  my $dh = DH->new({
 154     schema              => $schema,
 155     script_directory    => "$FindBin::Bin/dbicdh",
 156     databases           => 'SQLite',
 157     sql_translator_args => { add_drop_table => 0 },
 158  });
 159
 160  $dh->prepare_deploy;
 161  $dh->prepare_upgrade({ from_version => 1, to_version => 2});
 162  $dh->upgrade;
 163
 164 Our script directory now looks like:
 165
 166   dbicdh/
 167   |-- SQLite
 168   |   |-- deploy
 169   |   |   |-- 1
 170   |   |   |   `-- 001-auto.sql
 171   |   |   `-- 2
 172   |   |       `-- 001-auto.sql
 173   |   `-- upgrade
 174   |       `-- 1-2
 175   |           `-- 001-auto.sql
 176   `-- _source
 177       `-- deploy
 178           |-- 1
 179           |   `-- 001-auto.yml
 180           `-- 2
 181               `-- 001-auto.yml
 182
 183 The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
 184 state of the db as at that version.  The C<upgrade/1-2/001-auto.sql> file
 185 is the most interesting one; it is what gets your database from version 1 to 2.
 186
 187 And again, you can create a Perl file like we did previously with the
 188 deploy stage.
 189