lib/DBIx/Class/DeploymentHandler/Dad.pm

   1 package DBIx::Class::DeploymentHandler::Dad;
   2
   3 # ABSTRACT: Parent class for DeploymentHandlers
   4
   5 use Moose;
   6 require DBIx::Class::Schema;    # loaded for type constraint
   7 use Carp::Clan '^DBIx::Class::DeploymentHandler';
   8 use DBIx::Class::DeploymentHandler::Logger;
   9 use DBIx::Class::DeploymentHandler::Types;
  10 use Log::Contextual ':log', -package_logger =>
  11   DBIx::Class::DeploymentHandler::Logger->new({
  12     env_prefix => 'DBICDH'
  13   });
  14
  15 has schema => (
  16   isa      => 'DBIx::Class::Schema',
  17   is       => 'ro',
  18   required => 1,
  19 );
  20
  21 has backup_directory => (
  22   isa => 'Str',
  23   is  => 'ro',
  24   predicate  => 'has_backup_directory',
  25 );
  26
  27 has to_version => (
  28   is         => 'ro',
  29   isa        => 'Str',
  30   lazy_build => 1,
  31 );
  32
  33 sub _build_to_version { $_[0]->schema_version }
  34
  35 has schema_version => (
  36   is         => 'ro',
  37   isa        => 'StrSchemaVersion',
  38   lazy_build => 1,
  39 );
  40
  41 sub _build_schema_version { $_[0]->schema->schema_version }
  42
  43 sub install {
  44   my $self = shift;
  45
  46   my $version = (shift @_ || {})->{version} || $self->to_version;
  47   log_info { "installing version $version" };
  48   croak 'Install not possible as versions table already exists in database'
  49     if $self->version_storage_is_installed;
  50
  51   my $ddl = $self->deploy({ version=> $version });
  52
  53   $self->add_database_version({
  54     version     => $self->to_version,
  55     ddl         => $ddl,
  56   });
  57 }
  58
  59 sub upgrade {
  60   log_info { 'upgrading' };
  61   my $self = shift;
  62   my $ran_once = 0;
  63   while ( my $version_list = $self->next_version_set ) {
  64     $ran_once = 1;
  65     my ($ddl, $upgrade_sql) = @{
  66       $self->upgrade_single_step({ version_set => $version_list })
  67     ||[]};
  68
  69     $self->add_database_version({
  70       version     => $version_list->[-1],
  71       ddl         => $ddl,
  72       upgrade_sql => $upgrade_sql,
  73     });
  74   }
  75
  76   log_warn { 'no need to run upgrade' } unless $ran_once;
  77 }
  78
  79 sub downgrade {
  80   log_info { 'downgrading' };
  81   my $self = shift;
  82   my $ran_once = 0;
  83   while ( my $version_list = $self->previous_version_set ) {
  84     $ran_once = 1;
  85     $self->downgrade_single_step({ version_set => $version_list });
  86
  87     # do we just delete a row here?  I think so but not sure
  88     $self->delete_database_version({ version => $version_list->[0] });
  89   }
  90   log_warn { 'no version to run downgrade' } unless $ran_once;
  91 }
  92
  93 sub backup {
  94   my $self = shift;
  95   log_info { 'backing up' };
  96   $self->schema->storage->backup($self->backup_directory)
  97 }
  98
  99 __PACKAGE__->meta->make_immutable;
 100
 101 1;
 102
 103 # vim: ts=2 sw=2 expandtab
 104
 105 __END__
 106
 107 =pod
 108
 109 =attr schema
 110
 111 The L<DBIx::Class::Schema> (B<required>) that is used to talk to the database
 112 and generate the DDL.
 113
 114 =attr schema_version
 115
 116 The version that the schema is currently at.  Defaults to
 117 C<< $self->schema->schema_version >>.
 118
 119 =attr backup_directory
 120
 121 The directory where backups are stored
 122
 123 =attr to_version
 124
 125 The version (defaults to schema's version) to migrate the database to
 126
 127 =method install
 128
 129  $dh->install
 130
 131 or
 132
 133  $dh->install({ version => 1 })
 134
 135 Deploys the requested version into the database  Version defaults to
 136 L</schema_version>.  Populates C<version_storage> with C<version> and C<ddl>.
 137
 138 B<Note>: you typically need to call C<< $dh->prepare_deploy >> before you call
 139 this method.
 140
 141 B<Note>: you cannot install on top of an already installed database
 142
 143 =method upgrade
 144
 145  $dh->upgrade
 146
 147 Upgrades the database one step at a time till L</next_version_set>
 148 returns C<undef>.  Each upgrade step will add a C<version>, C<ddl>, and
 149 C<upgrade_sql> to the version storage (if C<ddl> and/or C<upgrade_sql> are
 150 returned from L</upgrade_single_step>.
 151
 152 =method downgrade
 153
 154  $dh->downgrade
 155
 156 Downgrades the database one step at a time till L</previous_version_set>
 157 returns C<undef>.  Each downgrade step will delete a C<version> from the
 158 version storage.
 159
 160 =method backup
 161
 162  $dh->backup
 163
 164 Simply calls backup on the C<< $schema->storage >>, passing in
 165 C<< $self->backup_directory >> as an argument.  Please test yourself before
 166 assuming it will work.
 167
 168 =head1 METHODS THAT ARE REQUIRED IN SUBCLASSES
 169
 170 =head2 deploy
 171
 172 See L<DBIx::Class::DeploymentHandler::HandlesDeploy/deploy>.
 173
 174 =head2 version_storage_is_installed
 175
 176 See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/version_storage_is_installed>.
 177
 178 =head2 add_database_version
 179
 180 See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/add_database_version>.
 181
 182 =head2 delete_database_version
 183
 184 See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/delete_database_version>.
 185
 186 =head2 next_version_set
 187
 188 See L<DBIx::Class::DeploymentHandler::HandlesVersioning/next_version_set>.
 189
 190 =head2 previous_version_set
 191
 192 See L<DBIx::Class::DeploymentHandler::HandlesVersioning/previous_version_set>.
 193
 194 =head2 upgrade_single_step
 195
 196 See L<DBIx::Class::DeploymentHandler::HandlesDeploy/upgrade_single_step>.
 197
 198 =head2 downgrade_single_step
 199
 200 See L<DBIx::Class::DeploymentHandler::HandlesDeploy/downgrade_single_step>.
 201
 202 =head1 ORTHODOX METHODS
 203
 204 These methods are not actually B<required> as things will probably still work
 205 if you don't implement them, but if you want your subclass to get along with
 206 other subclasses (or more likely, tools made to use another subclass), you
 207 should probably implement these too, even if they are no-ops.
 208
 209 =head2 database_version
 210
 211 see L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/database_version>
 212
 213 =head2 prepare_deploy
 214
 215 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_deploy>
 216
 217 =head2 prepare_resultsource_install
 218
 219 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_resultsource_install>
 220
 221 =head2 install_resultsource
 222
 223 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/install_resultsource>
 224
 225 =head2 prepare_upgrade
 226
 227 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_upgrade>
 228
 229 =head2 prepare_downgrade
 230
 231 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_downgrade>
 232
 233 =head2 SUBCLASSING
 234
 235 All of the methods mentioned in L</METHODS THAT ARE REQUIRED IN SUBCLASSES> and
 236 L</ORTHODOX METHODS> can be implemented in any fashion you choose.  In the
 237 spirit of code reuse I have used roles to implement them in my two subclasses,
 238 L<DBIx::Class::DeploymentHandler> and
 239 L<DBIx::Class::DeploymentHandler::Deprecated>, but you are free to implement
 240 them entirely in a subclass if you so choose to.
 241
 242 For in-depth documentation on how methods are supposed to work, see the roles
 243 L<DBIx::Class::DeploymentHandler::HandlesDeploy>,
 244 L<DBIx::Class::DeploymentHandler::HandlesVersioning>, and
 245 L<DBIx::Class::DeploymentHandler::HandlesVersionStorage>.
 246