Config

Config

config command. The Config class contains the settings for an Aerospike client instance, including the list of seed hosts, default policies, and other settings.

Constructor

new Config(configopt)

Source:
Example
const Aerospike = require('aerospike')

let config = {
  hosts: '192.168.1.10,192.168.1.11',
  user: process.env.DATABASE_USER,
  password: process.env.DATABASE_PASSWORD,
  policies: {
    read: new Aerospike.ReadPolicy({
      totalTimeout: 0
    })
  },
  log: {
    level: Aerospike.log.INFO,
    file: 2 // log to stderr
  }
}

Aerospike.connect(config)
  .then(client => {
    // client is ready to accept commands
    client.close()
  })
  .catch(error => {
    console.error('Failed to connect to cluster: %s', error.message)
  })


// Initializes a new client configuration from the given config values.
Parameters:
Name Type Attributes Description
config Object <optional>

configuration values

Throws:

If invalid config values are passed.

Type
TypeError

Members

authMode :number

Authentication mode used when user/password is defined.

Description:
Source:
See:

One of the auth modes defined in module:aerospike.auth.

Type:
  • number

clusterName :string

Expected Cluster Name.

Description:
  • If not null, server nodes must return this cluster name in order to join the client's view of the cluster. Should only be set when connecting to servers that support the "cluster-name" info command.

Source:
Since:
  • v2.4

If not null, server nodes must return this cluster name in order to join the client's view of the cluster. Should only be set when connecting to servers that support the "cluster-name" info command.

Type:
  • string

connTimeoutMs :number

Initial host connection timeout in milliseconds.

Description:
  • The client observes this timeout when opening a connection to the cluster for the first time.

Source:
Default Value:
  • 1000

The client observes this timeout when opening a connection to the cluster for the first time.

Type:
  • number

errorRateWindow :number

The number of cluster tend iterations that defines the window for Config#maxErrorRate to be surpassed. One tend iteration is defined as Config#tendInterval plus the time to tend all nodes. At the end of the window, the error count is reset to zero and backoff state is removed on all nodes.

Source:
Default Value:
  • 1
Type:
  • number

hosts :Array.<Host>|string

List of hosts with which the client should attempt to connect.

Description:
  • If not specified, the client attempts to read the host list from the AEROSPIKE_HOSTS environment variable or else falls back to use a default value of "localhost".

Source:

If not specified, the client attempts to read the host list from the AEROSPIKE_HOSTS environment variable or else falls back to use a default value of "localhost".

Type:
  • Array.<Host> | string
Examples

Setting hosts using a string:

const Aerospike = require('aerospike')

const hosts = '192.168.0.1:3000,192.168.0.2:3000'
const client = await Aerospike.connect({ hosts })

Setting hosts using an array of hostname/port tuples:

const Aerospike = require('aerospike')

const hosts = [
  { addr: '192.168.0.1', port: 3000 },
  { addr: '192.168.0.2', port: 3000 }
]
const client = await Aerospike.connect({ hosts })

Setting hosts with TLS name using a string:

const Aerospike = require('aerospike')

const hosts = '192.168.0.1:example.com:3000,192.168.0.2:example.com:3000'
const client = await Aerospike.connect({ hosts })

Setting hosts using an array of hostname/port/tlsname tuples:

const Aerospike = require('aerospike')

const hosts = [
  { addr: '192.168.0.1', port: 3000, tlsname: 'example.com' },
  { addr: '192.168.0.2', port: 3000, tlsname: 'example.com' }
]
const client = await Aerospike.connect({ hosts })

log :Object

Configuration for logging done by the client.

Source:
Properties:
Name Type Attributes Description
log.level Number <optional>

Log level; see module:aerospike.log for details.

log.file Number <optional>

File descriptor returned by fs.open() or one of process.stdout.fd or process.stderr.fd.

Type:
  • Object
Example

Enabling debug logging to a separate log file

const Aerospike = require('aerospike')

const fs = require('fs')

var debuglog = fs.openSync('./debug.log', 'w')
// INSERT HOSTNAME AND PORT NUMBER OF AEROSPIKE SERVER NODE HERE!
var config = {
  hosts: '192.168.33.10:3000',
  log: {
    level: Aerospike.log.DEBUG,
    file: debuglog
  }
}
Aerospike.connect(config, (err, client) => {
  if (err) throw err
  console.log("Connected. Now closing connection.")
  client.close()
})

loginTimeoutMs :number

Node login timeout in milliseconds.

Source:
Default Value:
  • 5000
Type:
  • number

maxConnsPerNode :number

Maximum number of asynchronous connections allowed per server node.

Description:
Source:
Default Value:
  • 100

New transactions will be rejected with an ERR_NO_MORE_CONNECTIONS error if the limit would be exceeded.

Type:
  • number

maxErrorRate :number

Maximum number of errors allowed per node per error_rate_window before backoff algorithm returns AEROSPIKE_MAX_ERROR_RATE for database commands to that node. If max_error_rate is zero, there is no error limit. The counted error types are any error that causes the connection to close (socket errors and client timeouts), server device overload and server timeouts.

The application should backoff or reduce the transaction load until AEROSPIKE_MAX_ERROR_RATE stops being returned.

Description:
  • If the backoff algorithm has been activated, transactions will fail with AEROSPIKE_MAX_ERROR_RATE until the Config#errorRateWindow has passed and the error count has been reset.

Source:
Default Value:
  • 100

If the backoff algorithm has been activated, transactions will fail with AEROSPIKE_MAX_ERROR_RATE until the Config#errorRateWindow has passed and the error count has been reset.

Type:
  • number

maxSocketIdle :number

Maximum socket idle time in seconds.

Description:
  • Connection pools will discard sockets that have been idle longer than the maximum. The value is limited to 24 hours (86400).

    It's important to set this value to a few seconds less than the server's proto-fd-idle-ms (default 60000 milliseconds or 1 minute), so the client does not attempt to use a socket that has already been reaped by the server.

    Connection pools are now implemented by a LIFO stack. Connections at the tail of the stack will always be the least used. These connections are checked for maxSocketIdle once every 30 tend iterations (usually 30 seconds).

Source:
Default Value:
  • 0 seconds

Connection pools will discard sockets that have been idle longer than the maximum. The value is limited to 24 hours (86400).

It's important to set this value to a few seconds less than the server's proto-fd-idle-ms (default 60000 milliseconds or 1 minute), so the client does not attempt to use a socket that has already been reaped by the server.

Connection pools are now implemented by a LIFO stack. Connections at the tail of the stack will always be the least used. These connections are checked for maxSocketIdle once every 30 tend iterations (usually 30 seconds).

Type:
  • number

minConnsPerNode :number

Minimum number of asynchronous connections allowed per server node.

Description:
  • Preallocate min connections on client node creation. The client will periodically allocate new connections if count falls below min connections.

    Server proto-fd-idle-ms may also need to be increased substantially if min connections are defined. The proto-fd-idle-ms default directs the server to close connections that are idle for 60 seconds which can defeat the purpose of keeping connections in reserve for a future burst of activity.

    If server proto-fd-idle-ms is changed, client Config#maxSocketIdle should also be changed to be a few seconds less than proto-fd-idle-ms.

Source:
Default Value:
  • 0

Preallocate min connections on client node creation. The client will periodically allocate new connections if count falls below min connections.

Server proto-fd-idle-ms may also need to be increased substantially if min connections are defined. The proto-fd-idle-ms default directs the server to close connections that are idle for 60 seconds which can defeat the purpose of keeping connections in reserve for a future burst of activity.

If server proto-fd-idle-ms is changed, client Config#maxSocketIdle should also be changed to be a few seconds less than proto-fd-idle-ms.

Type:
  • number

modlua :Object

Configuration values for the mod-lua user path.

Description:
  • If you are using user-defined functions (UDF) for processing query results (i.e. aggregations), then you will find it useful to set the modlua settings. Of particular importance is the modelua.userPath, which allows you to define a path to where the client library will look for Lua files for processing.

Source:
Properties:
Name Type Attributes Description
modlua.userPath string <optional>

Path to user Lua scripts.

If you are using user-defined functions (UDF) for processing query results (i.e. aggregations), then you will find it useful to set the modlua settings. Of particular importance is the modelua.userPath, which allows you to define a path to where the client library will look for Lua files for processing.

Type:
  • Object

password :string

The password to use when authenticating to the cluster.

Source:
Type:
  • string

policies :Policies

Global client policies.

Description:
  • The configuration defines default policies for the application. Policies define the behavior of the client, which can be global for all uses of a single type of operation, or local to a single use of an operation.

    Each database operation accepts a policy for that operation as an argument. This is considered a local policy, and is a single use policy. This local policy supersedes any global policy defined.

    If a value of the policy is not defined, then the rule is to fallback to the global policy for that operation. If the global policy for that operation is undefined, then the global default value will be used.

    If you find that you have behavior that you want every use of an operation to utilize, then you can specify the default policy as Config#policies.

    For example, the Client#put operation takes a WritePolicy parameter. If you find yourself setting the WritePolicy#key policy value for every call to Client.put, then you may find it beneficial to set the global WritePolicy in Config#policies, which all operations will use.

Source:

The configuration defines default policies for the application. Policies define the behavior of the client, which can be global for all uses of a single type of operation, or local to a single use of an operation.

Each database operation accepts a policy for that operation as an argument. This is considered a local policy, and is a single use policy. This local policy supersedes any global policy defined.

If a value of the policy is not defined, then the rule is to fallback to the global policy for that operation. If the global policy for that operation is undefined, then the global default value will be used.

If you find that you have behavior that you want every use of an operation to utilize, then you can specify the default policy as Config#policies.

For example, the Client#put operation takes a WritePolicy parameter. If you find yourself setting the WritePolicy#key policy value for every call to Client.put, then you may find it beneficial to set the global WritePolicy in Config#policies, which all operations will use.

Type:
Example

Setting a default key policy for all write operations

const Aerospike = require('aerospike')

// INSERT HOSTNAME AND PORT NUMBER OF AEROSPIKE SERVER NODE HERE!
var config = {
  hosts: '192.168.33.10:3000',
  policies: {
    write: new Aerospike.WritePolicy({
      key: Aerospike.policy.key.SEND,
      socketTimeout : 0,
      totalTimeout : 0
    })
  }
}

let key = new Aerospike.Key('test', 'demo', 123)

Aerospike.connect(config)
  .then(client => {
    return client.put(key, {int: 42})
      .then(() => client.close())
      .catch(error => {
        throw error
        client.close()
      })
  })
  .catch(console.error)

port :number

Default port to use for any host address, that does not explicitly specify a port number. Default is 3000.

Source:
Since:
  • v2.4
Type:
  • number

rackAware :boolean

Track server rack data.

Description:
  • 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.

    rackId config, PREFER_RACK replica policy, and server rack configuration must also be set to enable this functionality.

Source:
Since:
  • 3.8.0
Default Value:
  • false

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.

rackId config, PREFER_RACK replica policy, and server rack configuration must also be set to enable this functionality.

Type:
  • boolean

rackId :number

Rack where this client instance resides.

Description:
  • rackAware config, PREFER_RACK replica policy, and server rack configuration must also be set to enable this functionality.

Source:
Since:
  • 3.8.0
Default Value:
  • 0

rackAware config, PREFER_RACK replica policy, and server rack configuration must also be set to enable this functionality.

Type:
  • number

sharedMemory :Object

Shared memory configuration.

Description:
  • This allows multiple client instances running in separate processes on the same machine to share cluster status, including nodes and data partition maps. Each shared memory segment contains state for one Aerospike cluster. If there are multiple Aerospike clusters, a different key must be defined for each cluster.

Source:
Tutorials:
See:
Properties:
Name Type Attributes Default Description
enable boolean <optional>
true

Whether to enable/disable usage of shared memory.

key number

Identifier for the shared memory segment associated with the target Aerospike cluster; the same key needs to be used on all client instances connecting to the same cluster.

maxNodes number <optional>
16

Sets the max. number of server nodes in the cluster - this value is required to size the shared memory segment. Ensure that you leave a cushion between actual server node cound and maxNodes so that you can add new nodes without rebooting the client.

maxNamespaces number <optional>
8

Sets the max. number of namespaces used in the cluster - this value is required to size the shared memory segment. Ensure that you leave a cushion between actual namespace count and maxNamespaces so that you can add new namespaces without rebooking the client.

takeoverThresholdSeconds number <optional>
30

Expiration time in seconds for the lock on the shared memory segment; if the cluster status has not been updated after this many seconds another client instance will take over the shared memory cluster tending.

This allows multiple client instances running in separate processes on the same machine to share cluster status, including nodes and data partition maps. Each shared memory segment contains state for one Aerospike cluster. If there are multiple Aerospike clusters, a different key must be defined for each cluster.

Type:
  • Object
Example

Using shared memory in a clustered setup

const Aerospike = require('aerospike')
const cluster = require('cluster')

const config = {
  sharedMemory: {
    key: 0xa5000000
  }
}
const client = Aerospike.client(config)
const noWorkers = 4

if (cluster.isMaster) {
  // spawn new worker processes
  for (var i = 0; i < noWorkers; i++) {
    cluster.fork()
  }
} else {
  // connect to Aerospike cluster in each worker process
  client.connect((err) => { if (err) throw err })

  // handle incoming HTTP requests, etc.
  // http.createServer((request, response) => { ... })

  // close DB connection on shutdown
  client.close()
}

tenderInterval :number

Polling interval in milliseconds for cluster tender.

Source:
Default Value:
  • 1000
Type:
  • number

tls :Object

Configure Transport Layer Security (TLS) parameters for secure connections to the database cluster. TLS connections are not supported as of Aerospike Server v3.9 and depend on a future server release.

Source:
Since:
  • v2.4
Properties:
Name Type Attributes Default Description
enable boolean <optional>
true

Enable TLS for socket connections to cluster nodes. By default TLS is enabled only if the client configuration includes a tls section.

cafile string <optional>

Path to a trusted CA certificate file. By default TLS will use system standard trusted CA certificates.

capath string <optional>

Path to a directory of trusted certificates. See the OpenSSL SSL_CTX_load_verify_locations manual page for more information about the format of the directory.

protocols string <optional>

Specifies enabled protocols. The format is the same as Apache's SSLProtocol documented at https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslprotocol. If not specified, the client will use "-all +TLSv1.2". If you are not sure what protocols to select this option is best left unspecified.

cipherSuite string <optional>

Specifies enabled cipher suites. The format is the same as OpenSSL's Cipher List Format documented at https://www.openssl.org/docs/manmaster/apps/ciphers.html. If not specified the OpenSSL default cipher suite described in the ciphers documentation will be used. If you are not sure what cipher suite to select this option is best left unspecified.

certBlacklist string <optional>

Path to a certificate blacklist file. The file should contain one line for each blacklisted certificate. Each line starts with the certificate serial number expressed in hex. Each entry may optionally specify the issuer name of the certificate. (Serial numbers are only required to be unique per issuer.) Example records:
867EC87482B2 /C=US/ST=CA/O=Acme/OU=Engineering/CN=Test Chain CA
E2D4B0E570F9EF8E885C065899886461

keyfile string <optional>

Path to the client's key for mutual authentication. By default, mutual authentication is disabled.

keyfilePassword string <optional>

Decryption password for the client's key for mutual authentication. By default, the key is assumed not to be encrypted.

certfile string <optional>

Path to the client's certificate chain file for mutual authentication. By default, mutual authentication is disabled.

crlCheck boolean <optional>
false

Enable CRL checking for the certificate chain leaf certificate. An error occurs if a suitable CRL cannot be found. By default CRL checking is disabled.

crlCheckAll boolean <optional>
false

Enable CRL checking for the entire certificate chain. An error occurs if a suitable CRL cannot be found. By default CRL checking is disabled.

logSessionInfo boolean <optional>
false

Log session information for each connection.

forLoginOnly boolean <optional>
false

Use TLS connections only for login authentication. All other communication with the server will be done with non-TLS connections. Default: false (Use TLS connections for all communication with the server.)

Type:
  • Object

useAlternateAccessAddress :boolean

Whether the client should use the server's alternate-access-address instead of the access-address.

Source:
Since:
  • v3.7.1
Default Value:
  • false
Type:
  • boolean

user :string

The user name to use when authenticating to the cluster.

Description:
  • Leave empty for clusters running without access management. (Security features are available in the Aerospike Database Enterprise Edition.)

Source:

Leave empty for clusters running without access management. (Security features are available in the Aerospike Database Enterprise Edition.)

Type:
  • string

Methods

setDefaultPolicies(one)

Description:
  • Set default policies from the given policy values.

Source:
Parameters:
Name Type Description
one Policies

or more default policies

Throws:

if any of the properties of the policies object is not a valid policy type

Type
TypeError