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<DBIx::Class::DeploymentHandler::HandlesVersionStorage/database_version>
=back
+=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>.
__END__
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<two existing implementations|/KNOWN IMPLEMENTATIONS> for examples of what you
+might want to do in your own storage.
=method add_database_version
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' })
return true iff the version storage is installed.
+=head1 KNOWN IMPLEMENTATIONS
+
+=over
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionStorage::Standard>
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionStorage::Deprecated>
+
+=back
+
+__END__
vim: ts=2 sw=2 expandtab
__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</next_version_set> 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<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 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</previous_version_set> 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: ';
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<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic>
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionHandler::DatabaseToSchemaVersions>
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionHandler::ExplicitVersions>
+
+=back
+
+__END__
+
vim: ts=2 sw=2 expandtab
projects / dbsrgits/DBIx-Class-DeploymentHandler.git / commitdiff