test: add e2e schema-upgrade test for two-phase extension migration by WentingWu666666 · Pull Request #426 · documentdb/documentdb-kubernetes-operator

WentingWu666666 · 2026-07-16T16:18:02Z

What

Adds a new e2e upgrade spec — test/e2e/tests/upgrade/upgrade_schema_test.go — that covers the two-phase extension schema upgrade (the irreversible ALTER EXTENSION documentdb UPDATE migration) that the existing image-only upgrade spec (upgrade_images_test.go) deliberately does not exercise.

Why

Today we cannot gate a bump of the default DocumentDB version on schema-migration safety — there is no e2e coverage of the extension schema upgrade path. This showed up while preparing the operator 0.3.0 release: the database version bump was deferred because we had no way to prove the schema migration is safe. This test closes that gap.

Approach

Drives the upgrade through the user-facing knobs — spec.documentDBVersion (which sets the extension + gateway images together) and spec.schemaVersion — rather than raw spec.image.* overrides, mirroring how a real user bumps a version. A new mixin manifests/mixins/documentdb_version.yaml.template pins the version at create time.

Flow (per the two-phase contract documented on spec.schemaVersion):

Create at the old version with schemaVersion unset (two-phase) and seed data → status.schemaVersion settles on the old semver.
Bump spec.documentDBVersion to the new version → pods roll (status.documentDBImage advances), but schema must stay at the old version (no auto ALTER EXTENSION), seeded data retained. Held with Consistently so a stray auto-migration fails.
Set spec.schemaVersion to the new version → operator runs ALTER EXTENSION UPDATE, status.schemaVersion advances, seeded data still retained.

Runs on every e2e PR

Lives in the existing upgrade matrix row, which already sets E2E_UPGRADE=1 on PRs.
Gated at High level (SkipUnlessLevel(High)), which runs at the PR default depth (Medium).
Old/new versions default to 0.109.0 → 0.110.0 (public GHCR images) so the spec runs without depending on repo CI vars. Overridable via E2E_UPGRADE_OLD_DOCUMENTDB_VERSION / E2E_UPGRADE_NEW_DOCUMENTDB_VERSION.

Status

Draft — not yet run end-to-end against a live cluster (compiles/vets clean). Opening for early review of the approach and assertions.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

documentdb-triage-tool · 2026-07-16T17:40:48Z

🤖 Auto-triaged by documentdb-triage-tool.

Applied: test, CI/CD, documentation, enhancement
Project fields suggested: Component test · Priority P2 · Effort M · Status In Progress
Confidence: 0.88 (mixed)

Reasoning

component from path globs (test, ci, docs); effort from diff stats (275+0 LOC, 5 files); LLM: Adds a new e2e test file covering the two-phase extension schema upgrade path, directly addressing a release-blocking gap (0.3.0 version bump deferred due to missing coverage), scoped to the test component within one upgrade suite.

If a label is wrong, remove it manually and ping @patty-chow so the rules can be tuned. The bot will not re-label items that already have component labels.

Add a High-level, disruptive upgrade spec that gates the safety of bumping the default DocumentDB version. It exercises the irreversible extension schema migration (ALTER EXTENSION documentdb UPDATE) that the image-only upgrade spec deliberately does not cover. The spec drives the upgrade through the user-facing knobs — spec.documentDBVersion (which sets the extension + gateway images together) and spec.schemaVersion — rather than raw spec.image.* overrides, mirroring how an operator user actually bumps a version: 1. create at the old version with schemaVersion unset and seed data; status.schemaVersion settles on the old semver 2. bump spec.documentDBVersion to the new version; pods roll but the schema must stay at the old version (no auto ALTER EXTENSION) and seeded data is retained 3. finalize by setting spec.schemaVersion; the operator runs ALTER EXTENSION UPDATE, status.schemaVersion advances and seeded data is still retained The old/new versions default to the last-released pair (0.109.0 → 0.110.0) so the spec runs on every e2e PR via the existing `upgrade` matrix row (E2E_UPGRADE=1, Medium depth); admins may override via E2E_UPGRADE_OLD/NEW_DOCUMENTDB_VERSION repo vars. A new manifests/mixins/documentdb_version.yaml.template pins the version at create time. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b8370a70-9c47-476c-8d6e-b9a75a8ced64 Signed-off-by: Wenting Wu <wentingwu@microsoft.com>

Copilot

Pull request overview

Adds an end-to-end upgrade spec that exercises the two-phase DocumentDB extension schema migration path (the irreversible ALTER EXTENSION ... UPDATE) using the user-facing spec.documentDBVersion + spec.schemaVersion knobs, closing a gap left by the existing image-only upgrade coverage.

Changes:

Add a new upgrade e2e spec (upgrade_schema_test.go) that verifies: binary upgrade does not auto-migrate schema in two-phase mode, then explicit finalization migrates schema while retaining seeded data.
Add a manifests mixin to pin spec.documentDBVersion at creation time, plus new env vars/defaults to control the old/new version pair.
Wire the new env vars into CI and document them in the e2e README.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`test/e2e/tests/upgrade/upgrade_schema_test.go`	New e2e spec covering two-phase schema migration and data retention across binary + schema upgrade steps.
`test/e2e/tests/upgrade/helpers_test.go`	Adds env var knobs and defaults for old/new DocumentDB versions used by the schema-upgrade spec.
`test/e2e/README.md`	Documents the new schema-upgrade env vars and their defaults.
`test/e2e/manifests/mixins/documentdb_version.yaml.template`	New mixin to set `spec.documentDBVersion` via rendered manifests at create time.
`.github/workflows/test-e2e.yml`	Sets version env vars so the schema-upgrade spec runs consistently in CI.

+func schemaVersionGetter(ctx context.Context, c client.Client, key types.NamespacedName) func() string {
+	return func() string {
+		dd, err := shareddb.Get(ctx, c, key)
+		if err != nil {
+			return ""
+		}
+		return dd.Status.SchemaVersion
+	}
+}


+			key := types.NamespacedName{Namespace: ns, Name: ddName}
+			Eventually(assertions.AssertDocumentDBReady(ctx, c, key),
+				timeouts.For(timeouts.DocumentDBReady),
+				timeouts.PollInterval(timeouts.DocumentDBReady),
+			).Should(Succeed(), "DocumentDB did not reach Ready on oldVersion=%s", oldVersion)
+
+			By("waiting for status.schemaVersion to settle on the old version")
+			Eventually(schemaVersionGetter(ctx, c, key),
+				timeouts.For(timeouts.DocumentDBReady),
+				timeouts.PollInterval(timeouts.DocumentDBReady),
+			).Should(Equal(oldVersion), "initial schema version should be %s", oldVersion)
+


+			Consistently(schemaVersionGetter(ctx, c, key),
+				30*time.Second, 5*time.Second,
+			).Should(Equal(oldVersion),
+				"schema must remain at %s until spec.schemaVersion is set (two-phase)", oldVersion)


+			By("waiting for ALTER EXTENSION UPDATE to advance status.schemaVersion to the new version")
+			Eventually(schemaVersionGetter(ctx, c, key),
+				timeouts.For(timeouts.DocumentDBUpgrade),
+				timeouts.PollInterval(timeouts.DocumentDBUpgrade),
+			).Should(Equal(newVersion), "schema did not migrate to %s after finalize", newVersion)
+


WentingWu666666 force-pushed the wentingwu/e2e-schema-upgrade-test branch from fc8c030 to aad154d Compare July 16, 2026 16:29

documentdb-triage-tool Bot added CI/CD documentation Improvements or additions to documentation enhancement New feature or request test labels Jul 16, 2026

WentingWu666666 force-pushed the wentingwu/e2e-schema-upgrade-test branch from aad154d to 35c5051 Compare July 17, 2026 16:17

WentingWu666666 marked this pull request as ready for review July 17, 2026 16:21

WentingWu666666 requested a review from xgerman as a code owner July 17, 2026 16:21

Copilot AI review requested due to automatic review settings July 17, 2026 16:21

WentingWu666666 requested review from alaye-ms and hossain-rayhan as code owners July 17, 2026 16:21

Copilot started reviewing on behalf of WentingWu666666 July 17, 2026 16:23 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

test: add e2e schema-upgrade test for two-phase extension migration#426

test: add e2e schema-upgrade test for two-phase extension migration#426
WentingWu666666 wants to merge 1 commit into
documentdb:mainfrom
WentingWu666666:wentingwu/e2e-schema-upgrade-test

WentingWu666666 commented Jul 16, 2026 •

edited

Loading

Uh oh!

documentdb-triage-tool Bot commented Jul 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

WentingWu666666 commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Approach

Runs on every e2e PR

Status

Uh oh!

documentdb-triage-tool Bot commented Jul 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

WentingWu666666 commented Jul 16, 2026 •

edited

Loading