# Connection management

This guide explains how the Developer SDK manages connections to Aerospike clusters.

## Connection architecture

```plaintext
┌─────────────────────────────────────────────────────────┐

│                    Your Application                     │

│                                                         │

│  ┌─────────┐  ┌─────────┐  ┌─────────┐                  │

│  │ Session │  │ Session │  │ Session │  (multiple)      │

│  └────┬────┘  └────┬────┘  └────┬────┘                  │

│       └────────────┼────────────┘                       │

│                    │                                    │

│              ┌─────┴─────┐                              │

│              │  Cluster  │  (shared connection pool)    │

│              └─────┬─────┘                              │

└────────────────────┼────────────────────────────────────┘

                     │

         ┌───────────┼───────────┐

         │           │           │

    ┌────┴────┐ ┌────┴────┐ ┌────┴────┐

    │ Node 1  │ │ Node 2  │ │ Node 3  │  (Aerospike cluster)

    └─────────┘ └─────────┘ └─────────┘
```

## Cluster discovery

The client automatically discovers all nodes from seed hosts:

-   [Java](#tab-panel-2946)
-   [Python](#tab-panel-2947)

```java
import com.aerospike.client.sdk.Cluster;

import com.aerospike.client.sdk.ClusterDefinition;

import com.aerospike.client.sdk.Host;

// Provide seed hosts - client discovers the full cluster

Cluster cluster = new ClusterDefinition(

    new Host("seed1.example.com", 3000),

    new Host("seed2.example.com", 3000)  // Backup seed

).connect();

// Client now knows about all nodes in the cluster
```

```python
from aerospike_sdk import ClusterDefinition, Host

# Provide seed hosts - client discovers the full cluster

cluster = await ClusterDefinition(

    hosts=[

        Host.of("seed1.example.com", 3000),

        Host.of("seed2.example.com", 3000),

    ]

).connect()

# Client now knows about all nodes in the cluster
```

## Connection pooling

The Cluster maintains a pool of connections to each node:

-   Connections are reused across operations
-   Pool size adjusts based on load
-   Idle connections are cleaned up periodically

## Node failure handling

When a node fails:

1.  Client detects failure via heartbeat or operation timeout
2.  Operations automatically retry on other nodes
3.  Client removes failed node from active pool
4.  When node recovers, client re-adds it

## Monitoring connection health

-   [Java](#tab-panel-2948)
-   [Python](#tab-panel-2949)

```java
// Check cluster health

ClusterStats stats = cluster.getStats();

System.out.println("Active nodes: " + stats.getActiveNodeCount());

System.out.println("Total connections: " + stats.getTotalConnections());
```

```python
# The Python SDK does not expose a programmatic cluster-stats API. Use

# cluster.is_connected() for a simple liveness check, and instrument

# connection health at the application level — see the Metrics and Logging

# guides for Prometheus / OpenTelemetry / StatsD integration patterns.

connected = cluster.is_connected()

print(f"Cluster connected: {connected}")
```

## Best practices

1.  **Reuse Cluster instances** — Create once, share across your application
2.  **Use multiple seed hosts** — Ensures discovery even if one seed is down
3.  **Close properly** — Call `cluster.close()` on shutdown
4.  **Monitor health** — Track connection metrics in production

## Next steps

-   [Connect to Aerospike](https://aerospike.com/docs/develop/client/sdk/connect)
-   [Behaviors](https://aerospike.com/docs/develop/client/sdk/concepts/behaviors)
-   [Common Issues](https://aerospike.com/docs/develop/client/sdk/reference/common-issues)