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."
If the user passes a target version (e.g. /upgrade-versions java 4.12.0.0), use it. Otherwise:
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.
-
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.
-
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.
-
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",
-
Run bazel mod tidy to refresh the resolved Maven dep set:
bazelisk mod tidy
-
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 proto/apple/. Skip BUILD.bazel (it lives only on our side).
for f in $(diff -q proto/apple/ fdb-record-layer/fdb-record-layer-core/src/main/proto/ \
| awk '/and.*differ/ {print $2}' | xargs -n1 basename); do
cp "fdb-record-layer/fdb-record-layer-core/src/main/proto/$f" "proto/apple/$f"
done
Read the diff before committing: pure additive changes (new fields / messages / enum values) are safe; renames or removals require code-side adjustments.
-
Regenerate Go proto code.
just generate
Then run just gazelle to update BUILD files if any new files appeared.
-
Update prose references. Two files mention the version explicitly:
CLAUDE.md — the "Java source reference" section. Update the tag and Maven artifact mention.TODO.md — the header line "Java Record Layer version: X.Y.Z.W".
-
Build + test.
just build
just test
The conformance test (//conformance:conformance_test) is the canary — if proto sync is wrong, it fails with NoSuchFieldError: ... PXxx_descriptor from a static initializer in fdb-relational-core, then cascades into HTTP timeouts as the Java server is left in a half-initialized state. Resolve by re-syncing the offending proto file from the submodule.
-
Commit. All proto changes + regenerated gen/*.pb.go + MODULE.bazel + prose files in one commit. Short title (upgrade Java record-layer to $VERSION) plus a body that records WHY the bump (matching ecosystem release, unblocking specific work).
-
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
-
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.
-
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"],
-
Bump .bazelrc.
test --test_env=FDB_VERSION=$VERSION
-
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/.
-
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 $VERSION.
-
Build + test.
just build
just test
The pure-Go client tests (//pkg/fdbgo/client:client_test) run against an FDB Docker container at $VERSION. If the wire format changed in a way the regenerated types don't capture, those tests fail with parse errors or unexpected error codes. Investigate by:
- reading the FDB release notes for the version delta;
- re-running the schema extractor manually to capture stderr (
bazelisk run //cmd/fdb-schema-extract);
- comparing one or two regenerated
*_generated.go files by hand against the previous version.
-
Run the binding stress for one seed as a smoke test:
just binding-stress 1 100
The binding tester's Python reference client compares against our Go stack — wire-format drift surfaces here even if the regular tests pass.
-
Commit. Bundle MODULE.bazel + .bazelrc + regenerated *_generated.go + prose files. Short title (upgrade FDB C++ to $VERSION) plus a body that calls out: any new wire types added, any behavior changes in the release notes that affect us, binding-stress smoke result.
