Skip to content

Latest commit

 

History

History
323 lines (256 loc) · 13 KB

policies.md

File metadata and controls

323 lines (256 loc) · 13 KB
Raw

Policies

Policies provide the ability to modify the behavior of operations.

This document provides information on the structure of policy objects for specific operations and the allowed values for some of the policies.

Objects

Policy objects are classes which define the behavior of associated operations.

When invoking an operation, you can choose:

  • pass nil as policy. A relevant default policy will be used.
  • pass policy in method options; e.g. :ttl => 1
  • Generate the relevant policy object directly and pass it instead of the options parameter.

Examples

Using the default policy:

  client.put(key, bins) # Use default write policy

Overriding the default policy:

  client.put(key, bins, ttl: 3600)

Using a new policy object to set a custom policy:

  policy = WritePolicy.new(ttl: 3600)
  client.put(key, bins, policy)

ClientPolicy Object

Client policy affecting the overall operation of the client. The client policy needs to be set when a new client instance is being instantiated.

Attributes:

  • timeout - Initial host connection timeout in seconds. The timeout when opening a connection to the server host for the first time.
    • Default: 1 second
  • connection_queue_size - Size of the Connection Queue cache.
    • Default: 64
  • fail_if_not_connected - Throw exception if host connection fails during the initial connection.
    • Default: true
  • tend_interval - Tend interval in milliseconds; determines the interval at which the client checks for cluster state changes. Minimum interval is 10ms.
    • Default: 1000
  • user - User name for clusters that require authentication (Enterprise only)
  • password - Password for clusters that require authentication (Enterprise only)
  • cluster_name - Cluster name (optional)
    • If specified, the cluster name will be verified whenever the client connects to a new cluster node and nodes with non-matching cluster name will be rejected.
  • tls - TLS/SSL context parameters (optional; requires Aerospike Enterprise Edition v3.11 or later)
    • To encrypt the client <-> server connections end-to-end using Transport Layer Security (TLS), an SSL/TLS context needs to be setup, by specifying one or more of the follwing options:
      • ca_file - The path to a file containing a PEM-format CA certificate.
      • ca_path - The path to a directory containing CA certificates in PEM format. Files are looked up by subject's X509 name's hash value.
      • cert_file - The path to a file containing a PEM-format client certificate.
      • pkey_file - The path to a file containing a PEM-format private key for the client certificate.
      • pkey_pass - Optional password in case pkey_file is an encrypted PEM resource.
    • Alternatively, a pre-configured SSLContext can be passed using the context property of the tls options hash. In this case, all other properties in tls are ignored.
  • rack_aware - Track server rack data. This field is useful when directing read commands to the server node that contains the key and exists on the same rack as the client. This serves to lower cloud provider costs when nodes are distributed across different racks/data centers. ClientPolicy.rack_id, Replica.PREFER_RACK and server rack configuration must also be set to enable this functionality.
  • rack_id - Rack where this client instance resides on. ClientPolicy.rack_aware, Replica.PREFER_RACK and server rack configuration must also be set to enable this functionality.

Examples

Enabling TLS encryption by specifying the cert/private key file:

require 'aerospike'
include Aerospike

tls_options = {
  ca_file = './tls/ca.cert.pem',
  cert_file = './tls/client.cert.pem',
  pkey_file = './tls/client.key.pem'
}
policy = ClientPolicy.new(tls: tls_options)
seed = '10.0.0.10:mydb:3000'

client = Client.new(seed, policy: policy)

Enabling TLS encryption by passing a pre-configured SSLContext:

require 'aerospike'
require 'openssl'

include Aerospike

context = OpenSSL::SSL::SSLContext.new
cert = OpenSSL::X509::Certificate.new(File.read('./tls/client.cert.pem'))
pkey = OpenSSL::PKey.read(File.read('./tls/client.key.pem'))
context.add_certificate(cert, pkey)
context.ciphers = [ ... ] # Customize the context

policy = ClientPolicy.new(tls: { context: context })
seed = '10.0.0.10:mydb:3000'

client = Client.new(seed, policy: policy)

Policy Object

A policy affecting the behaviour of read operations.

Attributes:

  • priority – Specifies the behavior for the key.
  • timeout – Maximum time to wait for the operation to complete.
    • If 0 (zero), then the value means there will be no timeout enforced. Value should be in seconds.
    • Default: 0 (no timeout)
  • max_retries – Number of times to try on connection errors.
    • Default: 2
  • sleep_between_retries – Duration of waiting between retries.
    • Default: 0.500 (500ms)
  • replica - Specifies to send read commands to which node containing the key's partition replica type.
    • Default: Replica.MASTER
  • use_compression - Specifies to use compression between client and server.
    • Default: false.

WritePolicy Object

A policy affecting the behaviour of write operations.

Includes all Policy attributes, plus:

  • send_key – Qualify whether the server should store the record's primary key, or just use its digest.
    • Default: true
  • record_exists_action – Qualify how to handle writes where the record already exists.
  • generation_policy – Qualify how to handle record writes based on record generation.
    • For values, see GenerationPolicy Values.
    • Default: GenerationPolicy.NONE (generation is not used to restrict writes)
  • commit_level – Desired consistency guarantee when committing a transaction on the server.
    • For values, see CommitLevel Values.
    • Default: CommitLevel.COMMIT_ALL (wait for write confirmation from all replicas)
  • generation – Expected generation.
    • Generation is the number of times a record has been modified (including creation) on the server. If a write operation is creating a record, the expected generation would be 0
    • Default: 0
  • expiration – Record expiration. Also known as ttl (time-to-live).
    • Seconds record will live before being removed by the server.
    • Expiration values:
      • Aerospike::TTL::NEVER_EXPIRE: Never expire for Aerospike 2 server versions >= 2.7.2 and Aerospike 3 server versions >= 3.1.4. Do not use for older servers.
      • Aerospike::TTL::NAMESPACE_DEFAULT: Default to namespace configuration variable "default-ttl" on the server.
      • Aerospike::TTL::DONT_UPDATE: Update the record without changing the record's current TTL value.

      • 0: Actual expiration in seconds.

    • Default: Aerospike::TTL::NAMESPACE_DEFAULT
  • durable_delete - (boolean) If the transaction results in a record deletion, leave a tombstone for the record. This prevents deleted records from reappearing after node failures.
    • Valid for Aerospike Server Enterprise Edition 3.10+ only. Default: false

OperatePolicy Object

A policy affecting the behavior of operate commands.

Includes all WritePolicy attributes, plus:

  • record_bin_multiplicity - Specifies how to merge results from multiple operations on the same record bin.

BatchPolicy Object

A policy affecting the behaviour of batch operations.

Includes All Policy attributes, plus:

  • use_batch_direct - [Boolean] Whether to use legacy Batch Direct protocol (if true) or newer Batch Index protocol (if false).
    • Use old batch direct protocol where batch reads are handled by direct low-level batch server database routines. The batch direct protocol can be faster when there is a single namespace. But there is one important drawback: The batch direct protocol will not proxy to a different server node when the mapped node has migrated a record to another node (resulting in not found record). This can happen after a node has been added/removed from the cluster and there is a lag between records being migrated and client partition map update (once per second). The batch index protocol will perform this record proxy when necessary.
    • Default: false (use new batch index protocol if server supports it)

QueryPolicy Object

A policy affecting the behaviour of query operations.

Includes All Policy attributes, plus:

  • include_bin_data - [Boolean] Indicates if bin data is retrieved.
    • If false, only record digests (and user keys if stored on the server) are retrieved.
    • Default: true
  • record_queue_size - The record set buffers the query results locally.
    • This attribute controls the size of the buffer (a SizedQueue instance).
    • Default: 5000

ScanPolicy Object

A policy affecting the behaviour of scan operations.

Includes All Policy attributes, plus:

  • scan_percent - Percent of data to scan.
    • Valid integer range is 1 to 100.
    • Default: 100
  • concurrent_nodes - [Boolean] Issue scan requests in parallel (if true) or serially (if false).
    • Default: true (parallel scans)
  • include_bin_data - [Boolean] Indicates if bin data is retrieved.
    • If false, only record digests (and user keys if stored on the server) are retrieved.
    • Default: true
  • record_queue_size - The record set buffers the query results locally.
    • This attribute controls the size of the buffer (a SizedQueue instance).
    • Default: 5000
  • fail_on_cluster_change: [Boolean] Terminate scan if cluster is in fluctuating state.
    • Default: true

Values

The following are values allowed for various policies.

ReplicaPolicy Values

  • MASTER - Read from node containing key's master partition.
  • MASTER_PROLES - Distribute reads across nodes containing key's master and replicated partitions in round-robin fashion.
  • SEQUENCE - Always try node containing master partition first. If connection fails and Policy.max_retries is > 0, try nodes containing prole partition.
  • PREFER_RACK - Try node on the same rack as the client first. If there are no nodes on the same rack, use SEQUENCE instead.
  • RANDOM - Distribute reads across all nodes in cluster in round-robin fashion.

GenerationPolicy Values

  • NONE - Writes a record, regardless of generation.
  • EXPECT_GEN_EQUAL - Writes a record, ONLY if generations are equal.
  • EXPECT_GEN_GT - Writes a record, ONLY if local generation is greater-than remote generation.
  • DUPLICATE - Writes a record creating a duplicate, ONLY if the generation collides.

RecordExistsAction Values

  • UPDATE - Create or update record.
    • Merge write command bins with existing bins.
  • UPDATE_ONLY - Update record only. Fail if record does not exist.
    • Merge write command bins with existing bins.
  • REPLACE - Create or replace record.
    • Delete existing bins not referenced by write command bins.
    • Supported by Aerospike 2 server versions >= 2.7.5 and Aerospike 3 server versions >= 3.1.6.
  • REPLACE_ONLY - Replace record only. Fail if record does not exist.
    • Delete existing bins not referenced by write command bins.
    • Supported by Aerospike 2 server versions >= 2.7.5 and Aerospike 3 server versions >= 3.1.6.
  • CREATE_ONLY - Create only. Fail if record exists.

CommitLevel Values

  • COMMIT_ALL - Wait until successfully committing master and all replicas.
  • COMMIT_MASTER- Wait until successfully committing master only.

Priority Values

  • DEFAULT - The server defines the priority.
  • LOW - Run the database operation in a background thread.
  • MEDIUM - Run the database operation at medium priority.
  • HIGH - Run the database operation at the highest priority.

RecordBinMultiplicity Values

  • SINGLE - Returns only the value of the last operation on the bin.
  • ARRAY - Returns all results of operations on the same bin as an array.