Upgrade to Database 7.1

This page describes how to upgrade to Aerospike Database 7.1 from 7.0.x versions. If you are upgrading from versions prior to 6.0, see Upgrade from pre-6.0 versions.

Overview

Aerospike Database 7.1 handles the flushing of partially full write-blocks in a more IO-efficient way, when per-device throughput is too low to fill the write-block before the flush-max-ms has elapsed. Instead of writing the entire write-block with padding, it writes the most recent records in flush-size units (only the last flush-size unit will have any padding), appended to previously written data in the write-block. Once the write-block is full it gets no further writes and gets moved to the post-write queue.

As a result, the write-block-size configuration parameter has been removed, pinned to 8MiB, and you should edit it out of your namespace configuration. To maintain similar device IO patterns the new flush-size configuration parameter has a default 1MiB value. If you had explicitly set write-block-size in your configuration file, we suggest that you start by explicitly setting flush-size to this value. If your workload is dominated by partial writes you should consider setting it smaller, for example to 128K or smaller. As opposed to write-block-size, which was static and could only be increased, flush-size can be dynamically modified, and can be increased or decreased.

Similarly, you must replace any explicit post-write-queue configuration settings, expressed in multiples of the write-block-size with a post-write-cache, expressed in real bytes per-device (M for MiB, K for KiB, etc). Finally, we recommend that you explicitly use the max-record-size, matching it to a value up to your previous max-record-size. Its default value is 1MiB as of Database 7.1.

Caution

Starting in Database 7.1, map keys are restricted to simple types — integer, string, and blob. If your database was built with an earlier version, use asvalidation version 2.0.0 or later to search for map data with invalid map keys, and change your applications and data before you upgrade to 7.1. In 7.1 and later, any application write operation attempt using a map element with a list, map, geospatial, double, or boolean data type as its map key will be rejected.

Pre-upgrade tasks

1. (Optional) - Upgrade to Monitoring Stack 3.0 (Grafana and Prometheus Exporter) or later.

2. Download the Database 7.1 software from the download page.

3. Install the latest version of Aerospike Tools. You need asadm and asconfig from Aerospike Tools 10.1 or later to use the following steps.

Upgrade

1. Make a copy of your current configuration file.

2. Run asvalidation 2.0.0 or later to scan your data for map bins with unsupported map-key types. If found, change your applications to use a supported map-key data type — integer, string, or blob — before upgrading.

3. Run the following command to generate a configuration file which includes all dynamic configuration of the running node, and convert the config file to YAML. You can also specify the output location of the generated config and YAML files.

   Tip

   You can get a list of invalid configuration details by running the following command.

   asadm -h 172.17.1.4  -e 'generate config with 172.17.1.4' | asconfig validate -a '7.1.0'

4. Verify that the configuration file contains the correct cluster name that you specified.

5. Make the required changes.

6. Install Database 7.1 from the package you downloaded.

7. Restart the Aerospike node. Once the node joins the cluster you can configure the next cluster node. If the nodes use exactly the same configuration, you can reuse the previous configuration information.

   Note

   You must upgrade all nodes in the cluster before deploying applications that explicitly persist Map indexes (a Database 7.1 feature).

Upgrade from pre-6.0 versions

Tip

Always review the special upgrade instructions of the interim server releases between the current version of your cluster and the target version.

• Before you upgrade from Database 4.9 or 5.x, follow the instructions in Storage Format Upgrade in 6.0 Release.
• Back up /opt/aerospike/smd/security.smd in your system metadata (SMD) Directory Structure and aerospike.conf, the Aerospike configuration file.
• Find and fix any secondary index (sindex) names that are longer than 64 characters. See Upgrade to Database 6.1.
• If you are an Enterprise Edition customer, ensure that your feature-key file has the explicit feature keys needed in Database 6.3 and later.

Changes and updates

For information about new features, breaking changes, and late breaking news, see the 7.1 server release notes.