Special upgrade instructions for Aerospike Server 6.1

Important pre-upgrade considerations

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 server 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 below.
  • An alternative is to set up another cluster, but this is not the most common way to upgrade your system. For more details see How to Migrate Data from an existing Aerospike Cluster to an empty Cluster.

Secondary Index name limit reduced to 64 characters

Starting in server 6.1, secondary index (sindex) names are limited to 64 characters - down from 256. The server does not create any sindex that exceeds the limit, and logs a warning.

Mitigation - Find and fix sindex names that are too long

Before you upgrade, find any secondary index names that exceed the new 64-character limit (including a null terminator), delete them, then recreate the sindex with a shorter name after the upgrade

Example

Admin+> show sindex 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Secondary Indexes (2022-08-12 00:36:08 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                                                       Index Name|Namespace| Set| Bin|    Bin|  Index|State
                                                                 |         |    |    |   Type|   Type|     
age-index                                                        |test     |demo| age|NUMERIC|DEFAULT|RW   
this_sindex_name_is_over_64_characters_and_fail_being_made_in_6.1|test     |demo|name|STRING |DEFAULT|RW   
Number of rows: 2

Admin> manage sindex delete this_sindex_name_is_over_64_characters_and_fail_being_made_in_6.1 ns test                         
Successfully deleted sindex this_sindex_name_is_over_64_characters_and_fail_being_made_in_6.1.
Admin> manage sindex create string name-idx ns test set demo bin name                                                         
Successfully created sindex name-idx.

Admin+> show sindex                                                                                   
~~~~Secondary Indexes (2022-08-12 00:39:06 UTC)~~~~
    Index|Namespace| Set| Bin|    Bin|  Index|State
     Name|         |    |    |   Type|   Type|     
age-index|test     |demo| age|NUMERIC|DEFAULT|RW   
name-idx |test     |demo|name|STRING |DEFAULT|RW   
Number of rows: 2

Secondary Index without a set name now indexes the entire namespace

Starting in server 6.1, a sindex defined without a set-name will index the entire namespace, not just the set of records without a set-name. This adds the ability to index the entire namespace, and is another step to normalize primary index (PI) and secondary index (SI) queries.

caution

This change may require you to change your applications.

Example: Add sindex without a set name

Admin+> manage sindex create numeric last-updated ns test bin updated                                                                      
Successfully created sindex last-updated.
Admin+> show sindex                                                  
~~~~~~~Secondary Indexes (2022-08-12 00:42:05 UTC)~~~~~~~
  Index Name|Namespace| Set|    Bin|    Bin|  Index|State
            |         |    |       |   Type|   Type|     
last-updated|test     |NULL|updated|NUMERIC|DEFAULT|RW   
age-index   |test     |demo|    age|NUMERIC|DEFAULT|RW   
name-idx    |test     |demo|   name|STRING |DEFAULT|RW   
Number of rows: 3

In Aerospike server versions prior to 6.1, a query against this last-updated secondary index will only return records that are in no set (meaning the records of set demo will not appear in the query results).

In Aerospike server version 6.1 and later, a query against this last-updated secondary index will return all the records in the namespace.