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