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