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 preinstall.pl
  23
  24 Our first script, preinstall.pl reads our schema file and creates the tables in the database.
  25
  26   use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  27   use FindBin;
  28   use lib "$FindBin::Bin/../lib";
  29   use MyDatabase::Main;
  30   my $schema       = MyDatabase::Main->connect('dbi:SQLite:mydb');
  31
  32   my $dh = DH->new(
  33       {
  34           schema           => $schema,
  35           script_directory => "$FindBin::Bin/dbicdh",
  36           databases        => 'SQLite',
  37           sql_translator_args => { add_drop_table => 0 },
  38           schema_version   => 1,
  39       }
  40   );
  41
  42   $dh->prepare_install;
  43   $dh->install({version => 1});
  44
  45 TODO TODO TODO TODO
  46
  47 Someone really ought to fix the bug causing dbicdh/SQLite/deploy/1/001-auto.sql to have the dbix_class_deploymenthandler_versions
  48
  49 Right now, you need to comment out the version table crap in the sql file , then run install, then uncomment it.
  50
  51 TODO TODO TODO TODO
  52
  53 =head2 dbicdh - Our migration scripts
  54
  55 Running preinstall.pl should create the following:
  56
  57   dbicdh/
  58   |-- SQLite
  59   |   `-- deploy
  60   |       `-- 1
  61   |           `-- 001-auto.sql
  62   `-- _source
  63       `-- deploy
  64           `-- 1
  65               `-- 001-auto.yml
  66
  67 =head3 001-auto.sql
  68
  69 DBIx::Class::DeploymentHandler automatically generates SQL from our schema that is suitable for SQLite
  70
  71 =head3 001-auto.yml
  72
  73 This contains all of the raw information about our schema that is then translated into the sql.
  74
  75 =head1 Upgrading
  76
  77 Add a line to MyDatabase/Main/Result/Cd.pm below
  78
  79     __PACKAGE__->add_columns(qw/ cdid artist title /);
  80
  81 with
  82
  83     __PACKAGE__->add_column("isbn" => { is_nullable => 1 });
  84
  85 (We need it to either be nullable, or have a default - merely adding it to the add_columns line will not work)
  86
  87 Then run the following script:
  88
  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       {
  99           schema           => $schema,
 100           script_directory => "$FindBin::Bin/dbicdh",
 101           databases        => 'SQLite',
 102           sql_translator_args => { add_drop_table => 0 },
 103      schema_version => 2,
 104      from_version => 1,
 105      to_version => 2,
 106       }
 107   );
 108
 109   $dh->prepare_deploy;
 110   $dh->prepare_upgrade({ from_version => 1, to_version => 2});
 111   $dh->upgrade;
 112
 113
 114
 115 Our script directory now looks like:
 116
 117   dbicdh/
 118   |-- SQLite
 119   |   |-- deploy
 120   |   |   |-- 1
 121   |   |   |   `-- 001-auto.sql
 122   |   |   `-- 2
 123   |   |       `-- 001-auto.sql
 124   |   `-- upgrade
 125   |       `-- 1-2
 126   |           `-- 001-auto.sql
 127   `-- _source
 128       `-- deploy
 129           |-- 1
 130           |   `-- 001-auto.yml
 131           `-- 2
 132               `-- 001-auto.yml
 133
 134 The new deploy/001-auto.sql and deploy/001-auto.yml files are the state of the db as at that version.  The upgrade/1-2/001-auto.sql file is the most interesting one
 135
 136   -- Convert schema '/home/jdobbie/Projects/intro/dbicdh/_source/deploy/1/001-auto.yml' to '/home/jdobbie/Projects/intro/dbicdh/_source/deploy/2/001-auto.yml':;
 137
 138   ;
 139   BEGIN;
 140
 141   ;
 142   ALTER TABLE cd ADD COLUMN isbn;
 143
 144   ;
 145
 146   COMMIT;
 147