lib/DBIx/Class/DeploymentHandler/Dad.pm

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