X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FDeploymentHandler%2FDad.pm;h=85757a9e7cf0427285c300976ae450849511317d;hb=91557c90ba0b3f313696c2f15dd8b56fb8358574;hp=db485b3c8320487165fb7e0d36122a047efd412f;hpb=cfc9edf93ec15cb3ae64af76905d96c89681f51b;p=dbsrgits%2FDBIx-Class-DeploymentHandler.git

diff --git a/lib/DBIx/Class/DeploymentHandler/Dad.pm b/lib/DBIx/Class/DeploymentHandler/Dad.pm
index db485b3..85757a9 100644
--- a/lib/DBIx/Class/DeploymentHandler/Dad.pm
+++ b/lib/DBIx/Class/DeploymentHandler/Dad.pm
@@ -1,5 +1,7 @@
 package DBIx::Class::DeploymentHandler::Dad;
 
+# ABSTRACT: Parent class for DeploymentHandlers
+
 use Moose;
 use Method::Signatures::Simple;
 require DBIx::Class::Schema;    # loaded for type constraint
@@ -66,6 +68,10 @@ __PACKAGE__->meta->make_immutable;
 
 1;
 
+# vim: ts=2 sw=2 expandtab
+
+__END__
+
 =pod
 
 =attr schema
@@ -75,7 +81,7 @@ and generate the DDL.
 
 =attr backup_directory
 
-The directory that backups are stored in
+The directory where backups are stored
 
 =attr to_version
 
@@ -88,7 +94,7 @@ The version (defaults to schema's version) to migrate the database to
 Deploys the current schema into the database.  Populates C<version_storage> with
 C<version> and C<ddl>.
 
-B<Note>: you typically need to call C<< $dh->prepare_install >> before you call
+B<Note>: you typically need to call C<< $dh->prepare_deploy >> before you call
 this method.
 
 B<Note>: you cannot install on top of an already installed database
@@ -107,7 +113,7 @@ returned from L</upgrade_single_step>.
  $dh->downgrade
 
 Downgrades the database one step at a time till L</previous_version_set>
-returns C<undef>.  Each downgrade step will delete a C<version>from the
+returns C<undef>.  Each downgrade step will delete a C<version> from the
 version storage.
 
 =method backup
@@ -120,72 +126,80 @@ assuming it will work.
 
 =head1 METHODS THAT ARE REQUIRED IN SUBCLASSES
 
+=head2 deploy
+
+See L<DBIx::Class::DeploymentHandler::HandlesDeploy/deploy>.
+
 =head2 version_storage_is_installed
 
- warn q(I can't version this database!)
-   unless $dh->version_storage_is_installed
+See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/version_storage_is_installed>.
 
-return true iff the version storage is installed.
+=head2 add_database_version
 
-=head2 deploy
+See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/add_database_version>.
 
- $dh->deploy
+=head2 delete_database_version
 
-Deploy the schema to the database.
+See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/delete_database_version>.
 
-=head2 add_database_version
+=head2 next_version_set
 
- $dh->add_database_version({
-   version     => '1.02',
-   ddl         => $ddl # can be undef,
-   upgrade_sql => $sql # can be undef,
- });
+See L<DBIx::Class::DeploymentHandler::HandlesVersioning/next_version_set>.
 
-Store a new version into the version storage
+=head2 previous_version_set
 
-=head2 delete_database_version
+See L<DBIx::Class::DeploymentHandler::HandlesVersioning/previous_version_set>.
 
- $dh->delete_database_version({ version => '1.02' })
+=head2 upgrade_single_step
 
-simply deletes given database version from the version storage
+See L<DBIx::Class::DeploymentHandler::HandlesDeploy/upgrade_single_step>.
 
-=head2 next_version_set
+=head2 downgrade_single_step
 
- print 'versions to install: ';
- while (my $vs = $dh->next_version_set) {
-   print join q(, ), @{$vs}
- }
- print qq(\n);
+See L<DBIx::Class::DeploymentHandler::HandlesDeploy/downgrade_single_step>.
 
-return an arrayref describing each version that needs to be
-installed to upgrade to C<< $dh->to_version >>.
+=head1 ORTHODOX METHODS
 
-=head2 previous_version_set
+These methods are not actually B<required> as things will probably still work
+if you don't implement them, but if you want your subclass to get along with
+other subclasses (or more likely, tools made to use another subclass), you
+should probably implement these too, even if they are no-ops.
 
- print 'versions to uninstall: ';
- while (my $vs = $dh->previous_version_set) {
-   print join q(, ), @{$vs}
- }
- print qq(\n);
+=head2 database_version
 
-return an arrayref describing each version that needs to be
-"installed" to downgrade to C<< $dh->to_version >>.
+see L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/database_version>
 
-=head2 upgrade_single_step
+=head2 prepare_deploy
 
- my ($ddl, $sql) = @{$dh->upgrade_single_step($version_set)||[]}
+see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_deploy>
 
-call a single upgrade migration.  Takes an arrayref describing the version to
-upgrade to.  Optionally return an arrayref containing C<$ddl> describing
-version installed and C<$sql> used to get to that version.
+=head2 prepare_resultsource_install
 
-=head2 downgrade_single_step
+see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_resultsource_install>
 
- $dh->upgrade_single_step($version_set);
+=head2 install_resultsource
 
-call a single downgrade migration.  Takes an arrayref describing the version to
-downgrade to.
+see L<DBIx::Class::DeploymentHandler::HandlesDeploy/install_resultsource>
 
-__END__
+=head2 prepare_upgrade
+
+see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_upgrade>
+
+=head2 prepare_downgrade
+
+see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_downgrade>
+
+=head2 SUBCLASSING
+
+All of the methods mentioned in L</METHODS THAT ARE REQUIRED IN SUBCLASSES> and
+L</ORTHODOX METHODS> can be implemented in any fashion you choose.  In the
+spirit of code reuse I have used roles to implement them in my two subclasses,
+L<DBIx::Class::DeploymentHandler> and
+L<DBIx::Class::DeploymentHandler::Deprecated>, but you are free to implement
+them entirely in a subclass if you so choose to.
+
+For in-depth documentation on how methods are supposed to work, see the roles
+L<DBIx::Class::DeploymentHandler::HandlesDeploy>,
+L<DBIx::Class::DeploymentHandler::HandlesVersioning>, and
+L<DBIx::Class::DeploymentHandler::HandlesVersionStorage>.
 
-vim: ts=2 sw=2 expandtab