=pod

=head1 DESCRIPTION

The standard DeploymentHandler storage only stores the version of the schema. This means you can't deploy multiple DH-handled DBIC schemata into the same database.

This module has an extra column to store the schema that it is deploying as well as the version.

=head1 SYNOPSIS

To use it, you'll have to create a new subclass of L that uses this module instead of the standard one, and instantiate that in your script instead.

# See t/lib/Dad.pm for a working example
package My::DH::Dad;

use Moose;
extends 'DBIx::Class::DeploymentHandler::Dad';

with 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
  ...
  'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
    interface_role       => 'DBIx::Class::DeploymentHandler::HandlesVersionStorage',
    class_name           => 'DBIx::Class::DeploymentHandler::VersionStorage::WithSchema',
    delegate_name        => 'version_storage',
    attributes_to_assume => ['schema'],
  };

# in a script ...
my $handler = My::DH::Dad->new( ... );

# For the "core" schema (see below)
$handler->prepare_install( core => 1 );
$handler->install;

# For modules
$handler->prepare_install;
my $ddl = $handler->deploy;
$handler->add_schema_version({
    ddl => $ddl,
    version => $schema->to_version
});

The original idea behind this module is that you could merge any number of schemata together to create one big one, and DH would keep track of the version of each schema. However, DH won't support that easily, so instead, you'll have to have a single "core" module, and any number of modular schemata installed into it.

The reason for this is that DH tries to install a version table for every schema and we can't avoid it. To bypass this problem we define a I schema, which contains the C table, and other schemata that don't.

When you prepare the installation files for your core schema you should tell your Dad subclass that you are doing so. This will usually only happen once ever, because once you've created your core schema's first version you're golden. This is the only time you will I a schema.

$handler->prepare_install( core => 1 );
$handler->install;

When you prepare the installation files for a module schema, you run C without that extra argument.

$handler->prepare_install;

This ensures that the first version of your module doesn't contain a C<__VERSION> SQL file, and thus it won't immediately crash when you deploy it. Speaking of deploy, you can't C this schema because DH will die. You have to C it.

$handler->deploy;

When you deploy a schema like this, DH doesn't record the version, so you have to do that yourself. You can get the DDL out of the deploy step.

my $ddl = $handler->deploy;
$handler->add_schema_version({
    ddl => $ddl,
    version => $schema->to_version
});

=head1 SEE ALSO

This module implements L and is similar to L.

=cut