/ 
DBIO-ClickHouse-0.900004
/ DBIO::ClickHouse::Diff::View

NAME

DBIO::ClickHouse::Diff::View - Diff operations for ClickHouse views

VERSION

version 0.900004

DESCRIPTION

The view operations the upgrade knows, against the views the schema declares:

  • CREATE VIEW for a declared view the live database lacks;

  • CREATE OR REPLACE VIEW for a declared view whose live definition differs (core case diff-view-definition-changed);

  • DROP VIEW for a live view the schema no longer declares (core case diff-view-dropped). A view holds no data, so there is no opt-in.

The declared views are the schema's own ("declared_views" in DBIO::ClickHouse::DDL, the selection install_ddl uses) and the statements are rendered by DBIO::ClickHouse::DDL::Emit, the functions the install DDL uses. Without declared views (the declared_views argument of the diff is missing) the diff has no opinion about views and produces none.

The order

A view is created or replaced after the views its SELECT reads, and dropped before them (the reverse order); among views that read each other not at all, by name. The order comes from the text of the definitions, the declared ones for create and replace, the live ones for drop; the limits of that reading, and the refusal of a cycle (before any statement), are those of "view_order" in DBIO::ClickHouse::DDL.

What "differs" means

The two sides are compared as the server holds them: the live view's SELECT as read from system.tables.create_table_query (DBIO::ClickHouse::Introspect::Tables, definition), and the view of the target model, which DBIO::ClickHouse::Deploy builds by installing the schema into a scratch database and reading it back the same way. ClickHouse reformats a view's SELECT on creation (quotes dropped, tables qualified with their database), so the raw declared text would never equal what is stored. Both texts are therefore normalised before comparing: the database name in front of a table, the quoting marks and the white space do not count. A target without a definition (a hand-built model) is compared by the declared text, normalised the same way; a live view whose definition is unknown is never replaced on a guess.

Materialized views are refused

A materialized view holds data (its own table, filled by every insert). The statements above would delete or rebuild that data, so a live materialized view (or live or window view) that the schema does not declare, or declares as a plain view, ends the diff with a DBIO::Exception naming it and the way out, raised while the operation list is built -- before any statement of the plan runs.

This includes one created by hand and never declared: it blocks upgrade (the refusal is deliberate, not a defect) until it is declared or dropped by hand.

METHODS

diff

my @ops = DBIO::ClickHouse::Diff::View->diff(
    $source_tables, $declared_views, $storage, $target_tables,
);

$source_tables is the live model's tables section (views included), $declared_views is { name => $select_sql }, $target_tables the desired model's. Returns the drop operations, then the create and replace operations, each in the order of "The order". Throws for a materialized view as above.

as_sql

CREATE VIEW `name` AS ...; for a create (with IF NOT EXISTS when the storage declares the capability, exactly as the table ops do), CREATE OR REPLACE VIEW `name` AS ...; for a replace and DROP VIEW `name`; (with IF EXISTS under the same capability) for a drop.

summary

One line naming the view that is created (+), replaced (~) or dropped (-).

SEE ALSO

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.