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