lib/DBIx/Class/DeploymentHandler/Dad.pm

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