/ 
DBIO-0.900004
/ DBIO::DeploymentHandler

NAME

DBIO::DeploymentHandler - Extensible DBIO deployment

VERSION

version 0.900004

SYNOPSIS

use DBIO::DeploymentHandler;

# the schema must load the version-storage component -- it registers the
# __VERSION result source that prepare_install / install rely on
{
  package My::Schema;
  use DBIO 'Schema', -pg;
  __PACKAGE__->load_components('+DBIO::DeploymentHandler::VersionStorage::Standard::Component');
  __PACKAGE__->load_namespaces;
}

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' }, { all => 1 });
      },
    },
  },
});

$dh->prepare_install;   # does nothing with the native deploy method
$dh->install;           # deploys schema, version table included, 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 the dbio_deploymenthandler_versions table (result source __VERSION).

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

ATTRIBUTES

initial_version

The version the database starts from: the database_version constructor argument, else an initial_version argument, else (computed once and cached) the current "database_version".

version_source

Name of the result source holding the version rows. Defaults to __VERSION, the source registered by DBIO::DeploymentHandler::VersionStorage::Standard::Component.

version_class

Result class of the version table. Defaults to DBIO::DeploymentHandler::VersionStorage::Standard::VersionResult.

upgrade_hooks

Hashref of { $version => { pre => $code, post => $code } } (default empty). During "upgrade", every version $v with from < $v <= to has its pre hook called before the DDL reconcile and its post hook after it, in ascending version order, each as $code->($dh, { version, from, to, phase }).

deploy_method

version_handler

version_storage

The three collaborator objects built by "new".

METHODS

new

my $dh = DBIO::DeploymentHandler->new({
  schema        => $schema,          # required
  upgrade_hooks => { ... },          # optional, see DESCRIPTION
  to_version    => 3,                # optional, default: schema_version
  version_source => '__VERSION',     # optional
  version_class  => '...',           # optional
  txn_wrap      => 1,                # optional, default 1
});

Takes a hashref or a flat list. On top of the DBIO::DeploymentHandler::Dad attributes it accepts database_version as an alias for initial_version, upgrade_hooks, version_source, version_class and txn_wrap (handed to the deploy method, see "txn_do" in DBIO::DeploymentHandler::DeployMethod::Native). Builds the three collaborators -- "deploy_method" (DBIO::DeploymentHandler::DeployMethod::Native), "version_storage" (DBIO::DeploymentHandler::VersionStorage::Standard) and "version_handler" (DBIO::DeploymentHandler::VersionHandler::Monotonic) -- and checks each against its Handles* interface, throwing if one is incomplete.

prepare_deploy

deploy

prepare_resultsource_install

install_resultsource

prepare_upgrade

txn_do

Pass straight through to the same-named method of "deploy_method". With the native deploy method deploy installs the whole schema through the driver's Deploy class, the prepare_* methods and install_resultsource do nothing, and txn_do runs its coderef in a transaction scope guard (unless txn_wrap is false).

upgrade

my $diff = $dh->upgrade;
my $diff = $dh->upgrade({ to_version => 3 });
my $diff = $dh->upgrade({ allow_destructive => 1 });

The key allow_destructive releases a diff that drops or may alter stored data ("apply" in DBIO::Deploy::Base); without it such a diff stops the upgrade before its first statement.

Brings the database from "database_version" to to_version (default: the schema version) in one shot: runs the pre hooks, lets the driver reconcile live database against the code ("deploy_method"'s upgrade), runs the post hooks, then records the new version together with the diff's SQL (if the diff can('as_sql')). Carps and returns nothing when already at the target version; throws when asked to go backwards. The body is wrapped in "txn_do" only if the storage declares transactional DDL -- see "TRANSACTIONAL UPGRADE". Returns the driver's diff object.

downgrade

Always throws: the native deploy method diffs current code against the live database and has no historical versions to go back to.

add_database_version

database_version

delete_database_version

version_storage_is_installed

Pass straight through to the same-named method of "version_storage"; see DBIO::DeploymentHandler::VersionStorage::Standard.

next_version_set

previous_version_set

Pass straight through to the same-named method of "version_handler"; see DBIO::DeploymentHandler::VersionHandler::Monotonic.

prepare_version_storage_install

Calls "prepare_resultsource_install" for the version table's result source.

install_version_storage

$dh->install_version_storage({ version => 2 });

Calls "install_resultsource" for the version table's result source, with version defaulting to the schema version.

prepare_install

Calls "prepare_deploy", then "prepare_version_storage_install".

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 and MariaDB on every version, Oracle, Sybase, Informix), where the rebuild path depends on AutoCommit=on (SQLite), or whose driver deliberately declines the capability (DB2) the wrap is skipped; see "TRANSACTIONAL DDL" in DBIO::Deploy::Base. 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.

COMPATIBILITY: VERSION TABLE RENAME

The version-storage table was renamed from its inherited upstream name dbix_class_deploymenthandler_versions to dbio_deploymenthandler_versions. This is a hard, one-way fork-rename with no automatic migration: DBIO looks only for the new name. Any database that was deployed with an older DBIO (or with DBIx::Class::DeploymentHandler) still carries the OLD table and will look unversioned to the current handler -- the connection-time check will warn that the database is unversioned, and install is not refused either, since the handler does not see the old table.

If you have such a database, rename the existing table once, by hand, before connecting with the new DBIO. The DDL differs per engine; use the form for your database:

# PostgreSQL, SQLite, Oracle, MySQL/MariaDB -- standard ALTER TABLE ... RENAME TO
ALTER TABLE dbix_class_deploymenthandler_versions
  RENAME TO dbio_deploymenthandler_versions;

# MySQL/MariaDB also accept the dedicated statement:
RENAME TABLE dbix_class_deploymenthandler_versions
  TO dbio_deploymenthandler_versions;

# IBM DB2 -- RENAME TABLE (no ALTER ... RENAME form):
RENAME TABLE dbix_class_deploymenthandler_versions
  TO dbio_deploymenthandler_versions;

# Microsoft SQL Server -- stored procedure, not DDL:
EXEC sp_rename 'dbix_class_deploymenthandler_versions',
               'dbio_deploymenthandler_versions';

# Sybase ASE -- sp_rename, same shape as SQL Server:
sp_rename 'dbix_class_deploymenthandler_versions',
          'dbio_deploymenthandler_versions';

The ALTER TABLE ... RENAME TO form is SQL-standard and is what most engines the DBIO drivers target accept (PostgreSQL, SQLite, Oracle, and MySQL/MariaDB). Engines whose syntax differs are called out above: DB2 has no ALTER ... RENAME and uses RENAME TABLE; SQL Server and Sybase ASE rename through the sp_rename stored procedure rather than DDL. For any engine not listed, consult its manual for the table-rename statement -- do not assume the ALTER TABLE form works everywhere.

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.