From: Arthur Axel 'fREW' Schmidt Date: Mon, 31 May 2010 20:51:07 +0000 (-0500) Subject: initial copy of text from email X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits%2FDBIx-Class-DeploymentHandler.git;a=commitdiff_plain;h=refs%2Fheads%2Fcustom-version-handler-doc initial copy of text from email --- diff --git a/lib/DBIx/Class/DeploymentHandler/Cookbook/CustomVersionHandler.pod b/lib/DBIx/Class/DeploymentHandler/Cookbook/CustomVersionHandler.pod new file mode 100644 index 0000000..c4b6ee4 --- /dev/null +++ b/lib/DBIx/Class/DeploymentHandler/Cookbook/CustomVersionHandler.pod @@ -0,0 +1,69 @@ +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.)