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  use strict;
  48  use warnings;
  49  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  50  use FindBin;
  51  use lib "$FindBin::Bin/../lib";
  52  use MyDatabase::Main;
  53  my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
  54
  55  my $dh = DH->new({
  56       schema              => $schema,
  57       script_directory    => "$FindBin::Bin/dbicdh",
  58       databases           => 'SQLite',
  59       sql_translator_args => { add_drop_table => 0 },
  60  });
  61
  62  $dh->prepare_install;
  63  $dh->install;
  64
  65 =head2 dbicdh - Our migration scripts
  66
  67 Running C<install.pl> should create the following:
  68
  69  dbicdh/
  70  |-- SQLite
  71  |   `-- deploy
  72  |       `-- 1
  73  |           `-- 001-auto.sql
  74  `-- _source
  75      `-- deploy
  76          `-- 1
  77              `-- 001-auto.yml
  78
  79 =head3 001-auto.sql
  80
  81 DBIx::Class::DeploymentHandler automatically generates SQL from our schema
  82 that is suitable for SQLite
  83
  84 =head3 001-auto.yml
  85
  86 This contains all of the raw information about our schema that is then
  87 translated into the sql.
  88
  89 =head3 Population
  90
  91 To truly take advantage of all DBIx::Class::DeploymentHandler offers, you
  92 should probably be using it for population.  To do that all you need to do
  93 is create a file called C<dbicdh/_common/deploy/1/create_artists.pl>:
  94
  95  sub {
  96     my $schema = shift;
  97     $schema->resultset('User')->populate([
  98        ['name'],
  99        ['Marillion'],
 100        ['The Moutain Goats'],
 101        ['Ladyhawke'],
 102     ]);
 103  };
 104
 105 =head1 Upgrading
 106
 107 Add a line to MyDatabase/Main/Result/Cd.pm below
 108
 109  __PACKAGE__->add_columns(qw/ cdid artist title /);
 110
 111 with
 112
 113  __PACKAGE__->add_column(isbn => { is_nullable => 1 });
 114
 115 Aside: It must be nullable or have a default - otherwise the upgrade will
 116 fail for logical reasons.  To be clear, if you add a column to a database and
 117 it is not nullable and has no default, what will the existing rows contain
 118 for that column?
 119
 120 Now you need to modify the schema version in your MyDatabase::Main file to
 121 tell DBIx::Class::DeploymentHandler the new schema version number. You will
 122 want to remember the earlier advice about integer version numbers.
 123
 124  our $VERSION = 2;
 125
 126 So here is our next script, C<upgrade.pl>:
 127
 128  #!/usr/bin/env perl
 129  use strict;
 130  use warnings;
 131  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
 132  use FindBin;
 133  use lib "$FindBin::Bin/../lib";
 134  use MyDatabase::Main;
 135  my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
 136
 137  my $dh = DH->new({
 138     schema              => $schema,
 139     script_directory    => "$FindBin::Bin/dbicdh",
 140     databases           => 'SQLite',
 141     sql_translator_args => { add_drop_table => 0 },
 142  });
 143
 144  $dh->prepare_deploy;
 145  $dh->prepare_upgrade({ from_version => 1, to_version => 2});
 146  $dh->upgrade;
 147
 148 Our script directory now looks like:
 149
 150   dbicdh/
 151   |-- SQLite
 152   |   |-- deploy
 153   |   |   |-- 1
 154   |   |   |   `-- 001-auto.sql
 155   |   |   `-- 2
 156   |   |       `-- 001-auto.sql
 157   |   `-- upgrade
 158   |       `-- 1-2
 159   |           `-- 001-auto.sql
 160   `-- _source
 161       `-- deploy
 162           |-- 1
 163           |   `-- 001-auto.yml
 164           `-- 2
 165               `-- 001-auto.yml
 166
 167 The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
 168 state of the db as at that version.  The C<upgrade/1-2/001-auto.sql> file
 169 is the most interesting one; it is what gets your database from version 1 to 2.
 170
 171 And again, you can create a Perl file like we did previously with the
 172 deploy stage.
 173