lib/DBIx/Class/DeploymentHandler/Cookbook/CustomVersionHandler.pod

   1 DBIx::Class::DeploymentHandler (short name of DBICDH) is a tool for creating
   2 and upgrading your database.  In code it is a significant extension of
   3 DBIx::Class::Schema::Versioned; in spirit it is similar to ActiveRecord
   4 migrations, but at a different angle; with this tool you define your database's
   5 schema (and thus your migrations as well) with the perl classes instead of
   6 having your migrations define the database and *that* defining your schema.
   7
   8 In general the tool is as simple as instantiating a DBICDH with a DBIC schema
   9 and calling ->install or ->upgrade.  But what makes DBICDH so much nicer
  10 than DBIx::Class::Schema::Versioned is it's extensibility.  DBICDH uses a
  11 combination of delegation and roles to allow for easy extension and code reuse.
  12
  13 There are 3 basic parts (which are delegated to) in a typical DBICDH:
  14
  15    1. VersionHandler: The component that says what version to go to next
  16    2. VersionStorage: The component that knows the version of the current
  17    database 3. DeployMethod: The component that generates  and runs the sql
  18    for migrations
  19
  20 Again, typically people will go with the defaults, but if someone wants to
  21 do something unusual the first thing that will get overridden will probably
  22 be the VersionHandler.
  23
  24 The default VersionHandler merely upgrades (and downgrades) with monotonic
  25 integers, increasing and decreasing respectively.  So if your database is at
  26 version 5 and you ask to upgrade to version 10, it will request the following
  27 discrete migrations to be deployed, in order: (5,6), (6,7), (7,8), (8,9),
  28 (9,10).
  29
  30 Now lets say we are working on a large project and the database deploys
  31 are piling up.  Programmer Jack has set up a user authentication system.
  32 Programmer Steve has set up a verification system based on Jacks auth.
  33 Programmer Antonio has created a "friend" system in the spirit of social
  34 networking which is also based on Jacks auth.  Lastly Programmer Bethany
  35 has created a parts management system which does not depend on any of the
  36 other systems.
  37
  38 Basically we can look at these as 4 distinct "versions" of the database, let's
  39 call them "Auth", "Verification", "Friends", and "Parts."  If code is managed
  40 carefully supposedly git can be used to see what code depends on other code.
  41 Let's pretend that we already have that part working.  Using such a tool
  42 would allow us to query git to discover what database versions depend on
  43 other versions and thus allow a non-linear migration path, allowing QC to
  44 take more time on more complex features without holding up the deployment
  45 of different parts of the live database.
  46
  47 Lets do a quick example using the versions we've defined above.  QC requests
  48 to install "Verification" since it's a major feature that must exist in the
  49 live site even before a private beta.  Our overridden VersionHandler will
  50 query git and see that "Verification" depends on "Auth."  It will then query
  51 git again to see what "Auth" depends on and it will discover that "Auth"
  52 does not depend on anything else.  So it will run two migrations, first
  53 "Auth," and then "Verification."
  54
  55 QC signs off on "Verification" and it gets deployed to the live site and
  56 the beta begins.  Meanwhile Antonio and Bethany both finish their respective
  57 subsystems.  QC requests that "Parts" be installed.  Because Parts depends on
  58 nothing else, it installs, QC likes it, it also gets deployed to the live beta.
  59
  60 QC asks for Antonio's "Friend" system to be deployed, and because it only
  61 depends on "Auth," which is already installed, it has no new dependencies
  62 and is installed just fine.  Finally, QC signs off on this last subsystem
  63 and it is also deployed to the live site.
  64
  65 The beauty of a system like the above described is that it allows the database
  66 to be upgraded based on what's ready as opposed to what people are working on.
  67 And because VersionHandler can easily be replaced with a more sophisticated
  68 VersionHandler the above is completely feasible, assuming the communication
  69 with git can be done (and it can.)