Skip to main content

Backward Incompatible API Changes

Version 2.9.0

Changed Default for send_key Policy

The default value for the send_key write policy has changed from true to false. I.e. by default, the client only sends the record digest to the server on writes and no longer sends the user key.

The default send_key policy can be set through the global client policy:

require "aerospike"
include Aerospike

policy =
policies: {
write: true)
client = policy)

Version 2.6.0

Supported Ruby versions

The minimum required Ruby version is Ruby 2.3. Older versions of Ruby are no longer supported.

Version 2.0.0

Integer Key Digest Incompatibility

The v1 client was computing the key digest for record keys with integer values in a manner incompatible with all other Aerospike Client SDKs. Instead of converting the integer values into binary format using big endian byte order before computing the digest the Ruby v1 client was using little endian byte order. Therefore the resulting hash values were different and as a result, a database record with an integer key written using the Ruby v1 client could not be retrieved by any other Aerospike client and vice versa.

The Ruby v2 client fixes this. However that means that the digests for integer keys created with the v1 client and the v2 client necessarily differ. Database records with integer keys written by the v1 client cannot be retrieved using the v2 client in its default configuration.

The Ruby v2 client has a setting to restore backward compatibility with the Ruby v1 client. (At the cost of continued incompatibiliy with all other Aerospike clients libraries.) There are two options to enable v1 compatible digest computation.

To enable v1 compatibility globally for all integer keys generated by the v2 client use the Aerospike::Key.enable_v1_compatibility! class method:

k1 ='test', 'demo', 42)
puts k1.digest.unpack("H*") # => cf5a1365effa4dc53333f2166d103358f8711096
k2 ='test', 'demo', 42)
puts k2.digest.unpack("H*") # => 0de7a87b3db745e84c7571d947c4b038bb735760

To create only specific keys using v1 compatible digest, set the v1_compatible flag to true when initializing a new key instance:

k1 ='test', 'demo', 42)
puts k1.digest.unpack("H*") # => cf5a1365effa4dc53333f2166d103358f8711096
k2 ='test', 'demo', 42, v1_compatible: true)
puts k2.digest.unpack("H*") # => 0de7a87b3db745e84c7571d947c4b038bb735760

Client Initializer

The client initializer has been updated to accept multiple hostnames. The hostnames can be passed either in the form of Aerospike::Host objects or as a string of comma separated hostnames. If no hosts are specified, the v2 client will attempt to read the hostnames from the AEROSPIKE_HOSTS environment variable. Last, the client will default to the address "localhost:3000".

Client policy settings need to be passed as a hash to the policy: named parameter.

The new connect: named paramter can be set to false to prevent the client from connecting to the cluster immediately. The connection can be established later using the Client#connectx method.

Here is the new method signature:

def initialize(hosts = nil, policy:, connect: true)

Usage examples:

Specifying a single host seed address:

host ="", 3000)
client =

Specifying a list of host addresses:

client =",")

Using AEROSPIKE_HOSTS to set the hostnames:

client =

Setting a client policy:

client = { timeout: 0.2 })

Aerospike::Client.new_many has been removed as the regular new method can now accept multiple hostnames.

Supported Ruby versions

Ruby 1.9.3 is no longer supported. Ruby 2.0 or later are requried to use Aerospike Ruby client v2.0.