Skip to content

Connection management

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Applies to

  • Aerospike Developer SDK (Java 21+ and Python 3.11+)
  • Aerospike Database 8.2.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:

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()

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. The client detects failure using heartbeat or operation timeout.
  2. Operations automatically retry on other nodes.
  3. The client removes the failed node from the active pool.
  4. When the node recovers, the client adds it back.

Monitoring connection health

// Check cluster health
System.out.println("Connected: " + cluster.isConnected());
System.out.println("Active nodes: " + cluster.getNodes().length);
System.out.println("Commands: " + cluster.getCommandCount());
System.out.println("Retries: " + cluster.getRetryCount());

📖 API reference: com.aerospike.client.sdk

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