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