From 1b978cb95edf3c7b1b321fbb077a41a4971310e5 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Thu, 12 Nov 2026 11:52:49 +0000 Subject: [PATCH] Add native 3.7.0 release notes Co-Authored-By: Claude Opus 5.5 --- docs/releases/3.7.0.md | 73 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/releases/3.7.0.md diff --git a/docs/releases/3.7.0.md b/docs/releases/3.7.0.md new file mode 100644 index 000000000..348862b8b --- /dev/null +++ b/docs/releases/3.7.0.md @@ -0,0 +1,73 @@ +# Durable Workflow Server 3.7.0 (native) + +Server 3.7.0 stores MySQL JSON documents as exact text, so doubles come back +with every digit. It also lets redrive carry a failed run's start-time memos and +search attributes, and reports whether a run can be redriven in describe. Its +exact images are `durableworkflow/server:3.7.0` and +`ghcr.io/durable-workflow/server:3.7.0` (index +`sha256:27ca9a9156c9e4b489de770b4d5abc10f5ba9fc6da97134d26432fcaabdf37fb`). The +published Compose default selects 3.7.0, and Helm chart 1.5.0 defaults to it. + +## Upgrade + +**MySQL only: schema upgrade from 12 to 13.** The upgrade rebuilds the 36 +tables that hold the 75 JSON columns, one atomic `ALTER TABLE` per table, and +an interrupted upgrade resumes table by table. The Server is down for the whole +upgrade, which takes about 2 minutes per million history rows. That was +measured on MySQL 8.0.46 with 2 CPUs and the default 128 MiB buffer pool: +1,000,000 history rows (2.65 GB) took 115 s. Plan for the other JSON tables +too. + +1. Stop every native Server. +2. Back up the database and record the current image reference. +3. Run the 3.7.0 image's `schema-upgrade` once. It reports + `"from_schema_version":12,"schema_version":13,"status":"upgraded"`. Run + again, it reports `"status":"current"`. +4. Start the 3.7.0 Servers and confirm `/api/ready`, `/api/cluster/info` + (`version` is `3.7.0`) and worker registration. + +A 3.7.0 Server on a MySQL schema-12 database refuses to start with +`native_schema_upgrade_required`. Rolling back to 3.6.0 on MySQL means +restoring the backup: 3.6.0 refuses the upgraded database with +`native_schema_newer_than_binary`. + +**MariaDB, PostgreSQL and SQLite: no schema change.** MariaDB and PostgreSQL +stay at schema 12 (MariaDB's bootstrap checksum is unchanged) and SQLite at 11. +Replace the image and restart; rolling back to 3.6.0 is an image change. +Databases still on 3.4.x or earlier need the +[3.5.0 schema upgrade](3.5.0.md#upgrade); the 3.7.0 image's `schema-upgrade` +applies the earlier steps too. + +On Kubernetes, follow the chart's +[Chart 1.5.0 / Server 3.7.0 notes](../../k8s/helm/durable-workflow/docs/UPGRADING.md#chart-150--server-370-native). +The worker protocol stays at `1.20` and the control plane at version `2`. + +## Exact JSON on MySQL + +MySQL's `json` type parses doubles into its own binary form, so a history +payload, memo, search attribute or heartbeat detail could come back one unit in +the last place off (`1.4820142857142857` read as `…855`) +([#1016](https://github.com/durable-workflow/server/issues/1016)). Schema 13 +stores every JSON document column as `LONGTEXT` in `utf8mb4_bin` with an +enforced `json_valid` check, as MariaDB already does, and the text is kept +verbatim. Queries are unchanged. Documents written before the upgrade keep +MySQL's earlier rendering, including any rounded doubles. + +## Redrive carries start-time visibility + +Redrive no longer refuses a failed run because it has memos or search +attributes set at start or inherited from its parent +([#980](https://github.com/durable-workflow/server/issues/980)). The successor +keeps each of those rows as recorded, and its `WorkflowStarted` keeps them too. +Values that workflow code upserted still refuse with +`unsupported_visibility_metadata`, and a run started as a child still refuses +with `unsupported_source_metadata`; later slices of #980 cover those. + +## Redrive decision in describe + +Describe's `actions` now report `can_redrive` and `redrive_blocked_reason`, from +the same check that redrive applies, as Workflow's run detail does +([#980](https://github.com/durable-workflow/server/issues/980)). The reason is +`run_not_failed`, then `already_redriven`, then redrive's own refusal reason; +`can_redrive` is true exactly when the reason is null. A read-only v1 +projection reports `v1_projection_read_only`.