Connection management

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

Connection architecture

┌─────────────────────────────────────────────────────────┐
│                    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
Python

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

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:

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

// Check cluster health
ClusterStats stats = cluster.getStats();
System.out.println("Active nodes: " + stats.getActiveNodeCount());
System.out.println("Total connections: " + stats.getTotalConnections());

# 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

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