From: Arthur Axel 'fREW' Schmidt Date: Fri, 2 Apr 2010 14:50:36 +0000 (-0500) Subject: lots more doc X-Git-Tag: v0.001000_01~17 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ed1721b92e5774426f63bbf69bc4b2c997fbf62e;p=dbsrgits%2FDBIx-Class-DeploymentHandler.git lots more doc --- diff --git a/lib/DBIx/Class/DeploymentHandler/Dad.pm b/lib/DBIx/Class/DeploymentHandler/Dad.pm index ccd6488..fcdd868 100644 --- a/lib/DBIx/Class/DeploymentHandler/Dad.pm +++ b/lib/DBIx/Class/DeploymentHandler/Dad.pm @@ -159,8 +159,6 @@ 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. -The methods are: - =head2 database_version see L @@ -187,6 +185,19 @@ see L =back +=head2 SUBCLASSING + +All of the methods mentioned in L and +L 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 and +L, 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, +L, and +L. __END__ diff --git a/lib/DBIx/Class/DeploymentHandler/HandlesDeploy.pm b/lib/DBIx/Class/DeploymentHandler/HandlesDeploy.pm index 3ee83f0..34e83ad 100644 --- a/lib/DBIx/Class/DeploymentHandler/HandlesDeploy.pm +++ b/lib/DBIx/Class/DeploymentHandler/HandlesDeploy.pm @@ -12,8 +12,6 @@ requires 'deploy'; 1; -__END__ - # should this be renamed prepare_deploy? =method prepare_install @@ -65,4 +63,20 @@ version installed and C<$sql> used to get to that version. call a single downgrade migration. Takes an arrayref describing the version to downgrade to. +=head1 KNOWN IMPLEMENTATIONS + +=over + +=item * + +L + +=item * + +L + +=back + +__END__ + vim: ts=2 sw=2 expandtab diff --git a/lib/DBIx/Class/DeploymentHandler/HandlesVersionStorage.pm b/lib/DBIx/Class/DeploymentHandler/HandlesVersionStorage.pm index 9bf7a0f..ffdb444 100644 --- a/lib/DBIx/Class/DeploymentHandler/HandlesVersionStorage.pm +++ b/lib/DBIx/Class/DeploymentHandler/HandlesVersionStorage.pm @@ -1,18 +1,20 @@ package DBIx::Class::DeploymentHandler::HandlesVersionStorage; use Moose::Role; -requires 'database_version'; requires 'add_database_version'; +requires 'database_version'; requires 'delete_database_version'; requires 'version_storage_is_installed'; 1; -__END__ -=method database_version +=head1 DESCRIPTION - my $db_version = $version_storage->database_version; +Typically VersionStorages will be implemented with a simple +DBIx::Class::Result. Take a look at the +L for examples of what you +might want to do in your own storage. =method add_database_version @@ -24,6 +26,10 @@ __END__ Store a new version into the version storage +=method database_version + + my $db_version = $version_storage->database_version; + =method delete_database_version $dh->delete_database_version({ version => '1.02' }) @@ -37,5 +43,20 @@ simply deletes given database version from the version storage return true iff the version storage is installed. +=head1 KNOWN IMPLEMENTATIONS + +=over + +=item * + +L + +=item * + +L + +=back + +__END__ vim: ts=2 sw=2 expandtab diff --git a/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm b/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm index 43f1009..43f7ffb 100644 --- a/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm +++ b/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm @@ -9,6 +9,78 @@ requires 'previous_version_set'; __END__ +=head1 DESCRIPTION + +Typically a VersionHandler will take a to_version and yeild an iterator of +"version sets." + +A "version set" is basically an arrayref of "version numbers" (which we +already know is vague as is.) Typically a call to a VersionHandler's +L with a db version of 1 and a "to_version" of 5 will +iterate over something like the following: + + [1, 2] + [2, 3] + [3, 4] + [4, 5] + undef + +or maybe just + + [1, 5] + undef + +Really how the version set's 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. 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. + +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 might look. + + to_version = "users", db_version = 1 + [3] + [5] + ["users"] + undef + +So what just happened there is that C 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 I'd like downgrades to be easy for users to perform and +understand. That means that with the first two examples give above we can use +the L iterator to yeild the following: + + + db_version = 5, to_version=1 + [4, 5] + [3, 4] + [2, 3] + [1, 2] + undef + +or maybe just + + [1, 5] + 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: '; @@ -31,37 +103,24 @@ installed to upgrade to C<< $dh->to_version >>. return an arrayref describing each version that needs to be "installed" to downgrade to C<< $dh->to_version >>. -# 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. +=head1 KNOWN IMPLEMENTATIONS + +=over + +=item * + +L + +=item * + +L + +=item * + +L + +=back + +__END__ + vim: ts=2 sw=2 expandtab