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  #!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/install/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 So here is our next script, C<upgrade.pl>:
 121
 122  #!perl
 123  use strict;
 124  use warnings;
 125  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
 126  use FindBin;
 127  use lib "$FindBin::Bin/../lib";
 128  use MyDatabase::Main;
 129  my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
 130
 131  my $dh = DH->new({
 132     schema              => $schema,
 133     script_directory    => "$FindBin::Bin/dbicdh",
 134     databases           => 'SQLite',
 135     sql_translator_args => { add_drop_table => 0 },
 136  });
 137
 138  $dh->prepare_deploy;
 139  $dh->prepare_upgrade({ from_version => 1, to_version => 2});
 140  $dh->upgrade;
 141
 142 Our script directory now looks like:
 143
 144   dbicdh/
 145   |-- SQLite
 146   |   |-- deploy
 147   |   |   |-- 1
 148   |   |   |   `-- 001-auto.sql
 149   |   |   `-- 2
 150   |   |       `-- 001-auto.sql
 151   |   `-- upgrade
 152   |       `-- 1-2
 153   |           `-- 001-auto.sql
 154   `-- _source
 155       `-- deploy
 156           |-- 1
 157           |   `-- 001-auto.yml
 158           `-- 2
 159               `-- 001-auto.yml
 160
 161 The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
 162 state of the db as at that version.  The C<upgrade/1-2/001-auto.sql> file
 163 is the most interesting one; it is what gets your database from version 1 to 2.
 164
 165 And again, you can create a Perl file like we did previously with the
 166 deploy stage.
 167