Skip to content

sql: accept WITH (WAIT ...) on ALTER CLUSTER unconditionally - #38104

Open
aljoscha wants to merge 1 commit into
aljoscha/cluster-legacy-03-staged-machinefrom
aljoscha/cluster-legacy-04-zdt-flag
Open

sql: accept WITH (WAIT ...) on ALTER CLUSTER unconditionally#38104
aljoscha wants to merge 1 commit into
aljoscha/cluster-legacy-03-staged-machinefrom
aljoscha/cluster-legacy-04-zdt-flag

Conversation

@aljoscha

@aljoscha aljoscha commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Part 4 of the design stack. Stacked on #38103.

Why

Graceful cluster reconfiguration has lived behind
enable_zero_downtime_cluster_reconfiguration, default off, so the planner
rejected any WITH (WAIT ...) clause unless a deployment turned the flag on.

That flag is now the only thing standing between an operator and the synchronous
cut-over (#38103), which is the escape hatch for reshaping a cluster when the
cluster controller itself is the problem. On any deployment running the compiled
default there would be no way to reshape a cluster at all in that situation. A
break-glass path behind a default-off flag is not a break-glass path.

What lands

  • The feature_flags! entry and the require_feature_flag call in
    plan_alter_cluster. Everything else about the flag is macro-derived, so
    there is no second registry to update.
  • Every test that used the surface enabled the flag itself, so those
    ALTER SYSTEM SET/RESET statements go (testdrive, sqllogictest, pg-cdc,
    test/cluster/mzcompose.py, cloudtest, parallel-workload, and the
    graceful-reconfiguration platform check).
  • get_minimal_system_parameters pins the flag on below v26.38 instead. This is
    load-bearing, not tidiness: AlterClusterGracefulReconfiguration issues
    WITH (WAIT UNTIL READY ...) in its first manipulate phase, which under
    UpgradeEntireMz runs against the last released binary, and that binary still
    enforces the gate.
  • The launchdarkly-flag-consistency allowlist entry moves from
    INTENTIONAL_LD_OVERRIDES to KNOWN_STALE_LD_FLAGS. The flag is a real LD
    flag, so once the last release carrying it ages out the consistency check
    would report it stale and fail. The flag should be archived in
    LaunchDarkly
    , after which this entry can go too.

The two rejections that share the removed code path are untouched: a WAIT
without a replica-shape change (WAIT can only be used together with a SIZE, AVAILABILITY ZONES, or INTROSPECTION change) and a WAIT on an unmanaged
cluster (ALTER... WITH not supported for unmanaged clusters). No test asserted
the gate's own error text, so nothing there changes.

enable_cluster_schedule_refresh is deliberately left alone at its current
default, even though it is the near-identical sibling gate a dozen lines below.

Reviewer attention, please

Two judgment calls worth a second opinion:

  1. The private-preview badges in doc/user/content/sql/alter-cluster.md are
    removed.
    Nothing gates the surface after this, so describing it as private
    preview is no longer accurate. If the preview status is a product decision
    that has not been made yet, revert just that file and the rest still stands.
  2. No release-note entry. doc/user/content/releases/_index.md is organized
    by released version with release dates, and v26.38 has no section yet, so
    there is nowhere to put one without inventing a date. Whoever writes the
    v26.38 notes should announce that WITH (WAIT ...) is generally available.

@aljoscha
aljoscha force-pushed the aljoscha/cluster-legacy-04-zdt-flag branch from b3e6c5d to 44e8e16 Compare August 7, 2026 08:00
@aljoscha
aljoscha force-pushed the aljoscha/cluster-legacy-04-zdt-flag branch from 44e8e16 to e06b9d6 Compare August 7, 2026 08:01
@aljoscha
aljoscha marked this pull request as ready for review August 7, 2026 08:14
@aljoscha
aljoscha requested review from a team as code owners August 7, 2026 08:14
@aljoscha
aljoscha force-pushed the aljoscha/cluster-legacy-04-zdt-flag branch from e06b9d6 to 8f88cec Compare August 7, 2026 08:28
@aljoscha
aljoscha force-pushed the aljoscha/cluster-legacy-04-zdt-flag branch from 8f88cec to f1f08b2 Compare August 7, 2026 08:45
Graceful cluster reconfiguration has been behind the
`enable_zero_downtime_cluster_reconfiguration` feature flag, default off, so the
`WITH (WAIT ...)` surface was rejected at plan time unless a deployment turned
it on. That is now the only thing standing between an operator and the
synchronous cut-over, which is the escape hatch for a reshape when the cluster
controller itself is the problem. A break-glass path behind a default-off flag
is not a break-glass path.

Remove the flag and the planner gate. The two rejections that share that code
path stay: a `WAIT` without a replica-shape change, and a `WAIT` on an
unmanaged cluster.

Every test that used the surface enabled the flag itself, so those statements
go. In a mixed-version run some phases execute against a released binary that
still enforces the gate (platform-checks' graceful-reconfiguration check runs
its first manipulate phase there), so `get_minimal_system_parameters` pins the
flag on below v26.38 instead.

The docs drop the private-preview badges: the surface is generally available
once nothing gates it.
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