docs: upgrade safety and the release-safety artifact (self-hosted) by charliedowler · Pull Request #1098 · lightdash/mintlify-docs

charliedowler · 2026-08-11T11:26:29Z

What

New self-hosting page "Upgrade safety and the release-safety artifact" (self-host/upgrade-safety.mdx), documenting the machine-readable safety signal that ships with every release as of 1.121.0:

The consumption contract, stated up front: only an explicit rollingUpdateSafe: true means rolling is advised — unknown means NOT safe (use Recreate).
How verdicts compose across a span (AND), required stops, minPreviousVersion, the 0.1893.0 index floor, and why backfilled entries are conservative.
Span checking via the lightdash upgrade-check CLI verb as the primary method (exit-code semantics for CI gates, --json), with the tested curl + jq recipe as an air-gapped/no-Node appendix.
Worked example reading the real 1.121.0 release-safety.json (a green verdict).
Full field reference for both release-safety.json (schemaVersion 2) and release-safety-index.json, including migration heaviness flags, config change shapes, and the dev-build sentinel.
A before-you-upgrade checklist.

Also adds the nav entry in docs.json and a cross-link from the updating page.

Page consolidation

The former "Updating Lightdash" and "Upgrading Lightdash (versioning)" pages are now one "Updating Lightdash" page (versioning semantics → pre-upgrade safety-signal note → per-deployment mechanics → CLI version match → upgrade guides stub). The versioning page is deleted, its nav entry removed, and a docs.json redirect maps the old URL to the merged page. The upgrade-safety page stays separate as the reference; the merged page links to it exactly once.

Notes

The upgrade-check CLI verb is documented from its implementation (feat(cli): ship lightdash upgrade-check — login-free upgrade safety verdicts lightdash#27169), which has not merged/published yet — no carrier CLI version is stated, and the sample output is marked illustrative. Verifying the verb against the actually-published npm CLI (and making the sample verbatim) must happen before this PR leaves draft.
Rollback guidance is deliberately absent from this page — upgrade-check rejects reverse spans, and rollback documentation arrives with the upgrade runbook.
All commands and example outputs were verified against the live index and the real 1.121.0 release asset.

Linear: SPK-930

🤖 Generated with Claude Code

https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

…for self-hosted deployments Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify · 2026-08-11T11:26:32Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
lightdash	🟢 Ready	View Preview	Aug 11, 2026, 11:28 AM

github-actions · 2026-08-11T11:26:55Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

linear-code · 2026-08-11T11:56:31Z

SPK-930

github-actions · 2026-08-11T11:56:52Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

…121.0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

github-actions · 2026-08-11T12:18:34Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

charliedowler · 2026-08-11T14:06:50Z

Status note — verification COMPLETE (06b3181): the lightdash upgrade-check verb is verified against the published @lightdash/cli@1.126.0 binary.

#27169 merged (c4d0239c) and published @lightdash/cli@1.126.0 carries the verb (first release tag containing the merge, confirmed via git tag --contains)
Verb verified via npx @lightdash/cli@1.126.0 against the live index — human output is verbatim identical to the documented sample; exit code 1 on the UNSAFE span as documented
--json shape confirmed against the binary — one docs mismatch found and fixed: the field list was missing fromVersion/toVersion (9 keys total, direction present as upgrade)
Reverse spans confirmed rejected (exit 1, "Rollback spans are not supported by this command") — consistent with this page containing no rollback guidance
Carrier CLI version stated in the docs ("version 1.126.0 or later"); illustrative marker and MDX verification comment removed

Update (f0ef2f2): the sidebar's three upgrade/update pages are consolidated to two — versioning merged into "Updating Lightdash" (with a redirect from the old URL), upgrade-safety kept as the standalone reference.

Update (e85a7a3): the manual knex_migrations_lock recovery ritual in two self-host pages is replaced with version-fenced migrate status / migrate unlock --actor guidance (verbs verified present since release 1.123.0).

github-actions · 2026-08-11T14:06:52Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

…dash page Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

github-actions · 2026-08-11T14:11:48Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

github-actions · 2026-08-11T14:20:18Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

…ck from 1.123.0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

github-actions · 2026-08-11T15:12:16Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

github-actions · 2026-08-11T15:24:46Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

github-actions · 2026-08-11T16:16:31Z

🤖 Documentation Bot

✅ All checks passed! No issues found.

docs: document the release-safety artifact and upgrade-safety signal …

33662b2

…for self-hosted deployments Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

github-actions Bot assigned charliedowler Aug 11, 2026

mintlify Bot deployed to staging August 11, 2026 11:28 View deployment

docs: hold rollback guidance until the supporting runtime ships

0d47c61

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify Bot deployed to staging August 11, 2026 11:57 View deployment

docs: document api-surface advisory and count fields as shipped in 1.…

33fc9df

…121.0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify Bot deployed to staging August 11, 2026 12:19 View deployment

docs: make lightdash upgrade-check the primary span-check method

05af1a3

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify Bot deployed to staging August 11, 2026 14:07 View deployment

docs: consolidate versioning and update pages into one Updating Light…

f0ef2f2

…dash page Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify Bot deployed to staging August 11, 2026 14:12 View deployment

docs: drop the development-sentinel callout from the field reference

8c418dc

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify Bot deployed to staging August 11, 2026 14:20 View deployment

docs: replace manual migration-lock recovery with migrate status/unlo…

e85a7a3

…ck from 1.123.0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify Bot deployed to staging August 11, 2026 15:12 View deployment

docs: drop rollback-direction span checking

bb68e5a

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify Bot deployed to staging August 11, 2026 15:25 View deployment

docs: verify upgrade-check against published CLI 1.126.0

06b3181

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2if8my6XfAewUiZrkkbdX

mintlify Bot deployed to staging August 11, 2026 16:17 View deployment

charliedowler marked this pull request as ready for review August 11, 2026 16:17

charliedowler merged commit 8d672e6 into main Aug 11, 2026
6 checks passed

charliedowler deleted the feature/upgrade-safety-docs branch August 11, 2026 16:17

charliedowler mentioned this pull request Aug 12, 2026

docs: self-hosted upgrade runbook #1103

Merged

Navigation Menu

Uh oh!

docs: upgrade safety and the release-safety artifact (self-hosted) - #1098

docs: upgrade safety and the release-safety artifact (self-hosted)#1098
charliedowler merged 9 commits into
mainfrom
feature/upgrade-safety-docs

charliedowler commented Aug 11, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Aug 11, 2026

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

charliedowler commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

charliedowler commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Page consolidation

Notes

Uh oh!

mintlify Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

linear-code Bot commented Aug 11, 2026

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

charliedowler commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

charliedowler commented Aug 11, 2026 •

edited

Loading

mintlify Bot commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading

charliedowler commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading

github-actions Bot commented Aug 11, 2026 •

edited

Loading