Aerospike Server Community Edition 8.2.0.0

September 29, 2026  |  Download

New in this version

• Support for Ubuntu 26.04 LTS
• Preview startup flag (--preview) replaces --experimental
• List join (8.2.0) — concatenates list-of-strings elements; inverse of string split
• Blob b64_encode (8.2.0) — encodes blob to string; pairs with string b64_decode
• Structured server error details such as subcodes, messages, and expression traces

Developer experience

• String operations: 35 server-side read, modify, and conversion functions using the Operate API and expressions. Uses Unicode codepoints for index positions. See the string operations overview and operations reference.

• UTF-8 validation at string operation boundaries: String operations reject invalid UTF-8 with AS_ERR_INVALID_ENCODING. Standard writes still accept it and trigger a rate-limited warning. See Upgrade to Database 8.2.0 and later.

• ICU regular expressions: String regex_compare and regex_replace, the Aerospike expression language (AEL) =~ match operator, and regexReplace() compile patterns with ICU syntax, not PCRE or legacy POSIX cmp_regex syntax. Unsupported constructs are rejected at parse time. Replace operations use ICU's replacement dialect (capture references such as $1 and ${name}, $0, and \ escapes); an unresolvable $ fails the operation on any record the pattern matches, and is never evaluated on one it does not. Patterns that exceed ICU evaluation limits return AS_ERR_OP_NOT_APPLICABLE with AS_SUB_OPNOT_STRING_REGEX_LIMIT_EXCEEDED. See Regular expression syntax.

• Query optimizer: Database 8.2.0 adds a server-side query optimizer for automatic secondary index (SI) selection on AEL predicates.

  • Default behavior: A Developer SDK query with a where clause that finds no matching SI can fail with AS_ERR_SINDEX_NOT_FOUND (201) rather than reading every record, controlled per query or per Behavior by allowScansWithWhere. Queries without a where clause, background queries, and aggregations are unaffected.
  • Fallback option: Enable allowScansWithWhere to allow explicit fallback to primary index (PI) queries.
  • A query that carries no AEL and names no index runs against the primary index, as before. See Query optimizer.

• Unordered Map comparison in expressions: Expressions now support comparing unordered Maps, including equality comparisons. See Map comparison.

• Integer secondary index type name: Renamed the integer secondary index key type from numeric to integer for clarity. numeric is now deprecated but remains supported as an alias.

  • Usage: Specify integer with sindex-create and manage sindex create in asadm.
  • Existing indexes: No re-index required. Existing integer indexes continue to work.
  • API and command outputs:
    • sindex-list outputs type=integer when using v=v2 (v1 retains numeric for backward compatibility)
    • show sindex may still show numeric in the Bin Type column.
  • Client and deprecation behavior: Language client createIndex() APIs sending numeric on the wire will still be accepted. However, using numeric logs a warning and increments the deprecated_requests metric.

• Structured error details (Database 8.2.0 and later): Failed operations can now return extended error context based on a configurable verbosity level:

  • Level 1: Numeric subcode (scoped to parent status).
  • Level 2: Subcode + human-readable message.
  • Level 3: Subcode + message + expression trace (for expression failures).
  • Configuration: Opt-in per request via client policy (errorDetailVerbosity / error_detail_verbosity). Default is 0 (disabled), preserving existing application behavior.
  • Best Practice: Applications must dispatch error handling on the (status, subcode) pair, not subcode alone.
  • Coverage: Supported on single-record ops, batch (per-record), expressions, CDT, HLL, bitwise, string ops, transactions, and client-invoked UDFs.
  • Exclusions: Background UDF/operate jobs, batch-wide admission errors, and queries that fail after start.

Performance enhancements

• Wire compression (Enterprise Edition): Added Zstd compression for intra-cluster traffic to reduce cross-AZ (Availability Zone) network costs.
  • Supported traffic: Replica writes, partition migrations, and SMD full-sync messages.
  • Delta mode: Replica writes support delta encoding, transmitting only changed bytes against the prior record version
  • Configuration: Opt-in per transport and dynamically configurable without restarts. See Configure wire compression and Configure SMD wire compression.

Operations

• Improved memory over-configuration warning: The startup and dynamic-configuration memory best-practice check compares the configured maximum DRAM footprint, including indexes-memory-budget, in-memory data-size, and full max-write-cache and post-write-cache sizes, against the budget defined by stop-writes-sys-memory-pct, rather than comparing only in-memory data and index budgets to total system RAM. See Namespace memory budget.

• Wire compression metrics: Per-channel fabric byte counters, available in both editions, plus the Enterprise-only per-namespace replication and migration compression savings, delta-mode hit rates, and codec CPU percentages help you tune compression modes and levels. Query zstd-wire-stats for codec call counts and CPU; smd-info for SMD compression stats. Per-operation CPU percentages require enable-benchmarks-wire-compression. See the Metrics reference.

• Index checkpoint (Enterprise only, preview): Optional per-namespace durable copy of shared memory indexes for warm restart after a container replacement or host reboot. Enable with --preview index-checkpoint and per-namespace configuration. See Index checkpoint.

• SMD readiness on node join: A new or returning node completes its initial system metadata (SMD) sync before it accepts client or admin connections, and before it receives incoming record migrations. There is no configuration. See Upgrade instructions for rolling-upgrade behavior.

• Preview startup flag (--preview): Database 8.2.0 and later reject --experimental and require --preview to enable preview features by name. In this release, valid feature names are yaml-config (YAML configuration files) and index-checkpoint (index checkpoint). On Database 8.1.1 and 8.1.2, continue using --experimental for YAML configuration.

Breaking changes

CDT nesting depth limited to 64 levels

Starting with Aerospike Database 8.2.0, Lists and Maps support up to 64 levels of nesting. A top-level List or Map counts as level 1, and each nested List or Map adds one level. Keep collection values within this limit.

This change can affect data that predates this release when that data re-enters the server over the wire, such as:

• A client read-modify-write round trip on an existing List or Map nested deeper than 64 levels
• XDR shipping such a record to a destination running Database 8.2.0 or later
• Restoring a backup that was taken before the upgrade

The server checks the nesting depth of each List or Map value in a request: whole-bin writes, CDT operation values, and expression literals. It does not re-check values already stored, so an ordinary read of a List or Map stored deeper than 64 levels returns it unchanged.

The client receives the message text only when the request sets error detail verbosity to 2 or higher. Otherwise, the client receives the status code alone.

See Nesting depth limit to learn how depth is counted.

allow-unsafe-lua now defaults to false

Database 8.2.0.0 changes the default of mod-lua.allow-unsafe-lua from true to false, making Lua sandbox hardening the default. Hardened mode removes risky Lua globals (os, io, debug, dofile, loadfile, load, loadstring), blocks native .so and precompiled bytecode UDFs, and requires the lowercase .lua extension at registration.

:::caution
Before upgrading, audit your registered UDFs against the migration checklist. A UDF that depends on the removed functions or module formats breaks after upgrade unless you set allow-unsafe-lua true first.
:::

To keep the permissive behavior after upgrading, set mod-lua.allow-unsafe-lua to true and restart each node.

:::note
Database 8.1.2.x, 8.0.0.x, 7.2.0.x, and 7.1.0.x are unaffected and continue to default to true.
:::

See UDF security and sandbox hardening for the full behavior change and migration checklist.

Platform updates

• Database 8.2.0 adds support for Ubuntu 26.04 LTS, including OpenSSL 3.5 compatibility on that platform. Ubuntu 26.04 requires Database 8.2.0 or later.

• Database 8.2.0 build artifacts are not provided for Debian 12 (Bookworm). See Platform support and compatibility.

• Database 8.2.0 build artifacts are not provided for Ubuntu 22.04 LTS (Jammy Jellyfish). See Platform support and compatibility.

• On Ubuntu 24.04 and 26.04, install libcurl4t64. See Install on Linux, Install on Google Cloud, and Platform support and compatibility.

Upgrade instructions

You can upgrade directly to Database 8.2.0 from releases 7.1.0.x through 8.1.2.x.

• For upgrade instructions, see Upgrade or repair an Aerospike server.
• For special upgrade instructions, see Special upgrades and downgrades.

Rolling upgrades:

• Wire compression is opt-in and disabled by default. There is nothing to do at upgrade time.

  • Replica-write and SMD compression start only after every node in the cluster is Database 8.2.0 or later.
  • Migration compression can be used between two upgraded nodes during a rolling upgrade. Support is negotiated separately for each migration peer.

• SMD readiness (new in Database 8.2.0):

  • The wait arms only when every node in the cluster is Database 8.2.0 or later, so during a rolling upgrade only the last node you upgrade waits.
  • While a node waits, client requests, asinfo, and asadm against that node time out rather than being refused. The rest of the cluster defers its incoming migrations until it is ready.
  • The node is ready when its log shows initial SMD sync done for cluster key <key>. A still waiting for initial SMD sync warning repeating every 10 seconds is expected until then. See System metadata readiness on node join.

Reference and error code updates

The following tables outline the latest reference updates for configurations, info commands, metrics server logs, and error messages.

Configuration updates

Info command updates

Metrics updates

Server log updates

Error code updates

Known issues

Known issues for 8.2.0

Documentation updates

• String examples
• String operations reference
• Regular expression syntax
• String operations reference
• Query optimizer
• Secondary index queries
• Namespace memory budget
• Metrics reference
• Index checkpoint
• Warm restart
• Quiesce a node
• Configure Aerospike Database
• Aerospike Daemon CLI options
• Configure wire compression
• Configure SMD wire compression
• System metadata readiness on node join
• Server error details
• Error subcodes

Complete list of changes