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 => [qw(schema schema_version)],
  15     attributes_to_copy   => [qw( ignore_ddl databases script_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     result_source => $self->version_storage->version_rs->result_source
  36   });
  37 }
  38
  39 sub install_version_storage {
  40   my $self = shift;
  41
  42   my $version = (shift||{})->{version} || $self->schema_version;
  43
  44   $self->install_resultsource({
  45     result_source => $self->version_storage->version_rs->result_source,
  46     version       => $version,
  47   });
  48 }
  49
  50 sub prepare_install {
  51   $_[0]->prepare_deploy;
  52   $_[0]->prepare_version_storage_install;
  53 }
  54
  55 # the following is just a hack so that ->version_storage
  56 # won't be lazy
  57 sub BUILD { $_[0]->version_storage }
  58 __PACKAGE__->meta->make_immutable;
  59
  60 1;
  61
  62 #vim: ts=2 sw=2 expandtab
  63
  64 __END__
  65
  66 =head1 SYNOPSIS
  67
  68  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  69  my $s = My::Schema->connect(...);
  70
  71  my $dh = DH->new({
  72    schema              => $s,
  73    databases           => 'SQLite',
  74    sql_translator_args => { add_drop_table => 0 },
  75  });
  76
  77  $dh->prepare_install;
  78
  79  $dh->install;
  80
  81 or for upgrades:
  82
  83  use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
  84  my $s = My::Schema->connect(...);
  85
  86  my $dh = DH->new({
  87    schema              => $s,
  88    databases           => 'SQLite',
  89    sql_translator_args => { add_drop_table => 0 },
  90  });
  91
  92  $dh->prepare_upgrade(1, 2);
  93
  94  $dh->upgrade;
  95
  96 =head1 DESCRIPTION
  97
  98 C<DBIx::Class::DeploymentHandler> is, as it's name suggests, a tool for
  99 deploying and upgrading databases with L<DBIx::Class>.  It is designed to be
 100 much more flexible than L<DBIx::Class::Schema::Versioned>, hence the use of
 101 L<Moose> and lots of roles.
 102
 103 C<DBIx::Class::DeploymentHandler> itself is just a recommended set of roles
 104 that we think will not only work well for everyone, but will also yeild the
 105 best overall mileage.  Each role it uses has it's own nuances and
 106 documentation, so I won't describe all of them here, but here are a few of the
 107 major benefits over how L<DBIx::Class::Schema::Versioned> worked (and
 108 L<DBIx::Class::DeploymentHandler::Deprecated> tries to maintain compatibility
 109 with):
 110
 111 =over
 112
 113 =item *
 114
 115 Downgrades in addition to upgrades.
 116
 117 =item *
 118
 119 Multiple sql files files per upgrade/downgrade/install.
 120
 121 =item *
 122
 123 Perl scripts allowed for upgrade/downgrade/install.
 124
 125 =item *
 126
 127 Just one set of files needed for upgrade, unlike before where one might need
 128 to generate C<factorial(scalar @versions)>, which is just silly.
 129
 130 =item *
 131
 132 And much, much more!
 133
 134 =back
 135
 136 That's really just a taste of some of the differences.  Check out each role for
 137 all the details.
 138
 139 =head1 WHERE IS ALL THE DOC?!
 140
 141 C<DBIx::Class::DeploymentHandler> extends
 142 L<DBIx::Class::DeploymentHandler::Dad>, so that's probably the first place to
 143 look when you are trying to figure out how everything works.
 144
 145 Next would be to look at all the pieces that fill in the blanks that
 146 L<DBIx::Class::DeploymentHandler::Dad> expects to be filled.  They would be
 147 L<DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator>,
 148 L<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic>,
 149 L<DBIx::Class::DeploymentHandler::VersionStorage::Standard>, and
 150 L<DBIx::Class::DeploymentHandler::WithReasonableDefaults>.
 151
 152 =method prepare_version_storage_install
 153
 154  $dh->prepare_version_storage_install
 155
 156 Creates the needed C<.sql> file to install the version storage and not the rest
 157 of the tables
 158
 159 =method prepare_install
 160
 161  $dh->prepare_install
 162
 163 First prepare all the tables to be installed and the prepare just the version
 164 storage
 165
 166 =method install_version_storage
 167
 168  $dh->install_version_storage
 169
 170 Install the version storage and not the rest of the tables
 171
 172 =head1 THIS SUCKS
 173
 174 You started your project and weren't using C<DBIx::Class::DeploymentHandler>?
 175 Lucky for you I had you in mind when I wrote this doc.
 176
 177 First off, you'll want to just install the C<version_storage>:
 178
 179  my $s = My::Schema->connect(...);
 180  my $dh = DBIx::Class::DeploymentHandler->({ schema => $s });
 181
 182  $dh->prepare_version_storage_install;
 183  $dh->install_version_storage;
 184
 185 Then set your database version:
 186
 187  $dh->add_database_version({ version => $s->version });
 188
 189 Now you should be able to use C<DBIx::Class::DeploymentHandler> like normal!
 190
 191 =head1 LOGGING
 192
 193 This is a complex tool, and because of that sometimes you'll want to see
 194 what exactly is happening.  The best way to do that is to use the built in
 195 logging functionality.  It the standard six log levels; C<fatal>, C<error>,
 196 C<warn>, C<info>, C<debug>, and C<trace>.  Most of those are pretty self
 197 explanatory.  Generally a safe level to see what all is going on is debug,
 198 which will give you everything except for the exact SQL being run.
 199
 200 To enable the various logging levels all you need to do is set an environment
 201 variables: C<DBICDH_FATAL>, C<DBICDH_ERROR>, C<DBICDH_WARN>, C<DBICDH_INFO>,
 202 C<DBICDH_DEBUG>, and C<DBICDH_TRACE>.  Each level can be set on it's own,
 203 but the default is the first three on and the last three off, and the levels
 204 cascade, so if you turn on trace the rest will turn on automatically.
 205
 206 =head1 DONATIONS
 207
 208 If you'd like to thank me for the work I've done on this module, don't give me
 209 a donation. I spend a lot of free time creating free software, but I do it
 210 because I love it.
 211
 212 Instead, consider donating to someone who might actually need it.  Obviously
 213 you should do research when donating to a charity, so don't just take my word
 214 on this.  I like Children's Survival Fund:
 215 L<http://www.childrenssurvivalfund.org>, but there are a host of other
 216 charities that can do much more good than I will with your money.