X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FDeploymentHandler%2FManual%2FIntro.pod;h=1148b53efe145b90c9945fc60270eb696d2f8b04;hb=3d416c8f66d964a153fccd0c3fc45d03b148879f;hp=c7e7a7db90ffa4a98ef1ebde3ad7991a38f8f886;hpb=298cdd9167cd5f9c0a480329ee5865c8b1d384f4;p=dbsrgits%2FDBIx-Class-DeploymentHandler.git

diff --git a/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod b/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod
index c7e7a7d..1148b53 100644
--- a/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod
+++ b/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod
@@ -1,14 +1,21 @@
-=head1 NAME
+package DBIx::Class::DeploymentHandler::Manual::Intro
 
-DBIx::Class::DeploymentHandler::Intro - Introduction to DBIx::Class::DeploymentHandler
+# ABSTRACT: Introduction to DBIx::Class::DeploymentHandler
 
-=head1 Why DBIx::Class::DeploymentHandler is worth using
+=pod
 
+=head1 Why is DBIx::Class::DeploymentHandler worth using?
 
-=head1 Our Sample database
+The most obvious reasons for using DBIx::Class::DeploymentHandler are
+that it can run multiple SQL scripts as well as Perl scripts, unlike
+DBIx::Class::Schema::Versioned, which only allows for a single SQL script.
+It is also extremely extensible, and is an opportunity for a break from
+backwards compatibility, so some regrettable decisions are avoided.
 
-Follow L<DBIx::Class::Manual::Intro> except for the parts setting up the database.
-After you are done, You should have the following files.
+=head1 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
@@ -19,30 +26,58 @@ After you are done, You should have the following files.
  |   `-- ResultSet
  `-- Main.pm
 
+Add a line like the following in your MyDatabase::Main file:
+
+ our $VERSION = 1;
+
+or if you are using a newer Perl you can use the prettier syntax:
+
+ package MyDatabase::Main 1;
+
+By default DBIx::Class::DeploymentHandler only uses integers for versions,
+this makes versioning much simpler for figuring out what version is next
+(or previous.) However, if you are using decimal numbers for versioning,
+you will need to create a separate DeploymentHandler class, as per
+L<DBIx::Class::DeploymentHandler::Cookbook::CustomResultSource>, and
+set the VersionHandler class_name from Monotonic to ExplicitVersions or
+DatabaseToSchemaVersions, as these handle version numbers as strings instead
+of integers.
+
 =head1 install.pl
 
 Our first script, C<install.pl> reads our schema file and creates the tables
 in the database.
 
- #!perl
+ #!/usr/bin/env perl
+
  use strict;
  use warnings;
  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
+ use Getopt::Long;
  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,
- });
+ my $force_overwrite = 0;
+
+ unless ( GetOptions( 'force_overwrite!' => \$force_overwrite ) ) {
+     die "Invalid options";
+ }
+
+ my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb.db');
+
+ my $dh = DH->new(
+     {
+         schema              => $schema,
+         script_directory    => "$FindBin::Bin/../dbicdh",
+         databases           => 'SQLite',
+         sql_translator_args => { add_drop_table => 0 },
+         force_overwrite     => $force_overwrite,
+     }
+ );
 
  $dh->prepare_install;
- $dh->install({ version => 1 });
+ $dh->install;
 
 =head2 dbicdh - Our migration scripts
 
@@ -58,6 +93,10 @@ Running C<install.pl> should create the following:
          `-- 1
              `-- 001-auto.yml
 
+You may wish to turn on L<debug logging|DBIx::Class::DeploymentHandler/"LOGGING"> 
+before running this script by setting the environment variable C<DBICDH_TRACE> to
+C<1>.
+
 =head3 001-auto.sql
 
 DBIx::Class::DeploymentHandler automatically generates SQL from our schema
@@ -68,6 +107,22 @@ that is suitable for SQLite
 This contains all of the raw information about our schema that is then
 translated into the sql.
 
+=head3 Population
+
+To truly take advantage of all DBIx::Class::DeploymentHandler offers, you
+should probably be using it for population.  To do that all you need to do
+is create a file called C<dbicdh/_common/deploy/1/create_artists.pl>:
+
+  sub {
+     my $schema = shift;
+     $schema->resultset('Artist')->populate([
+        ['artistid', 'name'],
+        [1,          'Marillion'],
+        [2,          'The Moutain Goats'],
+        [3,          'Ladyhawke'],
+     ]);
+  };
+
 =head1 Upgrading
 
 Add a line to MyDatabase/Main/Result/Cd.pm below
@@ -83,9 +138,15 @@ fail for logical reasons.  To be clear, if you add a column to a database and
 it is not nullable and has no default, what will the existing rows contain
 for that column?
 
+Now you need to modify the schema version in your MyDatabase::Main file to
+tell DBIx::Class::DeploymentHandler the new schema version number. You will
+want to remember the earlier advice about integer version numbers.
+
+ our $VERSION = 2;
+
 So here is our next script, C<upgrade.pl>:
 
- #!perl
+ #!/usr/bin/env perl
  use strict;
  use warnings;
  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
@@ -96,7 +157,7 @@ So here is our next script, C<upgrade.pl>:
 
  my $dh = DH->new({
     schema              => $schema,
-    script_directory    => "$FindBin::Bin/dbicdh",
+    script_directory    => "$FindBin::Bin/../dbicdh",
     databases           => 'SQLite',
     sql_translator_args => { add_drop_table => 0 },
  });
@@ -128,3 +189,6 @@ The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
 state of the db as at that version.  The C<upgrade/1-2/001-auto.sql> file
 is the most interesting one; it is what gets your database from version 1 to 2.
 
+And again, you can create a Perl file like we did previously with the
+deploy stage.
+