---
title: "Best practices"
description: "Best practices for optimizing Aerospike Python client performance, connections, policies, and resource management."
---

# Best practices

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

This guide provides optimization techniques for the Aerospike Python client, including:

-   Shared client instances
-   Connection pool limits
-   Policy reuse
-   Circuit breaker settings
-   Logging for operational visibility

## Enable client log

Each client instance runs a background cluster tend thread that periodically polls all nodes for cluster status. This thread generates log messages that reflect node additions and removals and any errors when retrieving node status, peers, partition maps, and racks. Enable logging to receive these messages during troubleshooting.

See [Configure logging](https://aerospike.com/docs/develop/client/python/logging/).

## Share client instance

Each client instance spawns a maintenance thread that periodically makes info requests to all server nodes for cluster status. Multiple client instances create additional load on the server. Use one client instance per cluster in an application and share that instance across application threads or workers.

## Set maximum connections

Set `max_conns_per_node` in the client configuration to the maximum number of synchronous connections allowed per server node (default 100). The number of connections used per node depends on concurrent commands in progress plus sub-commands used for parallel multi-node commands (batch and query). A request fails if the maximum number of connections would be exceeded.

Set `min_conns_per_node` to preallocate connections and avoid latency from creating new connections after idle periods. See [Policies](https://aerospike.com/docs/develop/client/python/policies/#connection-pool-configuration) and the [connection tuning guide](https://aerospike.com/docs/develop/connection-tuning-guide/) for details.

## User-defined key

By default, the user-defined key is not stored on the server. The client converts it to a hash digest that identifies the record. If the user-defined key must persist on the server, use one of the following methods:

-   Set `'key': aerospike.POLICY_KEY_SEND` in the write policy. The key is sent to the server for storage on writes and returned on multi-record queries.
-   Explicitly store and retrieve the user-defined key in a bin.

See [Create records](https://aerospike.com/docs/develop/client/python/usage/atomic/create/#policies) for an example.

## Replace mode

When a command creates or replaces all record bins, use replace mode to increase performance. The server then does not have to read the old record before updating. Do not use replace mode when updating a subset of bins.

```python
import aerospike

write_policy = {'exists': aerospike.POLICY_EXISTS_REPLACE}

client.put(key, bins, policy=write_policy)
```

See [Update records](https://aerospike.com/docs/develop/client/python/usage/atomic/update/#policies) for available `exists` actions.

## Policy reuse

Each database command accepts an optional policy argument. If a group of commands uses the same policy, reuse the policy dictionary instead of creating a new one for each command.

Set policy defaults in the client configuration and pass only the fields that differ per command:

```python
import aerospike

config = {

    'hosts': [('127.0.0.1', 3000)],

    'policies': {

        'read': {'total_timeout': 1000},

        'write': {'total_timeout': 2000, 'max_retries': 2},

    },

}

client = aerospike.client(config).connect()

client.get(key)  # uses read policy defaults from config
```

When a policy must differ from the default for a single command, copy the base policy and modify the copy so parallel commands are not affected by shared mutations.

## Circuit breaker

Use client-side backoff to prevent overwhelming a node during error bursts. Configure `max_error_rate` and `error_rate_window` in the client configuration. When the error threshold is reached, the client raises `aerospike.exception.MaxErrorRateExceeded` for commands to that node.

See [Policies — Backoff behavior](https://aerospike.com/docs/develop/client/python/policies/#backoff-behavior) and the [circuit breaker tutorial](https://aerospike.com/docs/develop/tutorials/circuit-breaker/).

## Use operate for multiple bin updates

Use `client.operate()` to batch multiple operations on the same record in a single round trip instead of issuing separate read and write commands.

See [Bin operations](https://aerospike.com/docs/develop/client/python/usage/atomic/multi/).

## Close the client

Call `client.close()` when the application shuts down to release connections and stop the cluster tend thread. After closing, create a new client or call `client.connect()` before executing further commands.