MySQL NDB Cluster API Developer Guide  /  NDB Cluster APIs: Overview and Concepts  /  NDB Cluster API Overview: Version Compatibility

1.2 NDB Cluster API Overview: Version Compatibility

The NDB API is now fairly mature, and has undergone few major changes in recent releases. Where they have occurred, such changes are indicated in the documentation of the affected objects and methods.

The API version of an NDB API application is determined by the version of libndbclient the application uses to provide NDB API functionality. Because it is necessary to support rolling upgrades, we perform basic testing across a number of versions (7.5 through 8.2) with regard to both older API versions connecting to data nodes of newer versions, and newer API versions connecting to data nodes of older versions. We no longer perform such testing with releases prior to NDB 7.5, since these are no longer maintained or supported in production.

In addition, in NDB 8.0, some compatibility has been dropped with API versions prior to 7.5, but is retained with versions 7.5 and 7.6.

When new a new feature is added to NDB, this is generally done in such a way that the new functionality includes checking that the data nodes which are currently connected are running versions which support the feature. This is done to guard against accidental use of the new feature during a rolling upgrade before the cluster is fully upgraded to the version adding support for it.

In the event that an application employing a newer version of the NDB API is run against an older cluster which does not support a newer feature used by the application, the application raises error code 4003 Function not implemented yet when trying to make use of the feature. Other errors are possible depending on the new functionality involved (see Section 2.4.2, “NDB Error Codes: by Type”).

When an application using an older version of libndbclient connects to a cluster running a newer version of NDB, the data nodes should support older API calls, but there other considerations as well. In particular, if the schema on the cluster makes use of newer features not supported by the older API version does not support, it is possible that operations may be less than optimal or give rise to errors. Some examples are listed here:

  • There are tables in the cluster using the JSON data type, which is unknown to NDB prior to version 7.5

  • The cluster uses one or more fully replicated tables, which are not supported in NDB prior to version 7.5

  • The cluster includes tables using generated columns, which are unsupported in NDB prior to version 7.5

When upgrading a cluster online (that is, by using a rolling restart), existing table schemas are preserved, thus avoiding activation of new schema features too early. This is not the case when the upgrad recreates the schema and restores all data, when the new version may by default use new schema features. For this reason, it is best practice to test with specific schemas, operations, and versions prior upgrading a production system to catch any problems that may arise when connecting an older application or SQL node to a cluster running a newer version of NDB.

For information about general requirements for compiling NDB API and MGM API applications, see Section, “General Requirements”.