Clairification about version compatibility between client and server

Using FoundationDB
1

Hey folks, in the docs, there is this bit about API versioning:

In general, a given client will support both its corresponding API version and earlier API versions . A client selects the API version it will use by explicitly specifying the version number upon initialization. The purpose of this design is to allow the server, client libraries, or bindings to be upgraded without having to modify application code. You can therefore upgrade to more recent packages (and so receive their various improvements) without having to change application code.

I took this to mean that I could upgrade clients to newer versions and have them connect to servers running older versions by specifying the older API version. Concretely, I tested this setup:

  • Server is running 7.1.67
  • Java client is using fdb-java version 7.3.67
  • libfdb_c.so version is 7.3.67
  • We specify API version of 710

But our Java application reported the cluster as unreachable. When I changed the fdb-java and libfdb_c.so versions to 7.1.67, then I was able to connect to the cluster.

Am I interpreting the docs incorrectly? Would it suffice for us to include both 7.1.67 and 7.3.67 versions of libfdb_c.so, configure multi version clients, and keep everything else the same?

2

Hi, answer is a bit late, but since we went through the same issue, it might help futures people reading this.

It doesn’t seem that FoundationDB clients are able to be backward compatible at MINOR (nor major) level. It seems to be only valid for PATCH. I’m not aware of the reason behind it, but from the client perspective, you see that a FDB client version hash (e.g. 0x0FDB00B071010000 for 7.1, 0x0FDB00B073000000 for 7.3) is checked against this mask 0xFFFFFFFFFFFF0000, only approving protocol versions that are not minor / major. Those hashes can be found in ProtocolVersion.h.

3

I believe the multi version client should work as described in the original post. Without downloading the FDB C lib of the cluster you’d like to connect to and configuring the client as such, it would not work. There was some ideas in the past about downloading the lib from the coordinators or from a blob store but I don’t think that went anywhere…

4

After some experimentation, we were also able to determine what works, and these are the “rules” that we’ve gone with:

  • You must always have the C library major and minor version that matches the server (e.g. 7.1). I think patch version differences are OK
  • Your language binding minor version can be older than the C library version.

So for example, we tested this configuration and it worked:

  • Server version 7.3.62
  • C library version 7.3.62
  • Python language binding version 7.1.60

The API version reported by the binding is 710, but we can connect to the cluster and perform operations.

The multi version client thing did work well for us, and that is how we conducted our upgrade from 7.1 to 7.3.

3 Likes