Initial commit of intro

diff --git a/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod b/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod
new file mode 100644 (file)
index 0000000..376e33c
--- /dev/null
+++ b/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod
@@ -0,0 +1,147 @@
+=head1 NAME
+
+DBIx::Class::DeploymentHandler::Intro - Introduction to DBIx::Class::DeploymentHandler
+
+=head1 Why DBIx::Class::DeploymentHandler is worth using
+
+
+=head1 Our Sample database
+
+Follow L<DBIx::Class::Manual::Intro> except for the parts setting up the database.
+After you are done, You should have the following files.
+
+  MyDatabase/
+  |-- Main
+  |   |-- Result
+  |   |   |-- Artist.pm
+  |   |   |-- Cd.pm
+  |   |   `-- Track.pm
+  |   `-- ResultSet
+  `-- Main.pm
+
+=head1 preinstall.pl
+
+Our first script, preinstall.pl reads our schema file and creates the tables in the database.
+
+  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
+  use FindBin;
+  use lib "$FindBin::Bin/../lib";
+  use MyDatabase::Main;
+  my $schema       = MyDatabase::Main->connect('dbi:SQLite:mydb');
+
+  my $dh = DH->new(
+      {
+          schema           => $schema,
+          script_directory => "$FindBin::Bin/dbicdh",
+          databases        => 'SQLite',
+          sql_translator_args => { add_drop_table => 0 },
+          schema_version   => 1,
+      }
+  );
+
+  $dh->prepare_install;
+  $dh->install({version => 1});
+
+TODO TODO TODO TODO
+
+Someone really ought to fix the bug causing dbicdh/SQLite/deploy/1/001-auto.sql to have the dbix_class_deploymenthandler_versions
+
+Right now, you need to comment out the version table crap in the sql file , then run install, then uncomment it.
+
+TODO TODO TODO TODO
+
+=head2 dbicdh - Our migration scripts
+
+Running preinstall.pl should create the following:
+
+  dbicdh/
+  |-- SQLite
+  |   `-- deploy
+  |       `-- 1
+  |           `-- 001-auto.sql
+  `-- _source
+      `-- deploy
+          `-- 1
+              `-- 001-auto.yml
+
+=head3 001-auto.sql
+
+DBIx::Class::DeploymentHandler automatically generates SQL from our schema that is suitable for SQLite
+
+=head3 001-auto.yml
+
+This contains all of the raw information about our schema that is then translated into the sql.
+
+=head1 Upgrading
+
+Add a line to MyDatabase/Main/Result/Cd.pm below
+
+    __PACKAGE__->add_columns(qw/ cdid artist title /);
+
+with
+
+    __PACKAGE__->add_column("isbn" => { is_nullable => 1 });
+
+(We need it to either be nullable, or have a default - merely adding it to the add_columns line will not work)
+
+Then run the following script:
+
+  use strict;
+  use warnings;
+  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
+  use FindBin;
+  use lib "$FindBin::Bin/../lib";
+  use MyDatabase::Main;
+  my $schema       = MyDatabase::Main->connect('dbi:SQLite:mydb');
+
+  my $dh = DH->new(
+      {
+          schema           => $schema,
+          script_directory => "$FindBin::Bin/dbicdh",
+          databases        => 'SQLite',
+          sql_translator_args => { add_drop_table => 0 },
+     schema_version => 2,
+     from_version => 1,
+     to_version => 2,
+      }
+  );
+
+  $dh->prepare_deploy;
+  $dh->prepare_upgrade({ from_version => 1, to_version => 2});
+  $dh->upgrade;
+
+
+
+Our script directory now looks like:
+
+  dbicdh/
+  |-- SQLite
+  |   |-- deploy
+  |   |   |-- 1
+  |   |   |   `-- 001-auto.sql
+  |   |   `-- 2
+  |   |       `-- 001-auto.sql
+  |   `-- upgrade
+  |       `-- 1-2
+  |           `-- 001-auto.sql
+  `-- _source
+      `-- deploy
+          |-- 1
+          |   `-- 001-auto.yml
+          `-- 2
+              `-- 001-auto.yml
+
+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
+
+  -- 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':;
+
+  ;
+  BEGIN;
+
+  ;
+  ALTER TABLE cd ADD COLUMN isbn;
+
+  ;
+
+  COMMIT;
+