fix POD bug from RT#79301

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

package DBIx::Class::DeploymentHandler::Cookbook::CustomResultSource;

=pod

=head1 NAME

DBIx::Class::DeploymentHandler::Cookbook::CustomResultSource - Customize how
your DBICDH versions are stored

=head1 DESCRIPTION

One of the reasons for the absurd level of flexibility that
L<DBIx::Class::DeploymentHandler> is so that you can do things that we did not
originally anticipate.  Surprisingly, I never added a method to change the
table for the version storage.  That's fine though, the following recipe
shows how one can do it in style:

=head2 Version Storage

 package MyApp::Schema::DBICDHStorage;
 use Moose;
 extends 'DBIx::Class::DeploymentHandler::VersionStorage::Standard';

 sub _build_version_rs {
   $_[0]->schema->register_class(
     __VERSION =>
       'MyApp::Schema::DBICDHStorageResult'
   );
   $_[0]->schema->resultset('__VERSION')
 }

 no Moose;
 __PACKAGE__->meta->make_immutable;
 1;

There's not a whole lot special there.  The only real bit of code to point out
is the C<register_class> call.  We make sure to point C<__VERSION> to the
result class that we will define next.

=head2 Version Result Class

 package MyApp::Schema::DBICDHStorageResult;
 use parent 'DBIx::Class::DeploymentHandler::VersionStorage::Standard::VersionResult';
 __PACKAGE__->table('fl_bench_journal_versions');
 1;

As you can see, this is almost silly how simple it is, we just change the
table being set on the original result.

=head2 Our very own DeploymentHandler

 package MyApp::Schema::DeploymentHandler;
 use Moose;
 extends 'DBIx::Class::DeploymentHandler::Dad';

 # a single with would be better, but we can't do that
 # see: http://rt.cpan.org/Public/Bug/Display.html?id=46347
 with 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
     interface_role       => 'DBIx::Class::DeploymentHandler::HandlesDeploy',
     class_name           => 'DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator',
     delegate_name        => 'deploy_method',
     attributes_to_assume => ['schema'],
     attributes_to_copy   => [qw( databases script_directory sql_translator_args )],
   },
   'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
     interface_role       => 'DBIx::Class::DeploymentHandler::HandlesVersioning',
     class_name           => 'DBIx::Class::DeploymentHandler::VersionHandler::Monotonic',
     delegate_name        => 'version_handler',
     attributes_to_assume => [qw( database_version schema_version to_version )],
   },
   'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
     interface_role       => 'DBIx::Class::DeploymentHandler::HandlesVersionStorage',
     class_name           => 'MyApp::Schema::DBICDHStorage',
     delegate_name        => 'version_storage',
     attributes_to_assume => ['schema'],
   };
 with 'DBIx::Class::DeploymentHandler::WithReasonableDefaults';

 sub prepare_version_storage_install {
   my $self = shift;

   $self->prepare_resultsource_install({
       result_source => $self->version_storage->version_rs->result_source
   });
 }

 sub install_version_storage {
   my $self = shift;

   my $version = (shift || {})->{version} || $self->schema_version;
   $self->install_resultsource({
       result_source => $self->version_storage->version_rs->result_source,
       version       => $version,
   });
 }

 sub prepare_install {
    $_[0]->prepare_deploy;
    $_[0]->prepare_version_storage_install;
 }

 no Moose;
 __PACKAGE__->meta->make_immutable;
 1;

Note: if you are using decimal numbers for versioning, you should ammend
this DeploymentHandler package, setting it's VersionHandler class_name from
Monotonic ( which handles integer only version numbers ) to ExplicitVersions
or DatabaseToSchemaVersions, as these handle version numbers as strings
instead of integers.