NAME

DBIO::DuckDB::Diff - Compare two introspected DuckDB models

VERSION

version 0.900007

DESCRIPTION

DBIO::DuckDB::Diff compares two introspected DuckDB models (produced by DBIO::DuckDB::Introspect) and emits a list of structured diff operations that can be rendered to SQL or a human-readable summary.

my $diff = DBIO::DuckDB::Diff->new(
    source => $current_model,
    target => $desired_model,
);

if ($diff->has_changes) {
    print $diff->as_sql;
    print $diff->summary;
}

Operations are emitted in dependency order: views that go, tables, then columns, then indexes, then views that are new. Drops come last for each layer. A view is created and dropped as a view (DBIO::DuckDB::Diff::View); it is never diffed as a table.

DuckDB enforces foreign keys, so the install DDL writes them and a table the diff creates brings its keys, after the tables they point to (a table is dropped before those).

What ALTER TABLE cannot do, the diff does by rebuilding the table (DBIO::DuckDB::Diff::Rebuild, docs/adr/0010-tables-are-rebuilt-for-what-alter-cannot-do.md): a column dropped while an index or a UNIQUE constraint stands on it or on a later column, a UNIQUE constraint that goes, a foreign key that is added or dropped (there is no ALTER TABLE ... ADD FOREIGN KEY in DuckDB), and a UNIQUE constraint a foreign key of the target needs (DuckDB takes a key to a constraint only, not to a unique index). The column and index operations of such a table are replaced by one rebuild and the creation of its target indexes; creates and rebuilds come in one order, the table a key points to first, whether it is created or rebuilt.

METHODS

rebuild_reasons

my $reasons = $diff->rebuild_reasons;   # { $table => [ 'reason', ... ] }

The tables of both models that have to be rebuilt, each with what makes it so (DBIO::DuckDB::Diff::Rebuild):

  • a column that goes while an index or a UNIQUE constraint stands on it or on a later column of the table;

  • a UNIQUE constraint the target lacks ("unique_constraint_changes");

  • a foreign key added or dropped, compared by columns, parent table, parent columns and actions (the constraint name is not part of it);

  • a UNIQUE constraint of the target that a foreign key of the target points to, while the source table has it neither as a constraint nor as its PRIMARY KEY (it may have a unique index, which DuckDB does not take for a key).

unique_constraint_changes

my ($added, $dropped) = $diff->unique_constraint_changes;

The UNIQUE constraints of tables that exist on both sides, compared by their column tuple in order: $added are the ones the target has and the source has neither as a constraint nor as a unique index, $dropped the ones the source has as a constraint and the target has neither as a constraint nor as a unique index. Each is a list of [ $table, $name, \@columns ]. A dropped one makes the table a rebuild ("rebuild_reasons"): DuckDB cannot drop a constraint.

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

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