/ 
DBIO-0.900001
/ DBIO::DeploymentHandler

NAME

DBIO::DeploymentHandler - Extensible DBIO deployment

VERSION

version 0.900001

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 t/deployment_handler.t for a runnable example.

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 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.) upgrade_hooks provides per-version pre and post callbacks that fire around the DDL apply, in ascending version order, for every version step that is being crossed. pre hooks see the old schema, post hooks see the new one.

Schema version is tracked in a __VERSION table.

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

TRANSACTIONAL UPGRADE

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

On engines where DDL forces an implicit COMMIT (MySQL pre-8.0 without transactional DDL, Oracle, DB2, Sybase, Informix) or where the rebuild path depends on AutoCommit=on (SQLite) the wrap is skipped -- the engine cannot honour it. In that case the __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 carp_once is emitted at the first non-transactional upgrade naming this storage class.

AUTHOR

DBIO & DBIx::Class Authors

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.