view release on metacpan or  search on metacpan

lib/DBIO/DeploymentHandler.pm  view on Meta::CPAN

  $_[0]->prepare_deploy;
  $_[0]->prepare_version_storage_install;
}

1;

# vim: ts=2 sw=2 expandtab

__END__

=pod

=encoding UTF-8

=head1 NAME

DBIO::DeploymentHandler - Extensible DBIO deployment

=head1 VERSION

version 0.900002

=head1 SYNOPSIS

  use DBIO::DeploymentHandler;
  my $s = My::Schema->connect(...);

  my $dh = DBIO::DeploymentHandler->new({
    schema => $s,
    upgrade_hooks => {
      2 => {
        post => sub {
          my ($dh, $info) = @_;
          # backfill new column on the now-current schema
          $dh->schema->resultset('User')->update({ status => 'active' });
        },
      },
    },
  });

  $dh->prepare_install;   # sets up __VERSION table
  $dh->install;           # deploys schema via native driver

  # later:
  $dh->upgrade;           # one-shot reconcile + run hooks for skipped versions

See F<t/deployment_handler.t> for a runnable example.

=head1 DESCRIPTION

DBIO::DeploymentHandler provides schema deployment and version management
using the native DBIO driver deploy system (no SQL::Translator needed).

The driver computes the diff between live database and current code in one
shot, so this handler does not loop over discrete version transitions the
way L<DBIx::Class::DeploymentHandler> does. The DDL part of an upgrade is
always a single reconcile.

For data migrations that the DDL diff cannot express (column backfills,
value normalisation, etc.) C<upgrade_hooks> provides per-version C<pre>
and C<post> callbacks that fire around the DDL apply, in ascending version
order, for every version step that is being crossed. C<pre> hooks see the
old schema, C<post> hooks see the new one.

Schema version is tracked in a C<__VERSION> table.

This is a port of L<DBIx::Class::DeploymentHandler> adapted for DBIO's
native driver architecture.

=head1 TRANSACTIONAL UPGRADE

L</upgrade> wraps the hook + DDL + version-bump body in
C<< $self->txn_do >> when the underlying storage reports
C<< _use_transactional_ddl >> truthy (see L<DBIO::Storage::DBI::Capabilities>).
A failure anywhere in the body rolls back both the DDL and the C<__VERSION>
row write.

On engines where DDL forces an implicit C<COMMIT> (MySQL pre-8.0 without
transactional DDL, Oracle, DB2, Sybase, Informix) or where the rebuild path
depends on C<AutoCommit=on> (SQLite) the wrap is skipped -- the engine
cannot honour it. In that case the C<__VERSION> row write is the
forward-progress gate: a partially applied upgrade can be re-run, the diff
re-computes against live state, and the next apply picks up the remainder.
A C<carp_once> is emitted at the first non-transactional upgrade naming
this storage class.

=head1 AUTHOR

DBIO & DBIx::Class Authors

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors
Portions Copyright (C) 2005-2025 DBIx::Class Authors
Based on DBIx::Class, heavily modified.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut