docs: cover branch rebase in the upgrade docs - #10311
Open
lancamat1 wants to merge 1 commit into
Open
Conversation
lancamat1
added
type/documentation
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
No issues found across 3 files
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Shadow auto-approve: would auto-approve. Documentation-only change: adds upgrade guidance, pre-flight checks, and caveats for large instances to upgrade docs. No code, behavior, or operational settings changed; no human tradeoff to review.
Re-trigger cubic
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) <noreply@anthropic.com>
lancamat1
force-pushed
the
mla/docs-upgrade-large-instance
branch
from
August 18, 2026 20:06
999367e to
8e189cc
Compare
lancamat1
changed the title
lancamat1
marked this pull request as ready for review
August 19, 2026 09:01
gmazoyer
reviewed
Aug 19, 2026
| ### 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. |
Contributor
There was a problem hiding this comment.
I'd avoid having step number in the doc. If we ever introduce a new step at some point that number would be stale.
ajtmccarty
reviewed
Aug 19, 2026
| ## 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. |
Contributor
There was a problem hiding this comment.
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
BaptisteGi
reviewed
Aug 20, 2026
|
|
||
| **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. |
Contributor
There was a problem hiding this comment.
Talking about open branches, should we consider adding a recommendation to delete stale branches so it avoids potential issue and speedup the migration.
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Three gaps in the upgrade docs, each of which an operator hits in practice. Kept deliberately minimal — one addition per gap, no restructuring.
What changed, and why each line is there
overview.mdx— "Before you upgrade" gains an "Open branches" lineThe section covers upgrade path, backups and release notes, but says nothing about branches, even though Step 6/6 rebases every open branch. A branch that cannot be rebased is therefore discovered mid-upgrade. The line points at
infrahub upgrade --check, which already reports the branches the upgrade will rebase, so they can be dealt with beforehand.overview.mdx— the transaction memory known issue gains two sentencesdbms.memory.transaction.total.maxto0removes the ceiling, but the memory is still allocated from the JVM heap, soserver.memory.heap.max_sizehas to be large enough as well. Without this, the documented workaround can be applied and still fail.community.mdx— "Verify the upgrade" also uses--checkVerification stopped at
infrahub db showmigrations, which passes even when the core schema or a branch rebase is still outstanding, so an upgrade can look verified while it is not.infrahub upgrade --checkreports all three areas.Related issues
Reported separately, against 1.10.6:
validate_databasedoes not retryTransientError, so a command can abort withDatabaseUnavailablewhile Neo4j is still recoveringinfrahub upgradeprintsUpgrade complete SUCCESSand exits 0 when branch rebases failedValidationErrorandMigrationFailureError, so any other error aborts the remaining branchesThe two paragraphs about the memory limit are interim guidance; if #10310 lands they should be revisited.
Verification
uv run invoke docs.lint— 0 markdownlint errors; vale reports 0 warnings on the changed files (the 25 warnings in the run are pre-existing in other pages)cd docs && npm run build— succeeds, no broken links or anchors🤖 Generated with Claude Code