Connection management

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Applies to

Aerospike Developer SDK preview (Java 21+ and Python 3.10+)
Aerospike Database 6.0 or later unless a section states otherwise

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

📖 API reference: ClusterDefinition(Host...) | Host(String,int) | Host(String,String,int) | ClusterDefinition.connect()

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

📖 API reference: ClusterDefinition | Host

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:

The client detects failure using heartbeat or operation timeout.
Operations automatically retry on other nodes.
The client removes the failed node from the active pool.
When the node recovers, the client adds it back.

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

📖 API reference: com.aerospike.client.sdk

# 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}")

📖 API reference: Cluster

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