From 8e189cc49ed87e4bfc618d48cdcb3206581a2453 Mon Sep 17 00:00:00 2001 From: Matej Lanca Date: Tue, 18 Aug 2026 21:55:57 +0200 Subject: [PATCH] docs: cover branch rebase in the upgrade docs Three minimal additions, each closing a gap an operator hits when upgrading: - "Before you upgrade" did not mention branches, so the branches the upgrade will rebase were only discovered once the upgrade was running. Point at `infrahub upgrade --check`, which already reports them. - The transaction memory known issue was scoped to migrations, but the branch rebase can reach the same limit, and its requirement grows with the size of the branch rather than the size of the database. - Removing the transaction limit alone can still fail, because the allocation then comes from the JVM heap, so the heap has to be sized for it too. - Verification stopped at `showmigrations`, which passes even when the core schema or a branch rebase is still outstanding. `--check` covers all three. Co-Authored-By: Claude Opus 5 (1M context) --- .../deploy-manage/maintain-upgrade/upgrade/community.mdx | 2 +- .../deploy-manage/maintain-upgrade/upgrade/overview.mdx | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/docs/deploy-manage/maintain-upgrade/upgrade/community.mdx b/docs/docs/deploy-manage/maintain-upgrade/upgrade/community.mdx index 5fd6d9472a2..99c78fd22e5 100644 --- a/docs/docs/deploy-manage/maintain-upgrade/upgrade/community.mdx +++ b/docs/docs/deploy-manage/maintain-upgrade/upgrade/community.mdx @@ -92,7 +92,7 @@ invoke demo.start ## Verify the upgrade -After the `infrahub upgrade` command exits with `Upgrade complete SUCCESS`, run `infrahub db showmigrations` against the same database to confirm every migration shows `[X]` and that the database version matches the target version reported in the header. If any migrations are still pending, re-run `infrahub upgrade`. +After the `infrahub upgrade` command exits with `Upgrade complete SUCCESS`, run `infrahub db showmigrations` against the same database to confirm every migration shows `[X]` and that the database version matches the target version reported in the header. Then run `infrahub upgrade --check`, which reports pending migrations, core schema differences and branches that still need rebase, so all three parts of the upgrade are covered rather than the migrations alone. Re-run `infrahub upgrade` until it reports nothing outstanding. If you skipped `--rebase-branches` and the upgrade reported open branches that need rebase, they are left in the `needs-rebase` state. You can rebase them manually later, or re-run with `infrahub upgrade --rebase-branches` (optionally combined with `--interactive` to confirm each branch). diff --git a/docs/docs/deploy-manage/maintain-upgrade/upgrade/overview.mdx b/docs/docs/deploy-manage/maintain-upgrade/upgrade/overview.mdx index 64a8e390528..ee14c7f5e85 100644 --- a/docs/docs/deploy-manage/maintain-upgrade/upgrade/overview.mdx +++ b/docs/docs/deploy-manage/maintain-upgrade/upgrade/overview.mdx @@ -12,6 +12,8 @@ Upgrading Infrahub involves pulling the latest container images, running databas **Backup first**: Even though a smooth migration is anticipated, we strongly recommend creating a backup before upgrading. See [Backup and restore](../database-backup/backup-and-restore.mdx). +**Open branches**: Run `infrahub upgrade --check` before you start. It reports the branches the upgrade will rebase, so a branch that needs attention first can be resolved or deleted instead of failing during the upgrade. + **Release notes**: Review the [release notes](../../../release-notes/infrahub/) for any version-specific upgrade instructions. In Infrahub 1.2 and later, the upgrade process was streamlined with a unified upgrade command. For earlier versions, refer to the release notes for specific instructions. ## What the upgrade does @@ -176,11 +178,11 @@ Select the guide for your edition and deployment: ### Migration failing because of transaction memory limit reached in Neo4j -For large database/schema migrations, you may encounter a `Transaction memory limit reached` error in Neo4j. +For large database/schema migrations, you may encounter a `Transaction memory limit reached` error in Neo4j. The branch rebase in Step 6/6 can reach the same limit, because the memory it needs grows with the number of changes on the branch being rebased. :::info -To work around this, you can disable the transaction memory limit by setting the `dbms.memory.transaction.total.max` to `0` in your Neo4j configuration. +To work around this, you can disable the transaction memory limit by setting the `dbms.memory.transaction.total.max` to `0` in your Neo4j configuration. The memory is still allocated from the JVM heap, so `server.memory.heap.max_size` also has to be large enough for the operation. :::