/ 
DBIO-0.900004
/ DBIO::Test::Conformance::Cases::Diff

NAME

DBIO::Test::Conformance::Cases::Diff - The shared Diff cases every DBIO driver answers

VERSION

version 0.900004

DESCRIPTION

The Diff list of DBIO::Test::Conformance (ADR 0060): twenty cases, U1 to U17, U19 and U20 of the ADR's first case list with U13 as two cases, and three cases of the deploy class (table version 4), as plain Perl data. A case is two schema declarations in DBIO's own terms, from and to, the rows that are in the tables when the upgrade runs, and what must be observable on the server afterwards. It holds no SQL and no driver name.

A case is a hash:

{
  name    => 'diff-fk-dropped',                 # stable id, diff- prefix
  since   => 1,                                 # table version that added it
  cards   => [ 'dbio-mysql k94' ],              # where it came from; documentation
  subject => { source => 'Child', column => 'parent_id' },   # optional
  input   => {
    from => { sources => [ { ... }, ... ] },
    to   => { sources => [ { ... }, ... ] },
    rows => [ { source => 'Parent', values => { id => 1 } }, ... ],
  },
  expect  => [ { foreign_key_count => ... }, ... ],
}

The runner installs from, creates rows in order through the data seams, upgrades to to and checks expect against the upgraded database. The sources are written as in DBIO::Test::Conformance::Cases::DDL; a source keeps its moniker across from and to and is told apart by name. subject is the object a refusal must name (the table of source and, when given, the column); without it the first source of to. Every case is also held to the second postcondition of the ADR: after the upgrade, a diff against to is empty.

The expectation is always a property of the server, never SQL text. Where the ADR says "applied or refused" (U5, U6, U13, U15, U16; for U13 both of its cases), the case is written for the applied outcome; a driver that refuses declares that in conformance_refusals like any other refusal. The order is the order of the ADR appendix. Names never change once published; a case that turns out wrong is replaced by a new one with a higher since: the case U10 is diff-indexed-column-dropped (since 3), the Diff list is at table version 4.

The deploy cases

Three cases (since 4, diff-deploy-*) are about the deploy class of the driver and carry input.deploy, a hash with the check and, where the case needs it, unchanged, expectations that hold after the call that must not have changed anything:

diff-deploy-inherited

The deploy class inherits apply and upgrade from DBIO::Deploy::Base (the same code reference); a driver takes part through the hooks _check_before_apply and _execute_diff. Then upgrade brings the database to to.

diff-deploy-dry-run

apply($diff, dry_run => 1) returns the diff and executes nothing (unchanged). Then upgrade brings the database to to.

diff-deploy-destructive-guard

A diff that drops a table throws a DBIO::Exception naming allow_destructive before the first statement (unchanged: the table is there, the additive change did not run), and runs with allow_destructive => 1.

The runner drives them through "conformance_deploy" in DBIO::Test::Conformance; a driver without that seam answers them na.

Not in the list

U18 diff-table-with-generated-column

A generated column is declared with SQL of the engine; DBIO has no engine-neutral way to write it, so the case is a driver-local one.

the check-constraint part of U13

U13 names three changes, a unique constraint, on_delete and a check constraint. A result source has no neutral declaration for a check, so the list holds the first two, each as a case of its own: diff-constraint-changed (the unique constraint, subject Child.code) and diff-fk-action-changed (on_delete, subject Child.parent_id, since 2).

METHODS

cases

my $cases = DBIO::Test::Conformance::Cases::Diff->cases;

An arrayref of the cases. It is a deep copy: a caller cannot damage the next run's table.

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.