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

docs.json

@@ -346,7 +346,7 @@
               "self-host/enterprise-on-prem",
               "self-host/self-host-lightdash-docker-compose",
               "self-host/update-lightdash",
-              "self-host/upgrading-lightdash-versioning",
+              "self-host/upgrade-safety",
               {
                 "group": "NATS workers",
                 "pages": [
@@ -742,6 +742,10 @@
     {
       "source": "/guides/developer/agentic-coding",
       "destination": "/guides/developer/agent-skills"
+    },
+    {
+      "source": "/self-host/upgrading-lightdash-versioning",
+      "destination": "/self-host/update-lightdash"
     }
   ],
   "api": {

self-host/customize-deployment/configure-lightdash-to-use-an-external-database.mdx

@@ -45,4 +45,17 @@ Lightdash requires the following extensions to be installed on the database:
 
 ## Migrations
 
-Migrations are ran automatically on starting the Lightdash server or workers. When upgrading Lightdash, migrations will be ran automatically. If migrations fail due to a pg\_lock error, check for a table called`knex_migrations_lock` to manually release the lock.
+Migrations are ran automatically on starting the Lightdash server or workers. When upgrading Lightdash, migrations will be ran automatically.
+
+If a migration gets stuck — for example after an interrupted deploy:
+
+- **On Lightdash `1.123.0` and later**, an interrupted migration's lock expires on its own and another process takes over automatically. To inspect migration state, or release a lock that is genuinely stuck, run the built-in `migrate` command inside a Lightdash container (`kubectl exec` / `docker compose exec`):
+
+  ```bash
+  pnpm -F backend migrate-production status
+  pnpm -F backend migrate-production unlock --actor "<your identity>"
+  ```
+
+  Do **not** edit the `knex_migrations_lock` table manually on these versions — it can release a lock that a live migration legitimately holds.
+
+- **On versions before `1.123.0`**, if migrations fail due to a pg\_lock error, check for a table called `knex_migrations_lock` to manually release the lock.

self-host/production-deployment-checklist.mdx

@@ -158,7 +158,7 @@ The chart auto-wires `HEADLESS_BROWSER_HOST` / `HEADLESS_BROWSER_PORT`. Remember
 
 ## Upgrades and operations
 
-Upgrade mechanics are in [update Lightdash](/self-host/update-lightdash) and the version policy in [versioning](/self-host/upgrading-lightdash-versioning). Operational best practice:
+Upgrade mechanics and the version policy are in [updating Lightdash](/self-host/update-lightdash). Operational best practice:
 
 - **Pin `image.tag`** and upgrade deliberately. There is no LTS tag. Lightdash versioning: patch = routine, minor = check release notes (may be backwards-incompatible), major = read the upgrade guide
 - **Upgrade cadence:** at least monthly. Lightdash ships continuously; falling many minor versions behind makes the eventual migration jump riskier
@@ -248,7 +248,7 @@ migrationJob:
   enabled: true
 ```
 
-(If a deploy is ever interrupted mid-migration, the lock lives in the `knex_migrations_lock` table.)
+(If a deploy is ever interrupted mid-migration on Lightdash `1.123.0` or later, inspect with `migrate status` and use `migrate unlock --actor <identity>` as the attributed escape hatch — see [Migrations](/self-host/customize-deployment/configure-lightdash-to-use-an-external-database#migrations). Manually clearing the `knex_migrations_lock` table is only for versions before `1.123.0`.)
 
 ## Object storage
 

self-host/update-lightdash.mdx

@@ -1,9 +1,28 @@
 ---
-title: "Updating Lightdash to the latest version"
+title: "Updating Lightdash"
 sidebarTitle: Updating Lightdash
+description: "How Lightdash versioning works and how to update your self-hosted deployment."
 boost: 0.001
 ---
 
+<Note>
+🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you're on Lightdash Cloud, upgrades are handled for you automatically.
+</Note>
+
+Lightdash uses semantic versioning in the form `major.minor.patch`. Each segment signals how significant the changes are and what level of care you should take when upgrading.
+
+## How Lightdash versioning works
+
+- **Patch versions** (`x.x.PATCH`) are small fixes. These are safe to pick up as part of routine upgrades.
+- **Minor versions** (`x.MINOR.x`) introduce new features or bigger changes that are backwards incompatible. Review the release notes before upgrading.
+- **Major versions** (`MAJOR.x.x`) introduce breaking changes. You **must** read the upgrade guides below before upgrading.
+
+Major version bumps can happen because the API or the self-hosted architecture has changed substantially. Expect to make configuration, infrastructure, or integration changes when moving between major versions.
+
+<Note>
+Before upgrading a production deployment, check the [release-safety signal](/self-host/upgrade-safety) for your upgrade span — it tells you whether a rolling update is safe and whether there are required stops on the way.
+</Note>
+
 ## Local deployments
 
 If you're running Lightdash on your own laptop using Docker, you just need to instruct Docker to pull the latest version of Lightdash:
@@ -28,3 +47,9 @@ helm upgrade -f values.yml lightdash lightdash/lightdash
 Your Lightdash CLI version should match the version of Lightdash you're running. After upgrading your deployment, make sure anyone using the CLI also upgrades it — otherwise commands like `lightdash preview` and `lightdash deploy` may behave unexpectedly.
 
 See [Upgrading your Lightdash CLI](/guides/cli/how-to-upgrade-cli) for instructions.
+
+## Upgrade guides
+
+### Upgrading from Version 0 to Version 1
+
+_Coming soon._