initial copy of text from email

[dbsrgits/DBIx-Class-DeploymentHandler.git] / lib / DBIx / Class / DeploymentHandler / Cookbook / CustomVersionHandler.pod

DBIx::Class::DeploymentHandler (short name of DBICDH) is a tool for creating
and upgrading your database.  In code it is a significant extension of
DBIx::Class::Schema::Versioned; in spirit it is similar to ActiveRecord
migrations, but at a different angle; with this tool you define your database's
schema (and thus your migrations as well) with the perl classes instead of
having your migrations define the database and *that* defining your schema.

In general the tool is as simple as instantiating a DBICDH with a DBIC schema
and calling ->install or ->upgrade.  But what makes DBICDH so much nicer
than DBIx::Class::Schema::Versioned is it's extensibility.  DBICDH uses a
combination of delegation and roles to allow for easy extension and code reuse.

There are 3 basic parts (which are delegated to) in a typical DBICDH:

   1. VersionHandler: The component that says what version to go to next
   2. VersionStorage: The component that knows the version of the current
   database 3. DeployMethod: The component that generates  and runs the sql
   for migrations

Again, typically people will go with the defaults, but if someone wants to
do something unusual the first thing that will get overridden will probably
be the VersionHandler.

The default VersionHandler merely upgrades (and downgrades) with monotonic
integers, increasing and decreasing respectively.  So if your database is at
version 5 and you ask to upgrade to version 10, it will request the following
discrete migrations to be deployed, in order: (5,6), (6,7), (7,8), (8,9),
(9,10).

Now lets say we are working on a large project and the database deploys
are piling up.  Programmer Jack has set up a user authentication system.
Programmer Steve has set up a verification system based on Jacks auth.
Programmer Antonio has created a "friend" system in the spirit of social
networking which is also based on Jacks auth.  Lastly Programmer Bethany
has created a parts management system which does not depend on any of the
other systems.

Basically we can look at these as 4 distinct "versions" of the database, let's
call them "Auth", "Verification", "Friends", and "Parts."  If code is managed
carefully supposedly git can be used to see what code depends on other code.
Let's pretend that we already have that part working.  Using such a tool
would allow us to query git to discover what database versions depend on
other versions and thus allow a non-linear migration path, allowing QC to
take more time on more complex features without holding up the deployment
of different parts of the live database.

Lets do a quick example using the versions we've defined above.  QC requests
to install "Verification" since it's a major feature that must exist in the
live site even before a private beta.  Our overridden VersionHandler will
query git and see that "Verification" depends on "Auth."  It will then query
git again to see what "Auth" depends on and it will discover that "Auth"
does not depend on anything else.  So it will run two migrations, first
"Auth," and then "Verification."

QC signs off on "Verification" and it gets deployed to the live site and
the beta begins.  Meanwhile Antonio and Bethany both finish their respective
subsystems.  QC requests that "Parts" be installed.  Because Parts depends on
nothing else, it installs, QC likes it, it also gets deployed to the live beta.

QC asks for Antonio's "Friend" system to be deployed, and because it only
depends on "Auth," which is already installed, it has no new dependencies
and is installed just fine.  Finally, QC signs off on this last subsystem
and it is also deployed to the live site.

The beauty of a system like the above described is that it allows the database
to be upgraded based on what's ready as opposed to what people are working on.
And because VersionHandler can easily be replaced with a more sophisticated
VersionHandler the above is completely feasible, assuming the communication
with git can be done (and it can.)