Skip to content

feat(build)!: rename maintained models to dynamic and close their hold gaps - #1594

Merged
kvlonge merged 2 commits into
mainfrom
fix/dynamic-model-bugs
Nov 19, 2026
Merged

kvlonge merged 2 commits into
mainfrom
fix/dynamic-model-bugs

Conversation

@kvlonge

@kvlonge kvlonge commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Why

Maintained models shipped with known gaps: two builds creating the same model could both hold it, a failed close hid A718, a late-committing pause could let two builds run together, a snapshot full rebuild dropped change tracking, and writing out the default refresh_mode recreated the model. The kind is also renamed to dynamic before more projects adopt it.

Changes

  • after_create runs the same earliest-hold check as acquire. A build that backs out after suspending a model it created resumes it at its end when no other build holds it. A failed close is reported inside A718.
  • A build also backs out for a rival that paused within its own insert's duration, or when a takeover closed its pause first. Two builds starting at once can both stop with A718; neither builds alongside the other.
  • A snapshot's first build and full rebuild turn change tracking on when a dynamic model reads it.
  • The planner's change check drops the default refresh_mode; stored-status hashes are unchanged.
  • Breaking, own commit: materialized dynamic, [dynamic], pause_dynamic, --ignore-dynamic-grace, _sqlbuild_dynamic_pauses, plan wording, errors, the Dynamic models page. No aliases. Each existing model is recreated once on upgrade; the old pause table is no longer read.

Residual risk: after a create race, the backed-out build leaves the model suspended and unheld until it ends. No DuckShop case: dynamic models build only on Snowflake.

Verification

  • Each fix has a test that failed first.
  • Live Snowflake: snapshot rebuild tracks changes; refresh_mode incremental add/remove kept the table; a 0.251.0 project upgraded with one recreate, then kept.
  • fensu, cargo and targeted pytest, make test, make check-ci; one review plus follow-up.

…duals

- A model created during a build now runs the same earliest-hold check as
  acquire once its pause is recorded, so two builds creating the same model
  no longer both hold it. Our create made the model active, so it is
  suspended either way; the build holding it resumes it at its end, and a
  build that backed out resumes it itself at its end when no other build
  holds it, so a model never stays suspended after both back out.
- When the losing build cannot close its own pause, the A718 error now names
  that failure too instead of being replaced by it.
- Pauses are ordered by the warehouse clock when each insert starts, but an
  insert commits later. A build now also backs out for a rival that paused
  within the time its own insert took, since that rival may have read the
  table before our pause committed, and when a takeover closed its pause
  before it read the table back. Two builds that start at the same moment
  can both stop with A718; neither builds alongside the other.
- A snapshot's first build and full rebuild turn change tracking on when a
  maintained model reads it, as table builds already do (new optional
  render_track_changes adapter method; Snowflake runs ALTER TABLE ... SET
  CHANGE_TRACKING = TRUE).
- The planner's change check drops refresh_mode when it is the default, on
  both the recorded and the current side, so writing out or removing the
  default no longer recreates the model. Stored-status hashes are unchanged.
The model kind is now called dynamic everywhere: `materialized dynamic`, the
`[dynamic]` project section (still `heartbeat_grace` and
`allow_ignore_grace`), the `pause_dynamic` target setting, the
`--ignore-dynamic-grace` build flag, the `_sqlbuild_dynamic_pauses` state
table, plan actions and wording, error text, the Dynamic models docs page
and the tests. Error codes are unchanged.

BREAKING CHANGE: `materialized maintained`, `[maintained]`,
`pause_maintained` and `--ignore-maintained-grace` are no longer accepted;
use `materialized dynamic`, `[dynamic]`, `pause_dynamic` and
`--ignore-dynamic-grace`. The materialization is part of a model's version
identity, so each existing model is recreated once, with a full recompute,
by its first build after the rename. Builds record pauses in
`_sqlbuild_dynamic_pauses` and no longer read `_sqlbuild_maintained_pauses`:
let builds on the previous version finish before upgrading, resume by hand
any model a killed older build left suspended, then drop the old table.
@kvlonge
kvlonge enabled auto-merge November 19, 2026 08:51
@kvlonge
kvlonge added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit 1ccf4d9 Nov 19, 2026
35 checks passed
@kvlonge
kvlonge deleted the fix/dynamic-model-bugs branch November 19, 2026 09:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant