API Version Upgrade Guide

Overview

This document provides an overview of changes that an application developer may need to make or effects that they should consider when upgrading the API version in their code. For each version, a list is provided that details the relevant changes when upgrading to that version from a prior version. To upgrade across multiple versions, make sure you apply changes from each version starting after your start version up to and including your target version.

For more details about API versions, see :ref:`api-versions`.

API version 700

API version 620

C bindings

fdb_future_get_version has been renamed to fdb_future_get_int64.

API version 610

General

The concept of opening a cluster has been removed from the API. Instead, databases are opened directly. See binding specific notes for the details as they apply to your language binding.
The TIMEOUT, MAX_RETRY_DELAY, and RETRY_LIMIT transaction options are no longer reset by calls to onError.
Calling onError with a non-retryable error will now put a transaction into an error state. Previously, this would partially reset the transaction.
The TRANSACTION_LOGGING_ENABLE option has been deprecated. Its behavior can be replicated by setting the DEBUG_TRANSACTION_IDENTIFIER and LOG_TRANSACTION options.

C bindings

Creating a database is now done by calling fdb_create_database, which is a synchronous operation.
The FDBCluster type has been eliminated and the following functions have been removed: fdb_create_cluster, fdb_cluster_create_database, fdb_cluster_set_option, fdb_cluster_destroy, fdb_future_get_cluster, and fdb_future_get_database.

Python bindings

fdb.open no longer accepts a database_name parameter.
Removed fdb.init, fdb.create_cluster, and fdb.Cluster. fdb.open should be used instead.

Java bindings

FDB.createCluster and the Cluster class have been deprecated. FDB.open should be used instead.

Ruby bindings

FDB.open no longer accepts a database_name parameter.
Removed FDB.init, FDB.create_cluster, and FDB.Cluster. FDB.open should be used instead.

Go bindings

Added fdb.OpenDatabase and fdb.MustOpenDatabase to open a connection to the database by specifying a cluster file.
Deprecated fdb.StartNetwork, fdb.Open, fdb.MustOpen, and fdb.CreateCluster. fdb.OpenDatabase or fdb.OpenDefault should be used instead.

API version 600

General

The TLS_PLUGIN option is now a no-op and has been deprecated. TLS support is now included in the published binaries.

API version 520

General

The SET_VERSIONSTAMPED_KEY atomic operation now uses four bytes instead of two to specify the versionstamp offset.
The SET_VERSIONSTAMPED_VALUE atomic operation now requires a four byte versionstamp offset to be specified at the end of the value, similar to the behavior with SET_VERSIONSTAMPED_KEY.
The READ_AHEAD_DISABLE option has been deprecated.

Java and Python bindings

Tuples packed with versionstamps will be encoded with four byte offsets instead of two.

API version 510

General

The atomic operations AND and MIN have changed behavior when used on a key that isn't present in the database. Previously, these operations would set an unset key to a value of equal length with the specified value but containing all null bytes (0x00). Now, an unset key will be set with the value passed to the operation (equivalent to a set).

Java bindings

Note: the Java bindings as of 5.1 no longer support API versions older that 510.
The Java bindings have moved packages from com.apple.cie.foundationdb to com.apple.foundationdb.
The version of the Java bindings using our custom futures library has been deprecated and is no longer being maintained. The Java bindings using CompletableFuture are the only ones that remain.
Finalizers now log a warning to stderr if an object with native resources is not closed. This can be disabled by calling FDB.setUnclosedWarning().
Implementers of the Disposable interface now implement AutoCloseable instead, with close() replacing dispose().
AutoCloseable objects will continue to be closed in object finalizers, but this behavior is being deprecated. All AutoCloseable objects should be explicitly closed.
AsyncIterator is no longer closeable.
getBoundaryKeys() now returns a CloseableAsyncIterable rather than an AsyncIterator.