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