NAME

DBIO::SQLite::Diff::Table - Diff operations for SQLite tables

VERSION

version 0.900007

DESCRIPTION

Represents a table-level diff operation in SQLite: CREATE TABLE or DROP TABLE. Unlike PostgreSQL, where the table shell can be created empty and columns added one at a time, SQLite wants the full table definition at once -- most of what makes a table (a rowid alias, UNIQUE, CHECK, WITHOUT ROWID, STRICT, generated columns) cannot be added to it afterwards at all.

So a create emits the statement the target table was created with: the sql of sqlite_master, which DBIO::SQLite::Introspect::Tables puts into the model and DBIO::SQLite::Diff::Rebuild has always reused for the same reason (ADR 0003). An introspected model cannot be turned back into that statement. PRAGMA table_xinfo reports id INTEGER PRIMARY KEY as the type INTEGER, a UNIQUE constraint shows up only as an automatic index, and a CHECK or a column's COLLATE not at all -- a table rebuilt from the columns loses them without a word.

Only a model that has no statement is rebuilt from its columns: the one "target_from_compiled" in DBIO::SQLite::Diff produces, which has no database behind it. See "as_sql" for what that rebuild carries.

A virtual table (CREATE VIRTUAL TABLE) is created and dropped by the same two ops: its create is its stored statement, and DROP TABLE is how SQLite removes one. A view is not a table and never comes here (DBIO::SQLite::Diff::View).

Changes that are refused

A third action, refuse, stands for a change of a table that no statement of this driver carries out. DBIO::SQLite::Diff emits it for a virtual table that both models have and that is not the same in them: its definition differs, or it is a virtual table in one model and a plain one in the other. SQLite cannot alter a virtual table (virtual tables may not be altered), and the rebuild that brings a plain table to a new shape would copy what SELECT shows of it and lose whatever else its module stores.

"as_sql" of such an op throws, in one line that names the table and the "reason"; "summary" still lists it. That is the way of "Changes that are refused" in DBIO::SQLite::Diff::Column, and it has the same consequence: the diff reports the change, as_sql of the whole diff throws, and "apply" in DBIO::SQLite::Deploy throws before it has run a statement.

ATTRIBUTES

unique_constraints

For a create op: the column lists of the target table's UNIQUE constraints, an arrayref of arrayrefs, each in the order of the constraint's columns, sorted and without duplicates. as_sql writes them for a model that has no sql.

reason

For a refuse op: what differs and why it cannot be carried out, as the exception and the summary say it.

METHODS

diff

my @ops = DBIO::SQLite::Diff::Table->diff(
    $source_tables, $target_tables,
    $target_columns, $target_fks, $target_indexes,
);

Compares two table hashrefs (keyed by table name) and returns create ops for tables present only in target and drop ops for tables only in source. create ops capture the target table entry (with its sql, if the model has one) and the target columns, FKs and UNIQUE column lists (from the indexes of origin u), which as_sql falls back to without it.

as_sql

Returns the SQL for this operation. For drop, emits DROP TABLE. Every name the op writes itself is quoted ("quote_identifier" in DBIO::SQLite::Util): DROP TABLE "item";.

For refuse it throws ("Changes that are refused"):

Cannot change table docs: its definition as a virtual table differs
from the target's, and SQLite cannot alter a virtual table -- ...

For create there are two cases:

  • The target table entry has sql (every introspected model, so every DBIO::SQLite::Deploy upgrade): that statement is returned as it is, with a terminating semicolon. Whatever sqlite_master holds for the name comes out, so a virtual table new in the target is emitted as its CREATE VIRTUAL TABLE.

  • It has none ("target_from_compiled" in DBIO::SQLite::Diff, or a model built by hand): a CREATE TABLE is rebuilt from the columns. It carries each column's type, NOT NULL and DEFAULT (an expression default in parentheses, see "default_value_sql" in DBIO::SQLite::Util), the primary key -- on the column for a single-column key, which makes an INTEGER one the rowid alias, as a table constraint for several columns, in the order of the key (pk_position; columns that have none keep their column order) -- and the model's UNIQUE constraints as UNIQUE (...) table constraints, read from the table's indexes of origin u, one per set of columns, and its foreign keys as FOREIGN KEY (...) REFERENCES ....

    It does not carry ON DELETE / ON UPDATE, CHECK, COLLATE, AUTOINCREMENT, WITHOUT ROWID, STRICT or generated columns. A compiled model has neither indexes nor foreign keys (the core's model compiler yields none), so a table created from one has no UNIQUE and no foreign key: it is usable, but it is not the table DBIO::SQLite::DDL creates for the same result class.

summary

+ table: name or - table: name; for a refuse op ! table: name (refused: reason). It never throws.

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.