Skip to content

docs: cover branch rebase in the upgrade docs #10311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lancamat1 wants to merge 1 commit into
base: stable
Choose a base branch
from
+5 −3
Open

docs: cover branch rebase in the upgrade docs #10311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/docs/deploy-manage/maintain-upgrade/upgrade/community.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@ajtmccarty ajtmccarty Aug 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if you keep running infrahub upgrade without the --rebase-branches option, I think it will keep reporting branches that need to be rebased, so it wouldn't ever reach the "until it reports nothing outstanding" state. I think the migration operator would understand how to proceed, but it doesn't seem quite right


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).

Expand Down
6 changes: 4 additions & 2 deletions docs/docs/deploy-manage/maintain-upgrade/upgrade/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@BaptisteGi BaptisteGi Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Talking about open branches, should we consider adding a recommendation to delete stale branches so it avoids potential issue and speedup the migration.


**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
Expand Down Expand Up @@ -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.

@gmazoyer gmazoyer Aug 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd avoid having step number in the doc. If we ever introduce a new step at some point that number would be stale.


:::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.

:::

Expand Down