upgrade-versions

name	upgrade-versions
description	Bump pinned versions of (A) Java fdb-record-layer / fdb-relational artifacts or (B) the FDB C++ wire protocol. Captures every spot the version is pinned, the codegen steps, and the conformance gotchas. Pass `java` or `fdb-cpp` to pick which procedure to run.
user-invocable	true

Upgrade procedure

This project pins two independent versions:

• A — Java fdb-record-layer / fdb-relational artifacts. Currently 4.11.1.0. Used by the conformance Java server and as the canonical source for proto schemas.
• B — FDB C++ wire protocol. Currently 7.3.77. Used by the pure-Go FDB client (pkg/fdbgo/) — wire frames, request/reply types, error codes, atomic mutation semantics all match this version.

These versions are independent — bumping Java does not require bumping FDB C++ or vice versa. Each procedure has its own canonical command sequence and its own set of "things you must touch."

Input

• /upgrade-versions java → run procedure A.
• /upgrade-versions fdb-cpp → run procedure B.
• /upgrade-versions (no arg) → ask the user which one.

If the user passes a target version (e.g. /upgrade-versions java 4.12.0.0), use it. Otherwise:

• For java: pick the latest 4.x.y.0 listed at https://repo1.maven.org/maven2/org/foundationdb/fdb-record-layer-core/. Verify the same version exists for fdb-relational-api and fdb-relational-core — if not, pick the highest version that exists in all three.
• For fdb-cpp: pick the latest 7.3.x tag at https://github.com/apple/foundationdb/tags. Do not jump major (7.x → 8.x) without explicit user confirmation; major bumps move serialization formats and error codes.

Always confirm the picked version with the user before editing any files. Bumping is destructive — wrong version means the rest of the procedure either fails midway or lands a broken pin.

---

Procedure A — Java fdb-record-layer / fdb-relational

What you're touching

Surface	Why
MODULE.bazel — maven.install.artifacts	The version of every fdb-record-layer / fdb-relational jar resolved by Bazel
fdb-record-layer/ (gitignored submodule)	Local git checkout for source reading + proto syncing
proto/apple/*.proto	Apple's proto files copied from the submodule. Compiled into both Go (gen/*.pb.go) and Java (libapple_proto-speed.jar). When Java's compiled proto classes drift from the maven jar's proto classes the conformance server hits NoSuchFieldError at static-init time.
gen/*.pb.go (auto)	Regenerated by just generate from proto/apple/*.proto. Always commit the regenerated output.
CLAUDE.md "Java source reference" prose	One-line version mention; keep it accurate.
TODO.md header line	One-line version mention; keep it accurate.

Steps

1. Confirm Maven artifact availability for the target version. fdb-relational-* started publishing later than fdb-record-layer-core, so a version that works for one may not exist for the others.

   for art in fdb-record-layer-core fdb-relational-api fdb-relational-core; do
     curl -sf "https://repo1.maven.org/maven2/org/foundationdb/$art/$VERSION/$art-$VERSION.pom" >/dev/null \
       && echo "OK $art $VERSION" || echo "MISSING $art $VERSION"
   done
   

   If any artifact is missing, pick a higher version where all three exist.

2. Update the local submodule checkout. It's gitignored — it lives at fdb-record-layer/ in the repo root.

   cd fdb-record-layer
   git fetch origin --tags
   git checkout $VERSION
   cd ..
   

   Sanity-check: git -C fdb-record-layer log --oneline -1 should show the release commit for $VERSION.

3. Bump MODULE.bazel. Update all three artifacts in the maven.install block to the same version:

   "org.foundationdb:fdb-record-layer-core:$VERSION",
   "org.foundationdb:fdb-relational-api:$VERSION",
   "org.foundationdb:fdb-relational-core:$VERSION",
   

4. Run bazel mod tidy to refresh the resolved Maven dep set:

   bazelisk mod tidy
   

5. Sync the proto files. This is the step the conformance test breaks if you skip.

   diff -q proto/apple/ fdb-record-layer/fdb-record-layer-core/src/main/proto/
   

   For every file that differs, copy the new version from the submodule into . Skip (it lives only on our side).

Common failures

• NoSuchFieldError: ... PXxx_descriptor in conformance test. Our locally-compiled proto/apple/libapple_proto-speed.jar is on the conformance test's classpath BEFORE the Maven jar. When proto/apple/*.proto is older than the Maven jar's compiled-in protos, fdb-relational-core's static init references a descriptor field our jar lacks. Fix: sync the proto file (step 5).
• Maven resolution picks an older fdb-record-layer-core via transitive deps. Rare; if it happens, pin the exact version in MODULE.bazel and run bazel mod tidy.
• Submodule on an older tag than the bumped version. git -C fdb-record-layer log --oneline -1 should match. Step 2 handles this; if you skipped it the proto diff in step 5 is misleading.

---

Procedure B — FDB C++ wire protocol

What you're touching

Surface	Why
MODULE.bazel — bazel_dep(name = "foundationdb", ...)	The pinned C++ source archive Bazel fetches
MODULE.bazel — module(name = "foundationdb", version = ...) (inside archive_override.patch_cmds)	The version embedded in the patched MODULE.bazel for the foundationdb module
MODULE.bazel — archive_override.strip_prefix + urls	Both reference the version literally
.bazelrc — test --test_env=FDB_VERSION=...	Version env var visible to test setups (testcontainers, etc.)
pkg/fdbgo/wire/types/*_generated.go (auto)	Regenerated by just generate-wire-types from the new C++ source via the schema extractor
pkg/fdbgo/wire/serializer.go doc comment	"Source: flow/include/flow/flat_buffers.h (FDB X.Y.Z)" — update the version string
pkg/fdbgo/README.md	Mentions the FDB version twice; keep it accurate
pkg/fdbgo/client/CRASH_BUG.md	Mentions Docker image tags foundationdb/foundationdb:X.Y.Z; keep accurate
CLAUDE.md "Baseline numbers" + similar prose	Mentions FDB version in benchmark context

Steps

1. Confirm tag availability.

   curl -sf "https://github.com/apple/foundationdb/archive/refs/tags/$VERSION.tar.gz" -o /dev/null -I | head -1
   

   Expect 200 OK. Also check the Docker image:

   docker manifest inspect foundationdb/foundationdb:$VERSION >/dev/null && echo OK || echo MISSING
   

2. Confirm wire-protocol compatibility. A patch bump within a minor line (e.g. 7.3.x → 7.3.y) is wire-compatible. A 7.3 → 7.4 minor bump may add new request/reply types but should remain backwards-compatible for the existing wire frames. A 7.x → 8.x major bump moves serialization in non-trivial ways — get explicit user confirmation before proceeding. Read FoundationDB release notes for the new version.

3. Bump MODULE.bazel. Replace the version in four places inside the foundationdb block:

   bazel_dep(name = "foundationdb", version = "$VERSION")
   ...
   module(name = "foundationdb", version = "$VERSION")
   ...
   strip_prefix = "foundationdb-$VERSION",
   urls = ["https://github.com/apple/foundationdb/archive/refs/tags/$VERSION.tar.gz"],
   

4. Bump .bazelrc.

   test --test_env=FDB_VERSION=$VERSION
   

5. Regenerate wire types. This invokes the C++ schema extractor against the new source archive Bazel fetched.

   just generate-wire-types
   just gazelle
   

   Inspect the diff in pkg/fdbgo/wire/types/*_generated.go. Pure additive changes (new fields / new types) are safe and the generator output is deterministic. Field-removal or type-rename diffs require call-site fixes elsewhere in pkg/fdbgo/.

6. Update prose / version-string references. Each of these files mentions the FDB version literally; sweep with grep:

   grep -l "$OLD_VERSION" pkg/fdbgo/wire/serializer.go pkg/fdbgo/README.md pkg/fdbgo/client/CRASH_BUG.md CLAUDE.md
   

   Replace with .

Common failures

• pkg/fdbgo/wire/types/*_generated.go includes a _generated.go file we didn't author. Schema extractor produced a new wire type. If it's something we use, integrate it; if not, register it in cmd/fdb-schema-extract/extract.h and main.cpp per the policy in CLAUDE.md.
• Client tests fail with unknown error code 21XX. New error code in the FDB version. Map it in pkg/fdbgo/client/errors.go (retryable / non-retryable / resource-constrained / etc.) per the same classification C++ uses (consult fdbclient/include/fdbclient/FDBOptions.h).
• Binding stress fails on seeds that previously passed. Real wire-protocol regression. Check FDB's release notes for serialization changes; if our regenerated wire types are correct but behavior diverges, the divergence is in our hand-written serializer adapter (pkg/fdbgo/wire/serializer.go) and needs a code fix.

---

Both procedures — closing checklist

• All version references updated consistently (run grep -rn "$OLD_VERSION" . and verify any remaining hits are intentional, e.g. historical context in handovers / RFCs).
• just test is green.
• git status shows only files mentioned in the procedure above (catch accidental edits).
• Commit message records WHY (matching ecosystem release / unblocking specific feature work / security fix in upstream).
• Push to the current shift branch — version bumps go through PR review like any other change. Never push directly to master.