Skip to main content
Loading

Single-Bin Namespace Upgrade to Aerospike Server 6.4

This page describes how to migrate a single-bin namespace to a new cluster.

Single-bin namespace storage configurations were removed from Aerospike server 6.4 as prerequisite work for upcoming server 7.0 features. As a result, the presence of single-bin or data-in-index configuration parameters in the Aerospike configuration file will prevent a cluster node from starting up.

info

If you do not have single-bin namespaces in your cluster, you can upgrade to server 6.4 with a regular rolling upgrade.

Rolling upgrades from single-bin namespaces into server 6.4 nodes will fail​

If you upgrade a cluster node to version 6.4 or later and remove the single-bin configuration parameter you will see one of the following failures.

Upgrading a single-bin namespace with data on SSD​

The node will not start up after being upgraded to version 6.4.

Aug 01 2023 10:51:53 GMT: CRITICAL (drv_ssd): (drv_ssd_ee.c:1600) device has 'single-bin' data but 'single-bin' is no longer supported
Aug 01 2023 10:51:53 GMT: WARNING (as): (signal.c:113) SIGUSR1 received, aborting Aerospike Enterprise Edition build 6.4.0.0-rc4 os ubuntu22.04 arch x86_64 sha f964a94 ee-sha 2a4fa32
Aug 01 2023 10:51:53 GMT: WARNING (as): (log.c:706) stacktrace: registers: rax 0000000000000000 rbx 00007f6f61b16180 rcx 00007f6f62544a7c rdx 000000000000000a rsi 0000000000000220 rdi 0000000000000220 rbp 0000000000000220 rsp 00007ffc7bd97c90 r8 00005631036ffb28 r9 00007ffc7bd97d60 r10 00007ffc7bd97554 r11 0000000000000246 r12 000000000000000a r13 0000000000000016 r14 000000000000000a r15 00007ffc7bd97d60 rip 00007f6f62544a7c
Aug 01 2023 10:51:53 GMT: WARNING (as): (log.c:718) stacktrace: found 16 frames: 0x332d7b 0x1457eb 0x7f6f624f0520 0x7f6f62544a7c 0x7f6f624f0476 0x331833 0x1d040c 0x1da0b8 0x1dbd56 0x1dd3e1 0x1e006e 0xcde6a 0xaae53 0x7f6f624d7d90 0x7f6f624d7e40 0xabd95 offset 0x5631031c6000

Upgrading a single-bin namespace with data in memory​

The node will rejoin the cluster on startup, but migrations onto the new node will fail.

Jul 27 2023 06:57:46 GMT: WARNING (bin): (bin.c:126) vmap err 1 - can't add new bin name ''
Jul 27 2023 06:57:46 GMT: WARNING (flat): (flat.c:330) flat bin name failed to assign id
Jul 27 2023 06:57:46 GMT: WARNING (record): (record.c:477) {test} record replace: failed unpickle bins 0ba0b2a2311c35af59b964f03c7da19165344226

The server 6.4 node cannot accept records being migrated from the single-bin namespace, so a rolling restart will not work.

danger

If you use single-bin namespaces, migrate them to a new Aerospike cluster, either using cross-datacenter replication (XDR) or by restoring from a backup.

Migrate the single-bin namespace to a new cluster​

The easiest way to migrate out of a single-bin namespace involves streaming it with XDR to an empty namespace on a server 6.4 cluster.

Aerospike Community Edition (CE) users can modify their applications to write to both the old and new cluster, then take a backup and restore it to the new server 6.4 cluster.

For more details see How to Migrate Data from an existing Aerospike Cluster to an empty Cluster.

Characteristics of a migrated (previously) single-bin namespace​

Once a previously single-bin namespace has been migrated to a new Aerospike cluster with nodes at server version 6.4 or later, it has the following characteristics.

  1. The migrated records will have an empty string bin name. The bin can be accessed using the bin name "".
  2. Applications that worked with single-bin will continue to work.
  3. New bins can be added to the records in these namespaces, with a unique bin name.
  4. Depending on the data type of the single bin, the converted namespace may consume more storage. See the capacity planning guide for more information.
  5. Secondary indexes cannot be created on the empty string bin name.
  6. You cannot choose XDR bin shipping while the namespace records have the empty-string bin name. The bin-policy must be all (the default setting).

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 Upgrade to Server 6.1.
  • If you're an Enterprise Edition customer, ensure that your feature-key file has the explicit feature keys needed in server 6.3 and later.

Changes and updates​

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