Migrating from classic client

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 helps you migrate an existing application from the Classic Aerospike client to the Developer SDK.

Why migrate?

The Developer SDK offers several advantages over the classic client:

• Cleaner syntax — Chainable, fluent APIs reduce boilerplate
• AEL queries — Human-readable filter expressions
• Better error handling — Actionable errors with recovery suggestions
• Decoupled configuration — Separate connection from behavior

Before you start

1. Confirm your Aerospike server is compatible (version 6.0 or later).
2. Install the Developer SDK as a separate package. It does not replace the classic client.
3. Plan to run both clients side by side during migration if you need a gradual cutover.

Conceptual changes

Connection model

Classic: Direct client with embedded configuration

SDK: Separate Cluster (connection) and Session (behavior)

Java Classic

// Classic: Everything in one place
AerospikeClient client = new AerospikeClient(
    new ClientPolicy(),
    new Host("localhost", 3000)
);

📖 API reference: Host(String,int) | Host(String,String,int)

Java SDK

import com.aerospike.client.sdk.policy.Behavior;
import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;
import com.aerospike.client.sdk.Session;

// SDK: Connection separate from behavior
try (Cluster cluster = new ClusterDefinition("localhost", 3000).connect()) {
    Session session = cluster.createSession(Behavior.DEFAULT);
}

📖 API reference: ClusterDefinition(String,int) | ClusterDefinition.connect() | Cluster.createSession(Behavior) | Cluster.close()

Python Classic

# Classic: Everything in one place
client = aerospike.client({
    'hosts': [('localhost', 3000)]
}).connect()

📖 API reference: aerospike.client() | Client.connect()

Python SDK

from aerospike_sdk import Behavior, ClusterDefinition

# SDK: Connection separate from behavior
async with await ClusterDefinition("localhost", 3000).connect() as cluster:
    session = cluster.create_session(Behavior.DEFAULT)

📖 API reference: Behavior.DEFAULT

Key and record references

Classic: Explicit Key objects with namespace, set, and user key

SDK: DataSet represents namespace + set, .id() creates record references

Java Classic

Key key = new Key("test", "users", "user-1");

📖 API reference: Key

Java SDK

DataSet users = DataSet.of("test", "users");
RecordRef ref = users.id("user-1");

📖 API reference: DataSet.of(...) | DataSet.id(...)

Python Classic

key = ("test", "users", "user-1")

📖 API reference: Key Tuple

Python SDK

users = DataSet.of("test", "users")
ref = users.id("user-1")

📖 API reference: DataSet.of() | DataSet.id()

Operation mapping

Create (put)

Java Classic

client.put(null, key, new Bin("name", "Alice"), new Bin("age", 30));

📖 API reference: com.aerospike.client.sdk

Java SDK

session.insert(users)
    .bins("name", "age")
    .id("user-1").values("Alice", 30)
    .execute();

📖 API reference: Session.insert(DataSet) | OperationObjectBuilder.bins(...) | IdValuesBuilder.id(...) | IdValuesRowBuilder.values(...) | ChainableQueryBuilder.execute()

Python Classic

client.put(key, {"name": "Alice", "age": 30})

📖 API reference: Client.put()

Python SDK

await session.insert(key=users.id("user-1")).put(
    {"name": "Alice", "age": 30}
).execute()

📖 API reference: DataSet.id() | Session.insert() | WriteSegmentBuilder.put() | WriteSegmentBuilder.execute()

Read (get)

Java Classic

Record record = client.get(null, key);
String name = record.getString("name");

📖 API reference: Record.getString(...)

Java SDK

import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.RecordStream;

String name;
try (RecordStream stream = session.query(users.id("user-1")).execute()) {
    Record user = stream.getFirstRecord();
    name = user.getString("name");
}

📖 API reference: DataSet.id(...) | Session.query(Key) | ChainableQueryBuilder.execute() | RecordStream.getFirstRecord() | Record.getString(...)

Python Classic

key, meta, bins = client.get(key)
name = bins["name"]

📖 API reference: Client.get()

Python SDK

stream = await session.query(users.id("user-1")).execute()
row = await stream.first_or_raise()
user = row.record_or_raise()
name = user.bins.get("name")
stream.close()

📖 API reference: DataSet.id() | Session.query() | RecordResult.record_or_raise() | RecordStream.first_or_raise() | RecordStream.close() | QueryBuilder.execute()

Update

Java Classic

client.put(null, key, new Bin("visits", 1), new Bin("updated", true));

📖 API reference: com.aerospike.client.sdk

Java SDK

session.update(users.id("user-1"))
    .bin("visits").setTo(1)
    .bin("updated").setTo(true)
    .execute();

📖 API reference: DataSet.id(...) | Session.update(DataSet) | ChainableOperationBuilder.bin(...) | ChainableQueryBuilder.bin(...) | ChainableQueryBuilder.execute()

Python Classic

client.put(key, {"visits": 1, "updated": True})

📖 API reference: Client.put()

Python SDK

await (
    session.update(users.id("user-1"))
    .bin("visits").set_to(1)
    .bin("updated").set_to(True)
    .execute()
)

📖 API reference: DataSet.id() | Session.update() | QueryBuilder.bin() | WriteSegmentBuilder.set_to() | WriteSegmentBuilder.bin() | WriteSegmentBuilder.execute()

Delete

Java Classic

client.delete(null, key);

📖 API reference: com.aerospike.client.sdk

Java SDK

session.delete(users.id("user-1")).execute().close();

📖 API reference: DataSet.id(...) | Session.delete(Key) | ChainableQueryBuilder.execute() | ChainableNoBinsBuilder.execute() | RecordStream.close()

Python Classic

client.remove(key)

📖 API reference: Client.remove()

Python SDK

stream = await session.delete(key=users.id("user-1")).execute()
stream.close()

📖 API reference: DataSet.id() | Session.delete() | RecordStream.close() | WriteSegmentBuilder.execute()

Query with filters

Java Classic

Statement stmt = new Statement();
stmt.setNamespace("test");
stmt.setSetName("users");
stmt.setFilter(Filter.range("age", 21, 100));

RecordSet rs = client.query(null, stmt);
while (rs.next()) {
    Record record = rs.getRecord();
    // process record
}

📖 API reference: RecordStream.next()

Java SDK

import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.RecordResult;
import com.aerospike.client.sdk.RecordStream;

RecordStream stream = session.query(users)
    .where("$.age >= 21")
    .execute();
stream.forEach((RecordResult result) -> {
    if (result.isOk()) {
        Record row = result.recordOrThrow();
        if (row != null) {
            // process record
        }
    }
});
stream.close();

📖 API reference: Session.query(DataSet) | ChainableQueryBuilder.where(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | RecordStream.close() | RecordResult.isOk() | RecordResult.recordOrThrow()

Python Classic

query = client.query("test", "users")
query.where(aerospike.predicates.between("age", 21, 100))

for record in query.results():
    # process record
    pass

📖 API reference: Client.query() | Query.where() | predicates.between() | Query.results()

Python SDK

stream = await session.query(users).where("$.age >= 21").execute()
async for row in stream:
    row.record_or_raise()
    pass  # process the returned record
stream.close()

📖 API reference: Session.query() | QueryBuilder.where() | RecordResult.record_or_raise() | RecordStream.close() | QueryBuilder.execute()

Migration strategy

Option 1: gradual migration

1. Add Developer SDK dependency alongside classic
2. Create new features with Developer SDK
3. Migrate existing code incrementally
4. Remove classic client when migration complete

Option 2: full migration

1. Create a feature branch
2. Replace all classic client calls with Developer SDK equivalents
3. Run comprehensive tests
4. Deploy with confidence

What’s not supported (yet)

Some advanced features from the classic client are not yet available in the Developer SDK SDK:

• Admin operations (cluster management)
• HyperLogLog
• GeoJSON queries
• Some complex expression in the AEL

For these features, continue using the classic client alongside Developer SDK.

Next steps

• Quickstart — Get started with Developer SDK
• AEL Queries — Learn the query syntax
• Error Handling — Understand error recovery