lib/DBIx/Class/DeploymentHandler.pm

   1 package DBIx::Class::DeploymentHandler;
   2
   3 # ABSTRACT: Extensible DBIx::Class deployment
   4
   5 use Moose;
   6
   7 extends 'DBIx::Class::DeploymentHandler::Dad';
   8 # a single with would be better, but we can't do that
   9 # see: http://rt.cpan.org/Public/Bug/Display.html?id=46347
  10 with 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
  11     interface_role       => 'DBIx::Class::DeploymentHandler::HandlesDeploy',
  12     class_name           => 'DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator',
  13     delegate_name        => 'deploy_method',
  14     attributes_to_assume => ['schema'],
  15     attributes_to_copy   => [qw( databases upgrade_directory sql_translator_args )],
  16   },
  17   'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
  18     interface_role       => 'DBIx::Class::DeploymentHandler::HandlesVersioning',
  19     class_name           => 'DBIx::Class::DeploymentHandler::VersionHandler::Monotonic',
  20     delegate_name        => 'version_handler',
  21     attributes_to_assume => [qw( database_version schema_version to_version )],
  22   },
  23   'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
  24     interface_role       => 'DBIx::Class::DeploymentHandler::HandlesVersionStorage',
  25     class_name           => 'DBIx::Class::DeploymentHandler::VersionStorage::Standard',
  26     delegate_name        => 'version_storage',
  27     attributes_to_assume => ['schema'],
  28   };
  29 with 'DBIx::Class::DeploymentHandler::WithReasonableDefaults';
  30
  31 sub prepare_version_storage_install {
  32   my $self = shift;
  33
  34   $self->prepare_resultsource_install(
  35     $self->version_storage->version_rs->result_source
  36   );
  37 }
  38
  39 sub install_version_storage {
  40   my $self = shift;
  41
  42   $self->install_resultsource(
  43     $self->version_storage->version_rs->result_source
  44   );
  45 }
  46
  47 sub prepare_install {
  48   $_[0]->prepare_deploy;
  49   $_[0]->prepare_version_storage_install;
  50 }
  51
  52 __PACKAGE__->meta->make_immutable;
  53
  54 1;
  55
  56 #vim: ts=2 sw=2 expandtab
  57
  58 __END__
  59
  60 =head1 SYNOPSIS
  61
  62  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  63  my $s = My::Schema->connect(...);
  64
  65  my $dh = DH->new({
  66    schema              => $s,
  67    databases           => 'SQLite',
  68    sql_translator_args => { add_drop_table => 0 },
  69  });
  70
  71  $dh->prepare_install;
  72
  73  $dh->install;
  74
  75 or for upgrades:
  76
  77  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  78  my $s = My::Schema->connect(...);
  79
  80  my $dh = DH->new({
  81    schema              => $s,
  82    databases           => 'SQLite',
  83    sql_translator_args => { add_drop_table => 0 },
  84  });
  85
  86  $dh->prepare_upgrade(1, 2);
  87
  88  $dh->upgrade;
  89
  90 =head1 DESCRIPTION
  91
  92 C<DBIx::Class::DeploymentHandler> is, as it's name suggests, a tool for
  93 deploying and upgrading databases with L<DBIx::Class>.  It is designed to be
  94 much more flexible than L<DBIx::Class::Schema::Versioned>, hence the use of
  95 L<Moose> and lots of roles.
  96
  97 C<DBIx::Class::DeploymentHandler> itself is just a recommended set of roles
  98 that we think will not only work well for everyone, but will also yeild the
  99 best overall mileage.  Each role it uses has it's own nuances and
 100 documentation, so I won't describe all of them here, but here are a few of the
 101 major benefits over how L<DBIx::Class::Schema::Versioned> worked (and
 102 L<DBIx::Class::DeploymentHandler::Deprecated> tries to maintain compatibility
 103 with):
 104
 105 =over
 106
 107 =item *
 108
 109 Downgrades in addition to upgrades.
 110
 111 =item *
 112
 113 Multiple sql files files per upgrade/downgrade/install.
 114
 115 =item *
 116
 117 Perl scripts allowed for upgrade/downgrade/install.
 118
 119 =item *
 120
 121 Just one set of files needed for upgrade, unlike before where one might need
 122 to generate C<factorial(scalar @versions)>, which is just silly.
 123
 124 =item *
 125
 126 And much, much more!
 127
 128 =back
 129
 130 That's really just a taste of some of the differences.  Check out each role for
 131 all the details.
 132
 133 =head1 WHERE IS ALL THE DOC?!
 134
 135 C<DBIx::Class::DeploymentHandler> extends
 136 L<DBIx::Class::DeploymentHandler::Dad>, so that's probably the first place to
 137 look when you are trying to figure out how everything works.
 138
 139 Next would be to look at all the roles that fill in the blanks that
 140 L<DBIx::Class::DeploymentHandler::Dad> expects to be filled.  They would be
 141 L<DBIx::Class::DeploymentHandler::WithSqltDeployMethod>,
 142 L<DBIx::Class::DeploymentHandler::WithMonotonicVersions>,
 143 L<DBIx::Class::DeploymentHandler::WithStandardVersionStorage>, and
 144 L<DBIx::Class::DeploymentHandler::WithReasonableDefaults>.
 145
 146 =method prepare_version_storage_install
 147
 148  $dh->prepare_version_storage_install
 149
 150 Creates the needed C<.sql> file to install the version storage and not the rest
 151 of the tables
 152
 153 =method prepare_install
 154
 155  $dh->prepare_install
 156
 157 First prepare all the tables to be installed and the prepare just the version
 158 storage
 159
 160 =method install_version_storage
 161
 162  $dh->install_version_storage
 163
 164 Install the version storage and not the rest of the tables
 165
 166 =head1 THIS SUCKS
 167
 168 You started your project and weren't using C<DBIx::Class::DeploymentHandler>?
 169 Lucky for you I had you in mind when I wrote this doc.
 170
 171 First off, you'll want to just install the C<version_storage>:
 172
 173  my $s = My::Schema->connect(...);
 174  my $dh = DBIx::Class::DeploymentHandler({ schema => $s });
 175
 176  $dh->prepare_version_storage_install;
 177  $dh->install_version_storage;
 178
 179 Then set your database version:
 180
 181  $dh->add_database_version({ version => $s->version });
 182
 183 Now you should be able to use C<DBIx::Class::DeploymentHandler> like normal!
 184
 185 =head1 DONATIONS
 186
 187 If you'd like to thank me for the work I've done on this module, don't give me
 188 a donation. I spend a lot of free time creating free software, but I do it
 189 because I love it.
 190
 191 Instead, consider donating to someone who might actually need it.  Obviously
 192 you should do research when donating to a charity, so don't just take my word
 193 on this.  I like Children's Survival Fund:
 194 L<http://www.childrenssurvivalfund.org>, but there are a host of other
 195 charities that can do much more good than I will with your money.