### 23.3.7 Upgrading and Downgrading NDB Cluster

[]()[]()[]()[]()

 This section provides information about NDB Cluster software and table file compatibility between different NDB Cluster 8.0 releases with regard to performing upgrades and downgrades as well as compatibility matrices and notes. You should already be familiar with installing and configuring NDB Cluster prior to attempting an upgrade or downgrade. See [Section 23.4, “Configuration of NDB Cluster”](mysql-cluster-configuration.html).

 Schema operations, including SQL DDL statements, cannot be performed while any data nodes are restarting, and thus during an online upgrade or downgrade of the cluster. For other information regarding the rolling restart procedure used to perform an online upgrade, see [Section 23.6.5, “Performing a Rolling Restart of an NDB Cluster”](mysql-cluster-rolling-restart.html).

Important

 Only compatibility between MySQL versions with regard to [`NDBCLUSTER`](mysql-cluster.html) is taken into account in this section, and there are likely other issues to be considered. *As with any other MySQL software upgrade or downgrade, you are strongly encouraged to review the relevant portions of the MySQL Manual for the MySQL versions from which and to which you intend to migrate, before attempting an upgrade or downgrade of the NDB Cluster software*. See [Section 2.11, “Upgrading MySQL”](upgrading.html).

 The table shown here provides information on NDB Cluster upgrade and downgrade compatibility among different releases of NDB 8.0. Additional notes about upgrades and downgrades to, from, or within the NDB Cluster 8.0 release series can be found following the table.

#### Upgrades and Downgrades, NDB Cluster 8.0

[]()

**Figure 23.5 NDB Cluster Upgrade and Downgrade Compatibility, MySQL NDB Cluster 8.0**

<img alt="Graphical representation of the upgrade/downgrade matrix contained in the file storage/ndb/src/common/util/version.cpp from the MySQL 8.0 source tree." src="images/mysql-cluster-upgrade-downgrade-8-0.png" height="345" width="210" />

**Version support.**  The following versions of NDB Cluster are supported for upgrades to GA releases of NDB Cluster 8.0 (8.0.19 and later):

* NDB Cluster 7.6: NDB 7.6.4 and later

* NDB Cluster 7.5: NDB 7.5.4 and later

* NDB Cluster 7.4: NDB 7.4.6 and later

 To upgrade from a release series previous to NDB 7.4, you must upgrade in stages, first to one of the versions just listed, and then from that version to the latest NDB 8.0 release. In such cases, upgrading to the latest NDB 7.6 release is recommended as the first step.

**Known Issues.**  The following issues are known to occur when upgrading to or between NDB 8.0 releases:

* Online downgrades from NDB 8.0 to previous releases are not supported. Tables created in NDB 8.0 are not backwards compatible with previous releases. This is due to a change in usage of the extra metadata property implemented by `NDB` tables to provide full support for the MySQL data dictionary.

   For more information, see [Changes in NDB table extra metadata](mysql-cluster-what-is-new.html#mysql-cluster-what-is-new-8-0-extra-metadata). See also [Chapter 14, *MySQL Data Dictionary*](data-dictionary.html).

* In NDB 8.0, the default values changed for [`log_bin`](replication-options-binary-log.html#sysvar_log_bin) (from 0 to 1) and [`ndb_log_bin`](mysql-cluster-options-variables.html#sysvar_ndb_log_bin) (from 1 to 0). This means that you must now explicitly set `ndb_log_bin` to 1 to enable binary logging.

* Distributed privileges shared between MySQL servers as implemented in prior release series (see [Distributed Privileges Using Shared Grant Tables](https://dev.mysql.com/doc/refman/5.7/en/mysql-cluster-privilege-distribution.html)) are not supported in NDB Cluster 8.0. When started, the [**mysqld**](mysqld.html) supplied with NDB 8.0 and later checks for the existence of any grant tables which use the `NDB` storage engine; if it finds any, it creates local copies (“shadow tables”) of these using `InnoDB`. This is true for each MySQL server connected to NDB Cluster. After this has been performed on all MySQL servers acting as NDB Cluster SQL nodes, the `NDB` grant tables may be safely removed using the [**ndb\_drop\_table**](mysql-cluster-programs-ndb-drop-table.html) utility supplied with the NDB Cluster distribution, like this:

  ```
  ndb_drop_table -d mysql user db columns_priv tables_priv proxies_priv procs_priv
  ```

   It is safe to retain the `NDB` grant tables, but they are not used for access control and are effectively ignored.

   For more information about the MySQL privileges system used in NDB 8.0, see [Section 23.6.12, “Privilege Synchronization and NDB\_STORED\_USER”](mysql-cluster-privilege-synchronization.html), as well as [Section 6.2.3, “Grant Tables”](grant-tables.html).

* In NDB 8.0, the binary configuration file format has been enhanced to provide support for greater numbers of nodes than in previous versions. The new format is not accessible to nodes running older versions of `NDB`, although newer management servers can detect older nodes and communicate with them using the appropriate format.

   Upgrades to NDB 8.0 should not be problematic in this regard. When downgrading from NDB 8.0 to previous versions, because older management servers cannot read the newer binary configuration file format, some manual intervention is required. When performing such a downgrade, it is necessary to remove any cached binary configuration files prior to starting the management using the older `NDB` software version, and to have the plaintext configuration file available for the management server to read. Alternatively, you can start the older management server using the [`--initial`](mysql-cluster-programs-ndb-mgmd.html#option_ndb_mgmd_initial) option (again, it is necessary to have the `config.ini` available). If the cluster uses multiple management servers, one of these two things must be done for each management server binary.

   Also in connection with support for increased numbers of nodes, due to incompatible changes implemented in NDB 8.0 in the data node LCP `Sysfile`, it is necessary, when performing an online downgrade from NDB 8.0 to a prior NDB Cluster release, to restart all data nodes using the [`--initial`](mysql-cluster-programs-ndbd.html#option_ndbd_initial) option.

   Restarting the data nodes with [`--initial`](mysql-cluster-programs-ndbd.html#option_ndbd_initial) is also required when upgrading any release prior to NDB 7.6.4 to any NDB 8.0 release.

* Direct downgrades of clusters running more than 48 data nodes, or with data nodes using node IDs greater than 48, to earlier NDB Cluster releases from NDB 8.0 are not supported. It is necessary in such cases to reduce the number of data nodes, change the configurations for all data nodes such that they use node IDs less than or equal to 48, or both, as required not to exceed the old maximums.

* If you are downgrading from NDB 8.0 to NDB 7.5 or NDB 7.4, you must set an explicit value for [`IndexMemory`](mysql-cluster-ndbd-definition.html#ndbparam-ndbd-indexmemory) in the cluster configuration file if none is already present. This is because NDB 8.0 does not use this parameter (which was removed in NDB 7.6) and sets it to 0 by default, whereas it is required in NDB 7.5 and NDB 7.4, in both of which the cluster refuses to start with Invalid configuration received from Management Server... if `IndexMemory` is not set to a nonzero value.

   Setting `IndexMemory` is *not* required for downgrades from NDB 8.0 to NDB 7.6.

* NDB 8.0.22 adds support for IPv6 addressing for management nodes and data nodes in the `config.ini` file. To begin using IPv6 addresses as part of an upgrade, perform the following steps:

  1. Perform an upgrade of the cluster to version 8.0.22 or a later version of the NDB Cluster software in the usual manner.

  2. Change the addresses used in the `config.ini` file to IPv6 addresses.

  3. Perform a system restart of the cluster.

* Due to changes in the internal `mysql.ndb_schema` table, if you upgrade to an NDB 8.0 release prior to 8.0.24, then you are advised to use [`ndb_schema_dist_upgrade_allowed = 0`](mysql-cluster-options-variables.html#sysvar_ndb_schema_dist_upgrade_allowed) to avoid unexpected outages (Bug #30876990, Bug #31016905).

* If you are using multithreaded data nodes ([**ndbmtd**](mysql-cluster-programs-ndbmtd.html)) and the [`ThreadConfig`](mysql-cluster-ndbd-definition.html#ndbparam-ndbmtd-threadconfig) configuration parameter, you may need to make changes in the value set for this in the `config.ini` file when upgrading from a previous release to NDB 8.0.30 or later. When upgrading from NDB 8.0.23 or earlier, any usage of `main`, `rep`, `recv`, or `ldm` threads that was implicit in the earlier version must be explicitly set. When upgrading from NDB 8.0.23 or later to NDB 8.0.30 or later, any usage of `recv` threads must be set explicitly in the `ThreadConfig` string. In addition, to avoid using `main`, `rep`, or `ldm` threads in NDB 8.0.30 or later, you must set the thread count for the given type to `0` explicitly.

   An example follows.

  *NDB 8.0.22 and earlier*:

  * `config.ini` file contains `ThreadConfig=ldm`.

  * This is interpreted by these versions of `NDB` as `ThreadConfig=main,ldm,recv,rep`.

  * Required in `config.ini` to match effect in NDB 8.0.30 or later: `ThreadConfig=main,ldm,recv,rep`.

  *NDB 8.0.23—8.0.29*:

  * `config.ini` file contains `ThreadConfig=ldm`.

  * This is interpreted by these versions of `NDB` as `ThreadConfig=ldm,recv`.

  * Required in `config.ini` to match effect in NDB 8.0.30 or later: `ThreadConfig=main={count=0},ldm,recv,rep={count=0}`.

   For more information, see the description of the [`ThreadConfig`](mysql-cluster-ndbd-definition.html#ndbparam-ndbmtd-threadconfig) configuration parameter.

