lib/DBIx/Class/DeploymentHandler/Dad.pm

   1 package DBIx::Class::DeploymentHandler::Dad;
   2
   3 use Moose;
   4 use Method::Signatures::Simple;
   5 require DBIx::Class::Schema;    # loaded for type constraint
   6 use Carp::Clan '^DBIx::Class::DeploymentHandler';
   7
   8 has schema => (
   9   isa      => 'DBIx::Class::Schema',
  10   is       => 'ro',
  11   required => 1,
  12   handles => ['schema_version'],
  13 );
  14
  15 has backup_directory => (
  16   isa => 'Str',
  17   is  => 'ro',
  18   predicate  => 'has_backup_directory',
  19 );
  20
  21 has to_version => (
  22   is         => 'ro',
  23   lazy_build => 1,
  24 );
  25
  26 sub _build_to_version { $_[0]->schema->schema_version }
  27
  28 method install {
  29   croak 'Install not possible as versions table already exists in database'
  30     if $self->version_storage_is_installed;
  31
  32   my $ddl = $self->deploy;
  33
  34   $self->add_database_version({
  35     version     => $self->to_version,
  36     ddl         => $ddl,
  37   });
  38 }
  39
  40 sub upgrade {
  41   my $self = shift;
  42   while ( my $version_list = $self->next_version_set ) {
  43     my ($ddl, $upgrade_sql) = @{$self->upgrade_single_step($version_list)||[]};
  44
  45     $self->add_database_version({
  46       version     => $version_list->[-1],
  47       ddl         => $ddl,
  48       upgrade_sql => $upgrade_sql,
  49     });
  50   }
  51 }
  52
  53 sub downgrade {
  54   my $self = shift;
  55   while ( my $version_list = $self->previous_version_set ) {
  56     $self->downgrade_single_step($version_list);
  57
  58     # do we just delete a row here?  I think so but not sure
  59     $self->delete_database_version({ version => $version_list->[-1] });
  60   }
  61 }
  62
  63 method backup { $self->storage->backup($self->backup_directory) }
  64
  65 __PACKAGE__->meta->make_immutable;
  66
  67 1;
  68
  69 =pod
  70
  71 =attr schema
  72
  73 The L<DBIx::Class::Schema> (B<required>) that is used to talk to the database
  74 and generate the DDL.
  75
  76 =attr backup_directory
  77
  78 The directory that backups are stored in
  79
  80 =attr to_version
  81
  82 The version (defaults to schema's version) to migrate the database to
  83
  84 =method install
  85
  86  $dh->install
  87
  88 Deploys the current schema into the database.  Populates C<version_storage> with
  89 C<version> and C<ddl>.
  90
  91 B<Note>: you typically need to call C<< $dh->prepare_install >> before you call
  92 this method.
  93
  94 B<Note>: you cannot install on top of an already installed database
  95
  96 =method upgrade
  97
  98  $dh->upgrade
  99
 100 Upgrades the database one step at a time till L</next_version_set>
 101 returns C<undef>.  Each upgrade step will add a C<version>, C<ddl>, and
 102 C<upgrade_sql> to the version storage (if C<ddl> and/or C<upgrade_sql> are
 103 returned from L</upgrade_single_step>.
 104
 105 =method downgrade
 106
 107  $dh->downgrade
 108
 109 Downgrades the database one step at a time till L</previous_version_set>
 110 returns C<undef>.  Each downgrade step will delete a C<version>from the
 111 version storage.
 112
 113 =method backup
 114
 115  $dh->backup
 116
 117 Simply calls backup on the C<< $schema->storage >>, passing in
 118 C<< $self->backup_directory >> as an argument.  Please test yourself before
 119 assuming it will work.
 120
 121 =head1 METHODS THAT ARE REQUIRED IN SUBCLASSES
 122
 123 =head2 version_storage_is_installed
 124
 125  warn q(I can't version this database!)
 126    unless $dh->version_storage_is_installed
 127
 128 return true iff the version storage is installed.
 129
 130 =head2 deploy
 131
 132  $dh->deploy
 133
 134 Deploy the schema to the database.
 135
 136 =head2 add_database_version
 137
 138  $dh->add_database_version({
 139    version     => '1.02',
 140    ddl         => $ddl # can be undef,
 141    upgrade_sql => $sql # can be undef,
 142  });
 143
 144 Store a new version into the version storage
 145
 146 =head2 delete_database_version
 147
 148  $dh->delete_database_version({ version => '1.02' })
 149
 150 simply deletes given database version from the version storage
 151
 152 =head2 next_version_set
 153
 154  print 'versions to install: ';
 155  while (my $vs = $dh->next_version_set) {
 156    print join q(, ), @{$vs}
 157  }
 158  print qq(\n);
 159
 160 return an arrayref describing each version that needs to be
 161 installed to upgrade to C<< $dh->to_version >>.
 162
 163 =head2 previous_version_set
 164
 165  print 'versions to uninstall: ';
 166  while (my $vs = $dh->previous_version_set) {
 167    print join q(, ), @{$vs}
 168  }
 169  print qq(\n);
 170
 171 return an arrayref describing each version that needs to be
 172 "installed" to downgrade to C<< $dh->to_version >>.
 173
 174 =head2 upgrade_single_step
 175
 176  my ($ddl, $sql) = @{$dh->upgrade_single_step($version_set)||[]}
 177
 178 call a single upgrade migration.  Takes an arrayref describing the version to
 179 upgrade to.  Optionally return an arrayref containing C<$ddl> describing
 180 version installed and C<$sql> used to get to that version.
 181
 182 =head2 downgrade_single_step
 183
 184  $dh->upgrade_single_step($version_set);
 185
 186 call a single downgrade migration.  Takes an arrayref describing the version to
 187 downgrade to.
 188
 189 __END__
 190
 191 vim: ts=2 sw=2 expandtab