Go client policies

This page describes how to customize your client policies for optimal query performance and reliability. Aerospike client policies control the behavior of database queries at a fine-grained level.

Connecting to the server

ClientPolicy includes constructors for defining the client/server connection, including authentication, consistency guarantees, and TCP keep-alive.

Basic timeout settings

Aerospike clients offer a variety of timeout and retry settings that control operation requests. Configure these timeout settings in the policy objects, and they are passed as a parameters when the Aerospike operation is requested.

We recommend the following when configuring timeout settings:

To avoid premature timeouts, ensure that timeout duration is longer than a normal request time.
To avoid unnecessary delays in detecting an abnormal condition or problem with the network or server, decrease timeout durations if you know it is safe to do so.

Increase the number of retries and the time between retries in an environment where your responses are unreliable, due to either network or server issues. Keep in mind that doing so will also cause more delays in detecting fatal error conditions such as real network or server outages.

Socket timeout: SocketTimeout specifies socket idle timeout in milliseconds when processing a database command.
Total timeout: TotalTimeout specifies total transaction timeout in milliseconds.
Max retries: MaxRetries specifies the maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.
Sleep between retries: SleepBetweenRetries specifies the milliseconds to sleep between retries. Enter zero to skip sleep. This field is ignored when MaxRetries is zero. This field is also ignored in async mode.
Timeout delay: TimeoutDelay creates a grace period after a client operation times out. During this period:
- The client returns a timeout error to the application immediately.
- Instead of closing the socket immediately, the client waits for the specified delay period.
- If the server response arrives during this delay window, the connection is returned to the pool for reuse.
- If no response arrives by the end of the delay, the connection is closed.
This approach is particularly valuable for TLS connections, which are significantly more expensive to establish due to the handshake process.

For more information, see the timeout policies blog post.

Connection pool configuration

Whenever possible, Aerospike clients manage an internal session pool to avoid the cost of creating a session when making a command request. A variety of client policy options are available to control the behavior of the Aerospike client’s session pool management. You can avoid fluctuation in the client pool and create a fixed resource utilization cost by setting the minimum connections per node to the same value as the maximum connections per node.

Increase the minimum connections per node to avoid the latency overhead for creating new connections after a period of relative inactivity. This situation can arise if your workload has spikes or waves of high volume, but comes at the cost of constant increased client-side resource utilization.

Minimum connections per node

Increase the minimum connections per node to avoid the latency overhead for creating new connections after a period of relative inactivity. This situation can arise if your workload has spikes or waves of high volume, but comes at the cost of constant increased client-side resource utilization.

MinConnectionsPerNode is the minimum number of synchronous connections allowed per server node. Setting this option preallocates the minimum connections on client node creation. The client periodically allocates new connections if the count falls below MinConnectionsPerNode.

For more information, see MinConnectionsPerNode.

You can avoid fluctuation in the client pool and create a fixed resource utilization cost by setting the minimum connections per node to the same value as the maximum connections per node.

Maximum connections per node

Increase the maximum connections per node to avoid latency overhead and blocking or queuing during your peak workload periods. This can greatly increase your client-side resource utilization. Consider reducing this number if you are controlling client-side scaling externally. For instance, with Kubernetes application side scaling, consider reducing the total number of outstanding sessions that the Aerospike server will need to support simultaneously.

ConnectionQueueSize is the maximum number of synchronous connections allowed per server node. Requests go through retry logic and potentially fail with ResultCode.NO_AVAILABLE_CONNECTIONS_TO_NODE if the maximum number of connections is exceeded.

You can avoid fluctuation in the client pool and create a fixed resource utilization cost by setting the maximum connections per node to the same value as the minimum connections per node.

Backoff behavior

Aerospike clients provide client-side backoff or circuit breaker functionality that you can control with the client policy. This functionality restricts an application from overwhelming the server with requests if it notices an increase in the number of errors returned by the server. We highly recommend that you use this functionality, especially in situations where you have a large or scalable application workload connected to a single Aerospike cluster.

Max error rate: MaxErrorRate is the maximum number of errors allowed per node during an interval defined by ErrorRateWindow before the backoff algorithm throws an AerospikeError.MaxErrorRate error on database commands to that node. If maxErrorRate is zero, there is no error limit and the exception is never thrown.
Error rate window: ErrorRateWindow is the number of cluster tend iterations to use to evaluate the MaxErrorRate. If the MaxErrorRate is reached, the backoff algorithm rejects additional database commands to the node until the number of errors goes back down.