Skip to content

Latest commit

 

History

History
96 lines (69 loc) · 3.55 KB

api-changes.md

File metadata and controls

96 lines (69 loc) · 3.55 KB
Raw

Backward Incompatible API Changes

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 = Aerospike::Key.new('test', 'demo', 42)
puts k1.digest.unpack("H*")                   # => cf5a1365effa4dc53333f2166d103358f8711096
Aerospike::Key.enable_v1_compatibility!
k2 = Aerospike::Key.new('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 = Aerospike::Key.new('test', 'demo', 42)
puts k1.digest.unpack("H*")                   # => cf5a1365effa4dc53333f2166d103358f8711096
k2 = Aerospike::Key.new('test', 'demo', 42, v1_compatible: true)
puts k2.digest.unpack("H*")                   # => 0de7a87b3db745e84c7571d947c4b038bb735760

Client Initializer

The client initializer Aerospike::Client.new 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: ClientPolicy.new, connect: true)

Usage examples:

Specifying a single host seed address:

  host = Aerospike::Host.new("127.0.0.1", 3000)
  client = Aerospike::Client.new(host)

Specifying a list of host addresses:

  client = Aerospike::Client.new("10.0.0.1:3000,10.0.0.2:3100")

Using AEROSPIKE_HOSTS to set the hostnames:

  ENV["AEROSPIKE_HOSTS"] = "192.168.10.10:3000"
  client = Client.new

Setting a client policy:

  client = Client.new(policy: { 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.