Skip to content

Prepare native Server 3.12.0 retained payload bindings and version usage release - #1225

Merged
rmcdaniel merged 2 commits into
mainfrom
release/server-3.12.0
Nov 17, 2026
Merged

rmcdaniel merged 2 commits into
mainfrom
release/server-3.12.0

Conversation

@rmcdaniel

Copy link
Copy Markdown
Member

Native Server 3.12.0 release preparation. Following the 3.11.0 precedent (#1218), this changes two files: the published Compose default moves from durableworkflow/server:3.11.0 to durableworkflow/server:3.12.0, and new docs/releases/3.12.0.md documents everything merged to main after tag 3.11.0 (da38c0ed) up to 2c675220. The Chart 2.1.0 prep commit is excluded because it is already released.

Contents

Schema, upgrade and rollback facts (from code)

  • New physical schema versions are SQLite 15, PostgreSQL 16, MariaDB 16 and MySQL 17 (was 14/15/15/16). Sources are rust/src/runtime/schema.rs VERSION, postgres.rs VERSION, mysql.rs MYSQL_VERSION/MARIADB_VERSION, and rust/migrations/*/00{15,16,17}_external_storage_bindings.sql. Each step adds the nullable runtime_external_payloads.storage_binding and workflow_namespaces.external_payload_storage_generation BIGINT NOT NULL DEFAULT 0.
  • Startup never upgrades the schema, so an explicit schema-upgrade is needed (schema_upgrade.rs). SQLite and PostgreSQL run it in one transaction. MySQL and MariaDB resume an interrupted ALTER (ensure_external_storage_bindings). With Helm 2.x, use the existing opt-in native.schemaUpgrade.enabled pre-upgrade hook or the manual Job.
  • There is no backfill. A registration is bound lazily on first use, and only when the current admitted policy reproduces its recorded URI. Before a policy change replaces the policy, it pins all unbound rows to the current or the explicitly requested location, or refuses with external_payload_storage_binding_unavailable (409) (external_storage_binding.rs, namespaces.rs::set_external_policy). Objects stranded under 3.11.x can be repaired by naming their original root explicitly.
  • Rollback: a 3.11.x binary refuses the upgraded database with native_schema_newer_than_binary. Rollback means restoring the pre-upgrade database and payload backup.
  • Worker protocol 1.20 and control-plane version 2 are unchanged. The OpenAPI document version is 15 → 16 (Report open-run legacy version usage in native Server #1221).

Checks run locally

  • The release-notes heading check and relative-link resolution from native-release-github-release.sh pass. All five relative links and anchors exist.
  • scripts/ci/check-native-release-tags.sh passes.
  • verify-native-release-dispatch.sh (stub gh) accepts tag 3.12.0 and refuses 3.11.0 against this Compose file.
  • tests/Unit/NativePublishedComposeContractTest.php passes (7 tests).
  • resources/release/source-release.json (PHP 2.11.8 / chart) is intentionally unchanged.

Open questions for the owner

  1. MySQL startup refusal reason. schema_upgrade::UPGRADABLE is [7, 8, 10, 11, 12, 13, 14, 15] and does not include 16. As a result, a 3.12.0 binary started on a 3.11.x MySQL database (marker 16) refuses with unsupported_rust_schema instead of native_schema_upgrade_required. schema-upgrade itself still upgrades 16 → 17 through Flavor::earlier(16). No test covers this startup reason. The notes therefore avoid naming the reason code. Recommendation: add 16 to UPGRADABLE with a test before tagging.
  2. Unrepairable multi-root case. The notes state that stranded registrations under two or more earlier roots make every policy change refuse. This is inferred from pin_legacy_payloads. Please confirm, or document a supported repair.
  3. Chart version. The chart version that selects 3.12.0 is undecided. Every backend needs a schema step, which per UPGRADING's rule for Chart 2.0.0 may mean a chart major. The notes defer to that chart's own notes.

Not done here: merge, tag, dispatch, publication or alias movement. #980, #1204 and #1220 consumer follow-through are unchanged.

🤖 Generated with Claude Code

Select durableworkflow/server:3.12.0 as the published Compose default and
add docs/releases/3.12.0.md covering retained payload storage bindings
(#1224), open-run version usage (#1221) and portable native library builds
(#1223), with the explicit schema steps, rollback and retained limits.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@rmcdaniel

Copy link
Copy Markdown
Member Author

General review of head a980fc8f: PASS for the notes and Compose default, to merge after #1226. The notes match the code: schema steps SQLite 14→15, PostgreSQL 15→16, MariaDB 15→16, MySQL 16→17, adding nullable storage_binding and external_payload_storage_generation with no row rewrite. They state the explicit schema-upgrade with no startup auto-upgrade, no backfill with bind-on-first-use, the explicit-location repair for stranded objects and its multi-root limit, rollback by backup restore (3.11 refuses the newer schema), and GET /api/workflow-version-usage with capabilities.workflow_version_usage. Open question 1 (MySQL 16 missing from UPGRADABLE) is fixed in #1226. Question 3: the chart choice is made after publication, as with 2.1.0.

@sonarqubecloud

Copy link
Copy Markdown

@rmcdaniel
rmcdaniel added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit da655a8 Nov 17, 2026
29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Keep stored external payloads readable after a namespace storage policy is disabled or moved

1 participant