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::LogImporter ':log';
   9 use DBIx::Class::DeploymentHandler::Types;
  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   lazy_build => 1,
  26 );
  27
  28 sub _build_to_version { $_[0]->schema_version }
  29
  30 has schema_version => (
  31   is         => 'ro',
  32   isa        => 'StrSchemaVersion',
  33   lazy_build => 1,
  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 __PACKAGE__->meta->make_immutable;
 101
 102 1;
 103
 104 # vim: ts=2 sw=2 expandtab
 105
 106 __END__
 107
 108 =pod
 109
 110 =attr schema
 111
 112 The L<DBIx::Class::Schema> (B<required>) that is used to talk to the database
 113 and generate the DDL.
 114
 115 =attr schema_version
 116
 117 The version that the schema is currently at.  Defaults to
 118 C<< $self->schema->schema_version >>.
 119
 120 =attr backup_directory
 121
 122 The directory where backups are stored
 123
 124 =attr to_version
 125
 126 The version (defaults to schema's version) to migrate the database to
 127
 128 =method install
 129
 130  $dh->install
 131
 132 or
 133
 134  $dh->install({ version => 1 })
 135
 136 Deploys the requested version into the database  Version defaults to
 137 L</schema_version>.  Populates C<version_storage> with C<version> and C<ddl>.
 138
 139 B<Note>: you typically need to call C<< $dh->prepare_deploy >> before you call
 140 this method.
 141
 142 B<Note>: you cannot install on top of an already installed database
 143
 144 =method upgrade
 145
 146  $dh->upgrade
 147
 148 Upgrades the database one step at a time till L</next_version_set>
 149 returns C<undef>.  Each upgrade step will add a C<version>, C<ddl>, and
 150 C<upgrade_sql> to the version storage (if C<ddl> and/or C<upgrade_sql> are
 151 returned from L</upgrade_single_step>.
 152
 153 =method downgrade
 154
 155  $dh->downgrade
 156
 157 Downgrades the database one step at a time till L</previous_version_set>
 158 returns C<undef>.  Each downgrade step will delete a C<version> from the
 159 version storage.
 160
 161 =method backup
 162
 163  $dh->backup
 164
 165 Simply calls backup on the C<< $schema->storage >>, passing in
 166 C<< $self->backup_directory >> as an argument.  Please test yourself before
 167 assuming it will work.
 168
 169 =head1 METHODS THAT ARE REQUIRED IN SUBCLASSES
 170
 171 =head2 deploy
 172
 173 See L<DBIx::Class::DeploymentHandler::HandlesDeploy/deploy>.
 174
 175 =head2 version_storage_is_installed
 176
 177 See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/version_storage_is_installed>.
 178
 179 =head2 add_database_version
 180
 181 See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/add_database_version>.
 182
 183 =head2 delete_database_version
 184
 185 See L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/delete_database_version>.
 186
 187 =head2 next_version_set
 188
 189 See L<DBIx::Class::DeploymentHandler::HandlesVersioning/next_version_set>.
 190
 191 =head2 previous_version_set
 192
 193 See L<DBIx::Class::DeploymentHandler::HandlesVersioning/previous_version_set>.
 194
 195 =head2 upgrade_single_step
 196
 197 See L<DBIx::Class::DeploymentHandler::HandlesDeploy/upgrade_single_step>.
 198
 199 =head2 downgrade_single_step
 200
 201 See L<DBIx::Class::DeploymentHandler::HandlesDeploy/downgrade_single_step>.
 202
 203 =head2 txn_do
 204
 205 See L<DBIx::Class::DeploymentHandler::HandlesDeploy/txn_do>.
 206
 207 =head1 ORTHODOX METHODS
 208
 209 These methods are not actually B<required> as things will probably still work
 210 if you don't implement them, but if you want your subclass to get along with
 211 other subclasses (or more likely, tools made to use another subclass), you
 212 should probably implement these too, even if they are no-ops.
 213
 214 =head2 database_version
 215
 216 see L<DBIx::Class::DeploymentHandler::HandlesVersionStorage/database_version>
 217
 218 =head2 prepare_deploy
 219
 220 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_deploy>
 221
 222 =head2 prepare_resultsource_install
 223
 224 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_resultsource_install>
 225
 226 =head2 install_resultsource
 227
 228 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/install_resultsource>
 229
 230 =head2 prepare_upgrade
 231
 232 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_upgrade>
 233
 234 =head2 prepare_downgrade
 235
 236 see L<DBIx::Class::DeploymentHandler::HandlesDeploy/prepare_downgrade>
 237
 238 =head2 SUBCLASSING
 239
 240 All of the methods mentioned in L</METHODS THAT ARE REQUIRED IN SUBCLASSES> and
 241 L</ORTHODOX METHODS> can be implemented in any fashion you choose.  In the
 242 spirit of code reuse I have used roles to implement them in my two subclasses,
 243 L<DBIx::Class::DeploymentHandler> and
 244 L<DBIx::Class::DeploymentHandler::Deprecated>, but you are free to implement
 245 them entirely in a subclass if you so choose to.
 246
 247 For in-depth documentation on how methods are supposed to work, see the roles
 248 L<DBIx::Class::DeploymentHandler::HandlesDeploy>,
 249 L<DBIx::Class::DeploymentHandler::HandlesVersioning>, and
 250 L<DBIx::Class::DeploymentHandler::HandlesVersionStorage>.
 251