Direct Answer
No, the server does not trigger re-population of existing Materialized Views during a version upgrade. An MV created in a pre-20.6 release retains its fully populated state after an in-place upgrade to 20.6 or later. The POPULATE operation runs exactly once at CREATE time and is never re-executed by a restart, version change, or target table engine modification.
Data completeness when moving from automatic to explicit backfill defaults must be verified by explicit row-count comparison between source and destination tables. There is no automatic flag or migration hook that reconciles the difference.
Version Boundary and Default Semantics
ClickHouse 20.6 (June 2020) changed the default for CREATE MATERIALIZED VIEW from POPULATE (backfill existing rows) to NO POPULATE (process only future inserts). This is a documented breaking change. MVs created before 20.6 without an explicit POPULATE clause were implicitly populated. MVs created on 20.6+ without an explicit POPULATE clause are not backfilled.
What Happens During an In-Place Upgrade
- Existing MV definitions in
system.materialized_views are preserved verbatim.
- The internal pointer that marks the source table position up to which data has been pushed remains intact.
- No
system.mutations entry is created for the destination table.
- If the destination table engine changes (e.g.,
MergeTree → ReplicatedMergeTree) via ALTER TABLE ... MODIFY ENGINE, the MV continues pushing new rows; historical data is not re-sent.
Risk Scenario: Recreating MVs During Upgrade
If your deployment automation drops and recreates MVs as part of the upgrade (common with schema migration tools), the new CREATE statement follows the target version's default. On 20.6+ that means NO POPULATE, leaving a completeness gap for all rows that existed before the recreation.
Verification Steps (Run on Each Replica)
- Confirm version:
SELECT version()
- Inspect MV population flag (21.8+):
SELECT database, name, is_populated FROM system.materialized_views WHERE name = 'your_mv'
- Compare row counts for a fixed time window:
SELECT count() FROM source_table WHERE event_date >= '2024-01-01';
SELECT count() FROM mv_destination WHERE event_date >= '2024-01-01';
- Check for pending mutations:
SELECT * FROM system.mutations WHERE table = 'mv_destination' AND is_done = 0
Rolling Upgrade Caution
In a mixed-version cluster, an MV created on a pre-20.6 node will backfill; the same statement on a 20.6+ node will not. Avoid creating new MVs until all nodes report the same major version.
One Diagnostic Detail Needed
Are your MVs managed by an external migration tool (e.g., Flyway, Liquibase, custom scripts) that drops and recreates them during the upgrade? If yes, you must add explicit POPULATE to every CREATE statement or run a manual backfill afterward.
clickhouse