X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FDeploymentHandler%2FHandlesVersioning.pm;h=5ca2974da3043d0467537b773941527a9cb3a39a;hb=refs%2Fheads%2Fmoo-port;hp=b1ebb78158dae6e3079169232dbbff35d02314ca;hpb=24f4524be2492ee3699f7ee87eb899238c6268c7;p=dbsrgits%2FDBIx-Class-DeploymentHandler.git

diff --git a/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm b/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm
index b1ebb78..5ca2974 100644
--- a/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm
+++ b/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm
@@ -1,69 +1,133 @@
 package DBIx::Class::DeploymentHandler::HandlesVersioning;
-use Moose::Role;
+use Moo::Role;
+
+# ABSTRACT: Interface for version methods
 
 requires 'next_version_set';
+requires 'previous_version_set';
 
-has schema => (
-  isa      => 'DBIx::Class::Schema',
-  is       => 'ro',
-  required => 1,
-  handles => [qw( schema_version )],
-);
+1;
 
-has version_rs => (
-  isa        => 'DBIx::Class::ResultSet',
-  is         => 'ro',
-  lazy_build => 1,
-  handles    => [qw( is_installed db_version )],
-);
+# vim: ts=2 sw=2 expandtab
 
-sub _build_version_rs {
-   $_[0]->schema->set_us_up_the_bomb;
-   $_[0]->schema->resultset('__VERSION')
-}
+__END__
 
-has to_version => (
-  is         => 'ro',
-  lazy_build => 1,
-);
+=head1 DESCRIPTION
 
-sub _build_to_version { $_[0]->schema->schema_version }
+Typically a VersionHandler will take a C<to_version> and yeild an iterator of
+L<version sets|/VERSION SET>.
 
-1;
+Typically a call to a VersionHandler's L</next_version_set> with a C<db_version>
+of 1 and a C<to_version> of 5 will iterate over something like the following:
 
-__END__
+ [1, 2]
+ [2, 3]
+ [3, 4]
+ [4, 5]
+ undef
+
+or maybe just
+
+ [1, 5]
+ undef
+
+Really how the L<version sets|/VERSION SET> are arranged is up to the
+VersionHandler being used.
+
+In some cases users will not want versions to have inherent "previous
+versions," which is why the version set is an C<ArrayRef>.  In those cases the
+user should opt to returning merely the version that the database is being
+upgraded to in each step.
+
+One idea that has been suggested to me has been to have a form of dependency
+management of the database "versions."  In this case the versions are actually
+more like features that may or may not be applied.  For example, one might
+start with version 1 and have a feature (version) C<users>.
+
+Each feature might require that the database be upgraded to another version
+first.  If one were to implement a system like this, here is how the
+VersionHandler's L</next_version_set> might look.
+
+ to_version = "users", db_version = 1
+ [3]
+ [5]
+ ["users"]
+ undef
+
+So what just happened there is that C<users> depends on version 5, which depends
+on version 3, which depends on version 1, which is already installed.  To be
+clear, the reason we use single versions instead of version pairs is because
+there is no inherent order for this type of database upgraded.
+
+=head2 Downgrades
+
+For the typical case downgrades should be easy for users to perform and
+understand.  That means that with the first two examples given above we can use
+the L</previous_version_set> iterator to yeild the following:
+
+
+ db_version = 5, to_version=1
+ [5, 4]
+ [4, 3]
+ [3, 2]
+ [2, 1]
+ undef
+
+or maybe just
+
+ [5, 1]
+ undef
+
+Note that we do not swap the version number order.  This allows us to remain
+consistent in our version set abstraction, since a version set really just
+describes a version change, and not necesarily a defined progression.
+
+=method next_version_set
+
+ print 'versions to install: ';
+ while (my $vs = $dh->next_version_set) {
+   print join q(, ), @{$vs}
+ }
+ print qq(\n);
+
+Return a L<version set|/VERSION SET> describing each version that needs to be
+installed to upgrade to C<< $dh->to_version >>.
+
+=method previous_version_set
+
+ print 'versions to uninstall: ';
+ while (my $vs = $dh->previous_version_set) {
+   print join q(, ), @{$vs}
+ }
+ print qq(\n);
+
+Return a L<version set|/VERSION SET> describing each version that needs to be
+"installed" to downgrade to C<< $dh->to_version >>.
+
+=head1 VERSION SET
+
+A version set could be defined as:
+
+ subtype 'Version', as 'Str';
+ subtype 'VersionSet', as 'ArrayRef[Str]';
+
+A version set should uniquely identify a migration.
+
+=head1 KNOWN IMPLEMENTATIONS
+
+=over
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic>
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionHandler::DatabaseToSchemaVersions>
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionHandler::ExplicitVersions>
+
+=back
 
-# normally a VersionHandler will take
-# a to_version and yeild an iterator of
-# "version sets" or something like that.
-#
-# A "version set" is basically an arrayref
-# of "version numbers" (which we already know
-# is vague as is.)  Typically an call to a
-# VH w/ a db version of 1 and a "to_version"
-# of 5 will iterate over something like this:
-# [1, 2]
-# [2, 3]
-# [3, 4]
-# [4, 5]
-#
-# Of course rob wants to be able to have dep
-# management with his versions, so I *think* his
-# would work like this:
-#
-# to_version = 7, db_version = 1
-# [1]
-# [5]
-# [7]
-#
-# Because 7 depended on 5, 5 was installed first;
-# note that this potentially never released module
-# doesn't use version pairs, instead it just yeilds
-# versions.  Version pairs are too much work for users
-# to have to deal with in that sitation.  We may
-# actually switch to this for other versioners.
-#
-# The upshot of all this is that the DeploymentMethod
-# needs to be able to take an ArrayRef[VersionNumber],
-# instead of just a pair of VersionNumber.
-vim: ts=2 sw=2 expandtab