Skip to content

Decoupled configuration

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

The Developer SDK separates connection configuration from operational behavior, giving operators and developers independent control.

Why decoupled configuration?

Traditional clients mix connection settings with operation policies, making it hard to:

  • Change timeouts without code changes
  • Use different configurations per environment
  • Let operators tune behavior without developer involvement

The Developer SDK solves this with three layers:

┌─────────────────────────────────────────┐
│           Application Code              │
│  (uses Session, calls operations)       │
├─────────────────────────────────────────┤
│            Behaviors                    │
│  (operational policies, developer-set)  │
├─────────────────────────────────────────┤
│         Cluster Configuration           │
│  (connection details, operator-set)     │
└─────────────────────────────────────────┘

Cluster configuration (operators)

Connection details that operators control:

import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;


// From environment variables
Cluster cluster = new ClusterDefinition(
        System.getenv("AEROSPIKE_HOST"),
        3000)
    .withNativeCredentials(
        System.getenv("AEROSPIKE_USER"),
        System.getenv("AEROSPIKE_PASSWORD"))
    .connect();

📖 API reference: ClusterDefinition.connect() | ClusterDefinition.withNativeCredentials(...)

Behaviors (developers)

Operational policies that developers control:

import java.time.Duration;
import com.aerospike.client.sdk.policy.Behavior.Selectors;


// Developer chooses behavior for their use case
Behavior readFast = Behavior.DEFAULT.deriveWithChanges("READ_FAST", builder -> builder
    .on(Selectors.reads(), ops -> ops
        .waitForCallToComplete(Duration.ofMillis(50))
        .abandonCallAfter(Duration.ofMillis(200))
        .maximumNumberOfCallAttempts(4)));


Session readHeavy = cluster.createSession(readFast);
Session writeHeavy = cluster.createSession(Behavior.DEFAULT);
Session balanced = cluster.createSession(Behavior.DEFAULT);

📖 API reference: Cluster.createSession(Behavior)

External configuration files

Set the AEROSPIKE_SDK_CONFIG_URL environment variable to the path of a YAML file before you connect. Both SDKs read the same file format at connect() with snake_case keys and reload it when it changes. The behaviors section defines named behaviors. The system section holds the following client-wide profiles: connection pool, circuit breaker, tend interval, transaction and metrics settings. Connection details such as hosts and TLS are in ClusterDefinition.

aerospike-sdk-config.yaml
behaviors:
  read-heavy:
    all_operations:
      abandon_call_after: 200ms
      wait_for_call_to_complete: 50ms
      maximum_number_of_call_attempts: 4
system:
  DEFAULT:              # applies to every cluster
    connections:
      maximum_connections_per_node: 200
    transactions:
      number_of_attempts: 3
      sleep_between_attempts: 250ms
  production:           # applies to a cluster named production
    transactions:
      number_of_attempts: 5

Look up a behavior from the file by name with Behavior.getBehavior("read-heavy") in Java or get_behavior_or_default("read-heavy") from aerospike_sdk.policy in Python. Both return DEFAULT when the name is not defined.

Configuration precedence

System settings resolve per field, highest first. A field one layer doesn’t set falls through to the next.

  1. The config file’s profile for the cluster: system.<cluster-name>, for the name set with clusterName(...) in Java or cluster_name(...) in Python
  2. The config file’s DEFAULT profile
  3. Code: settings passed with withSystemSettings(...) in Java or with_system_settings(...) in Python
  4. Built-in defaults

With the file above, a cluster named production makes 5 transaction attempts, 250 ms apart.

Next steps