Skip to content

Connecting

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

To establish an Aerospike server connection, create an AerospikeClient with one or more seed hosts. The client uses those hosts to discover the cluster.

AerospikeClient client = new(host, port);

The client starts a maintenance thread that periodically refreshes nodes, peers, partition maps, and rack information. The instance is thread-safe and should normally be shared by concurrent application code.

Startup and connection failures

By default, construction fails when the client cannot connect to any seed. Set failIfNotConnected to false when the application should start with a partial or empty cluster view and let the maintenance thread discover unavailable nodes later.

ClientPolicy startupPolicy = new()
{
  // False allows a client with a partial cluster view to start and discover
  // unavailable nodes later.
  failIfNotConnected = false
};

Synchronous connections are pooled per node. If a command needs a connection after maxConnsPerNode has been reached and none is available, it fails with ResultCode.NO_MORE_CONNECTIONS. Size both limits for application concurrency and for parallel subcommands created by batch, scan, and query operations.

ClientPolicy poolPolicy = new()
{
  minConnsPerNode = 10,
  maxConnsPerNode = 100
};

The error-rate circuit breaker rejects commands to a node after maxErrorRate errors occur during errorRateWindow tend iterations. When retries cannot route the command successfully, the client throws AerospikeException.Backoff with ResultCode.MAX_ERROR_RATE. See Circuit Breaker for how to size these values.

ClientPolicy backoffPolicy = new()
{
  maxErrorRate = 100,
  errorRateWindow = 1
};

Authentication

AuthMode.INTERNAL and AuthMode.EXTERNAL use a user name and password. External authentication requires TLS. AuthMode.PKI requires TLS and a client certificate, and does not use a user name or password. Constructing a client with EXTERNAL or PKI and no tlsPolicy throws AerospikeException.

ClientPolicy policy = new()
{
  user = user,
  password = password
};


AerospikeClient client = new(policy, host, port);

TLS secured connection

TLS connections require certificate configuration on both client and server. The TLS connection port is usually set to 4333 instead of the typically unsecured port 3000. See mTLS for more information about configuring a C# application to connect to an Aerospike cluster that uses mutual authentication TLS (mTLS).

The client TLS name (the tlsName argument to Host below) should match either the certificate common name (CN) or the certificate subject alternative name. Usually, the client TLS name is also the server’s tls-name configuration value.

TlsPolicy can also restrict protocols (protocols), revoke certificates by serial number (revokeCertificates), or encrypt only the login exchange (forLoginOnly). Login-only TLS leaves subsequent database traffic unencrypted, so use it only when that tradeoff is acceptable. When ClientPolicy.clusterName is set and a seed host has no explicit TLS name, the cluster name is used as the TLS name. See TLS configuration for more information about setting up TLS on your Aerospike Database server. See the API documentation for client TLS configuration options.

Host tlsHost = new(host, tlsName, port);


TlsPolicy tlsPolicy = new();


ClientPolicy policy = new()
{
  tlsPolicy = tlsPolicy
};


AerospikeClient client = new(policy, tlsHost);

TlsPolicy also has a constructor that takes these settings as strings, which is convenient when they come from application configuration. It loads the certificate file without a password, so use the clientCertificates collection shown below for a password-protected PFX.

// TlsPolicy also accepts its settings as strings, which suits configuration
// files. This overload loads the certificate file without a password.
TlsPolicy configuredTlsPolicy = new(
  protocolString: "Tls12",
  revokeString: null,
  clientCertificateFile: null,
  forLoginOnly: false);

For NAT, containers, or other environments where the server’s advertised service addresses are not reachable by the client, configure alternate service and peer addresses on the server and enable them in the client:

ClientPolicy alternateAddressPolicy = new()
{
  // Use service/peer alternate addresses advertised by the cluster.
  useServicesAlternate = true
};

PKI authentication

PKI authentication identifies the client by its certificate, so TlsPolicy.clientCertificates must be set. The certificate has to include an accessible private key. A certificate loaded without its key completes the TLS handshake configuration but fails authentication at the server.

X509Certificate2Collection comes from System.Security.Cryptography.X509Certificates.

Host tlsHost = new(host, tlsName, port);


X509Certificate2Collection clientCertificates = new();
clientCertificates.Import(clientCertificateFile, certificatePassword);


TlsPolicy tlsPolicy = new()
{
  clientCertificates = clientCertificates
};


ClientPolicy policy = new()
{
  tlsPolicy = tlsPolicy,
  authMode = AuthMode.PKI
};


AerospikeClient client = new(policy, tlsHost);

Cleaning Up

Call Close() when all commands are finished and the application is ready to shutdown.

client.Close();