Upgrading OmniGraph

Normal open accepts storage formats v14 to v16 (a v14 or v15 graph is stamped v16 at its first publish, or by the storage upgrade) and never migrates a graph. A standalone graph at v8 or v9 (release 0.11.x) or at v13 is converted in place by that offline upgrade. A graph at any other format, and every cluster-managed graph below v14, is refused and takes the export/import rebuild with the binary that wrote the graph. Start with the 0.13 → 0.14 checklist for fleet, CLI configuration, HTTP/MCP, and client compatibility changes.

Storage upgrade

omnigraph upgrade converts a standalone v8, v9 or v13 graph to v16 in place, and stamps a v14 or v15 graph to v16 in place by the route stamp-v14-to-v16: one metadata-only commit per live branch still below v16, main first, and nothing else (no pending marker, nothing under __history/legacy/, no table row rewritten); stop every reader and writer and take the backup as for any upgrade, and a run that stops part-way is finished by running it again. Branches, commit ids, commit history and table data are kept; no table row is rewritten. Only main builds from 2026-10-01 to 2026-10-04 wrote v13.

Graphs at v14 or v15 already open in 0.14; an offline stamp is not a prerequisite for ordinary reads and writes. The first ordinary 0.14 publication stamps that branch v16, including in a cluster. Opening the graph or running a no-op does not advance the stamp. as commit, commit publish and commit drop refuse a branch still at v14; as unattached branch refuses a branch still at v14 or v15. A standalone graph can use the offline command before using those features. Cluster graphs must first have an ordinary 0.14 publication on the affected branch; upgrade cannot stamp cluster graphs.

The explicit omnigraph upgrade command is offline, and it cannot verify that itself:

1. Stop every server, embedded reader or writer and maintenance process that has the graph open, and keep them stopped until the upgrade reports completed. An old process opened earlier can still write to a branch; the upgrade then stops and the root is restored from the backup.
2. Take and verify a backup of the whole graph root. There is no reverse conversion: rollback is restoring that backup with the old binary.
3. Check, then convert, then verify with the new binary:

omnigraph upgrade --target ./graph.omni --check --json
omnigraph upgrade --target ./graph.omni --json
omnigraph commit list --target ./graph.omni --json

--check writes nothing. For a v8, v9 or v13 conversion, a run without --check first marks the graph as pending, which every normal open refuses. It writes the pre-upgrade commits under __history/legacy/, converts each live branch, validates the result and only then removes the marker. Resume an interrupted conversion by running the same command with the same executable. Never delete the marker or anything under __history/.

The report's work object counts what the run read and writes: live_refs, retired_refs (deleted branches whose commits are kept), orphan_writers, legacy_commits, bookkeeping_versions, absent_parents, data_files, id_shards, writer_shards, schema_contents, census_reads, census_cells, legacy_bytes and table_opens (the tables of a v8 or v9 graph opened to compare their columns with the root schema objects). A resumed run that finds the legacy objects complete reads no history again and reports retired_refs, orphan_writers, bookkeeping_versions, schema_contents, census_reads, census_cells, legacy_bytes and table_opens as zero.

Limits, checked before anything is written: 1,024 live branches including main and 1,024 retired branches; 1,000,000 catalog rows or 64 MiB per branch head, live or retired, and 64 MiB per root schema object of a v8 or v9 graph; 256 KiB of commit fields and 16 MiB per commit record; a history-read budget that refuses a single v13 branch line above about 75,000 commits; and a history-memory budget of 1 GiB that admits about 3.8 million table entries, counted for each branch as its commits plus its head, times the tables of its head (10,000 commits over 383 tables, or 1,000 commits over 3,800). That count multiplies every commit of a branch by the tables of its head, so a graph whose tables were added late is over-counted. The budget counts only the fixed-size part of each table entry: table names and paths are not counted and planning holds a second copy, so the process needs several times 1 GiB of memory. A graph over a limit is rebuilt. A retired branch over a limit cannot shrink; 0.11.x cleanup --keep <N> --confirm removes it when no live branch, merge base or tag needs it (without --confirm it is a dry run), then run upgrade --check again.

After the upgrade, commit ids from before it resolve as before, and commit listing, the change feed, merges and cleanup read across the upgrade. A snapshot addressed by a catalog version below the upgrade serves the commit at that version, or the nearest commit below it. The upgrade lands the graph at v16, so a v14 or v15 development build older than this upgrade refuses the upgraded graph before any open: upgrade every binary first.

A graph written by 0.11.x (v8 or v9) has limits of its own. Its checks read every catalog version since init, so a long history is slow to check.

Select a standalone local direct-graph target with --target. Server, managed and direct-root targets are refused, as is a direct graph inside a cluster layout. Cluster-managed graphs below v14 require rebuild with an export from their original build. A 0.13 cluster's v14 graphs open directly in 0.14 and need no rebuild. Local paths, file URIs and symlinks resolve before the ownership check.

Lance substrate upgrades (v0.10, v0.14)

v0.10.0 moved from Lance 9 to Lance 11 on graph storage format v6: no export/import migration, but the full-text upgrade below. v0.14 moves to Lance 13 with graph format 16 and V2_2 data files unchanged: no omnigraph upgrade for a format-16 graph, and full-text indexes stay searchable, the analyzer being unchanged.

Neither transition is rolling-compatible. Update the CLI, server, and client integrations together with application traffic stopped, never run an old and new fleet against the same graph, and keep the old executables and a verified whole-root backup until the upgrade is proven: a graph the new fleet has written is not qualified for the old reader (Lance contract, v0.10 compatibility notes).

Full-text index upgrade

The v0.9-to-v0.10 transition changed the English stemmer while keeping graph storage format v6. That historical procedure requires the matching old binaries; see the v0.10 upgrade guide for its branch inventory, rebuild and rollback steps. The current CLI cannot open v6, so a graph still on that format needs an export/import rebuild.

In v0.14, certified full-text indexes from Lance 11 remain searchable with Lance 13 because the analyzer generation is unchanged. Missing or incompatible analyzer proofs still fail closed. For a graph that normal open accepts (formats 14–16), use the explicit maintenance command on each branch that needs new indexes:

omnigraph index rebuild --kind full-text --target ./graph.omni --branch main --as operator --json

Follow the full-text maintenance procedure for authorization, tokenizer changes and result checks. Rebuilding a live branch publishes its indexes in one graph commit; it leaves earlier snapshots unchanged, so those snapshots may still refuse full-text search. optimize is not a replacement for an analyzer rebuild.

A retained published commit under the current schema can start a branch with branch create --from-commit <id>; pre-upgrade commits are refused. See the branch-start restrictions.

Unsupported index inventory

A missing physical index kind or unsupported index format makes the rebuild refuse before publication. Use compatible old tooling for a controlled export/import rebuild, or restore a trusted backup with supported inventory. Keep the source intact; do not guess an index kind or edit metadata to bypass the refusal.

Cluster state and rollback

For the historical v0.10-to-v0.9 rollback, including external_blobs state, follow the tagged rollback procedure with those binaries. It is not a downgrade path from v0.14.

What an export/import rebuild preserves

This table describes rebuilding a graph at a new URI for a graph-format change, not the full-text index rebuild above. An index rebuild retains the existing graph's entities, branches, and history.

Export each branch you need separately. Each import becomes an independent main branch in a new graph; shared ancestry is not reconstructed.

Choose the export binary

The refusal message names the release line that wrote the graph. The known mapping is:

If the graph's generation is newer than the binary, upgrade the binary instead.

System-column upgrade (legacy spellings)

omnigraph schema upgrade-system-columns --target <graph> respells a standalone graph's legacy system columns in place (id/src/dst to __id/__src/__dst). It needs a graph that normal open accepts. The respelling changes no storage layout and publishes the replacement contract with the renamed table references in one new graph commit. Columns are renamed by field id: no table rows are rewritten, indexes survive, and data and existing history/commit IDs are preserved; --check runs the preflight and writes nothing; --json prints the report. The preflight refuses a graph with any non-main branch (merge what you need, then delete the branches: a merge alone leaves the source live) and a property whose name starts with _ (rename it with @rename_from first), naming every offender under system_columns_preflight. Edge constraints such as @unique(src, dst) become @unique(@src, @dst). Stop every server serving the graph and retain a verified backup first. Concurrent graph movement can refuse the attempt; stop writers and rerun from a fresh capture. There is no reverse operation. A run interrupted before it publishes changes nothing: rerun it. Once publication succeeds, fresh read-only and read-write opens use the accepted schema; a rerun reports already_current. A graph that already spells __id/__src/__dst reports already_current; cluster-managed graphs are refused.

Rebuild

Keep separate executables and target URIs so the source remains recoverable. Stop all source writers, including embedded and standalone CLI writers, before exporting schema and data, and keep them stopped through cutover. Take and verify a whole-root backup; use the old binary for the exports below.

When an export already carries top-level id, the rewrite preserves it and any user property named id. For predecessor schemas, change endpoint constraint references from src/dst to @src/@dst before the new init. See ingestion for the envelope contract.

# Old binary
old-omnigraph schema show s3://bucket/graph.omni > schema.pg
old-omnigraph export s3://bucket/graph.omni > graph.jsonl

# Relocate predecessor export identities
jq -c 'if has("id") then . else .id = .data.id | del(.data.id) end' \
  graph.jsonl > graph-current.jsonl

# New binary (schema.pg endpoint constraints use @src and @dst)
omnigraph init --schema schema.pg ./graph-new.omni
omnigraph load --mode overwrite --data graph-current.jsonl \
  --target ./graph-new.omni

# Verify with the new binary
omnigraph snapshot --target ./graph-new.omni --json
omnigraph schema show --target ./graph-new.omni

For another branch:

old-omnigraph export --branch review s3://bucket/graph.omni \
  > review.jsonl
jq -c 'if has("id") then . else .id = .data.id | del(.data.id) end' \
  review.jsonl > review-current.jsonl
omnigraph init --schema schema.pg ./graph-review-new.omni
omnigraph load --mode overwrite --data review-current.jsonl \
  --target ./graph-review-new.omni

Verify before cutover

At minimum:

• compare entity counts by type;
• run representative queries and mutations in a staging copy;
• sample IDs, vectors, null values, and Blob values;
• rebuild or reconcile declared indexes with optimize;
• verify server policy, stored queries, and external Blob access in the target cluster;
• keep the old graph read-only until the new fleet is serving successfully.

Embeddings are copied as stored vectors; they are not regenerated. If the model changed, re-embed after the import.

External Blob references require the target graph's allow-list to admit the same sources. A direct-store CLI has no cluster allow-list and therefore cannot admit new external references. Rebuild such data through a configured cluster server or an embedded host that installs the policy. See Blob values.

Cluster cutover

Cluster graph roots are derived as <cluster-root>/graphs/<graph-id>.omni; a graph declaration cannot point at an arbitrary replacement root. Choose one of these cutovers:

• New graph ID in the same cluster. Add (for example) knowledge-next with the desired schema, query, provider, and policy bindings. Validate, plan, and submit cluster apply --target <server-target> --config <bundle> so the running owner creates and activates its derived root. Load through that server, verify the new ID, back up what you need, and move clients. Removing the old declaration and applying deletes its managed storage and all retained history.
• Same graph ID in a parallel cluster root. Copy the source bundle and keep the original cluster untouched. Bootstrap a separate root following cluster bootstrap and ownership transfer. Validate the bundle, then for a local root plan and apply with --target ./cluster-new --config ./new-bundle; any storage: assertion must match that selected root, and changing storage: alone never selects it. After direct apply, establish that its owner and accepted I/O have settled, then release its exact retained lock as that procedure requires. Start the new server against the new root, load through its server target, verify, and move clients to it. This preserves the public graph ID while changing the whole deployment artifact.

In either case, quiesce writers before export and cutover. External Blob references must be loaded through a policy-aware server or embedded host after the target allow-list is applied.

Do not run a mixed fleet of binaries that disagree on the storage format. Do not edit internal metadata, overwrite the source root with init --force, or copy files or backing datasets between graph roots.