Connecting

To connect to an Aerospike database, create a new Client instance that specifies the IP address and port of one or more seed nodes in the cluster.

Prerequisites

• A running Aerospike cluster reachable from your application host.
• The Aerospike Rust client installed in your project.
• For TLS connections, a cluster with TLS enabled and the CA certificate (and client certificate and key, for mutual TLS) available to your application. TLS and mutual TLS require Aerospike Database Enterprise Edition.

Single seed node

The client first connects to a seed node, and then discovers the rest of the cluster.

use aerospike::{Client, ClientPolicy};

let client = Client::new(&ClientPolicy::default(), &"127.0.0.1:3000").await?;

📖 API reference: Client::new

The port number can be omitted. The client defaults to port 3000.

Multiple seed nodes

Multiple seed nodes can also be provided. The client iterates through the array of nodes until it successfully connects to a node. It then discovers all nodes in the cluster.

use aerospike::{Client, ClientPolicy};

let client = Client::new(
    &ClientPolicy::default(),
    &"10.0.10.1,10.0.10.2,10.0.10.3",
)
.await?;

📖 API reference: Client::new

TLS connection without client authentication

Connect to an Aerospike cluster with TLS but without client certificate authentication:

use aerospike::{Client, ClientPolicy, TlsPolicy};
use rustls::RootCertStore;
use rustls::pki_types::CertificateDer;

fn tls_policy_no_client_auth(ca_cert_path: &str) -> TlsPolicy {
    let mut root_store = RootCertStore {
        roots: webpki_roots::TLS_SERVER_ROOTS.into(),
    };

    root_store.add_parsable_certificates(
        CertificateDer::pem_file_iter(ca_cert_path)
            .expect("Cannot open CA file")
            .map(|result| result.unwrap()),
    );

    let config = rustls::ClientConfig::builder()
        .with_root_certificates(root_store)
        .with_no_client_auth();

    TlsPolicy::new(config)
}

let mut policy = ClientPolicy::default();
policy.tls_policy = Some(tls_policy_no_client_auth("/path/to/ca-cert.pem"));

let hosts = "tls-cluster.example.com:4333";
let client = Client::new(&policy, &hosts).await?;

📖 API reference: Client::new() | ClientPolicy

TLS connection with client authentication

Connect to an Aerospike cluster with TLS and mutual authentication using client certificates:

use aerospike::{Client, ClientPolicy, TlsPolicy};
use rustls::RootCertStore;
use rustls::pki_types::{CertificateDer, PrivateKeyDer};

fn tls_policy_with_client_auth(
    ca_cert_path: &str,
    client_cert_path: &str,
    client_key_path: &str,
) -> TlsPolicy {
    let mut root_store = RootCertStore {
        roots: webpki_roots::TLS_SERVER_ROOTS.into(),
    };

    root_store.add_parsable_certificates(
        CertificateDer::pem_file_iter(ca_cert_path)
            .expect("Cannot open CA file")
            .map(|result| result.unwrap()),
    );

    let client_cert = CertificateDer::from_pem_file(client_cert_path)
        .expect("Cannot open client certificate file");
    let client_key = PrivateKeyDer::from_pem_file(client_key_path)
        .expect("Cannot open client key file");

    let config = rustls::ClientConfig::builder()
        .with_root_certificates(root_store)
        .with_client_auth_cert(vec![client_cert], client_key)
        .expect("Failed to configure client authentication");

    TlsPolicy::new(config)
}

let mut policy = ClientPolicy::default();
policy.tls_policy = Some(tls_policy_with_client_auth(
    "/path/to/ca-cert.pem",
    "/path/to/client-cert.pem",
    "/path/to/client-key.pem",
));

let hosts = "tls-cluster.example.com:4333";
let client = Client::new(&policy, &hosts).await?;

📖 API reference: Client::new() | ClientPolicy

Note

TLS is included in the default feature set for version 3.0.0. Turning default-features off also drops async, so tls alone is not enough. TLS works only with rt-tokio. Re-enable async and pick one runtime feature, for example:

[dependencies]
aerospike = { version = "3.0.0", default-features = false, features = ["async", "rt-tokio", "tls"] }

Cluster tending

Client::new() spawns a cluster-tending maintenance task on the async runtime that periodically checks node health. If a network disturbance is detected and the client can’t reach any nodes, the seed nodes are used until the client-server connection is reestablished. Configure the tend interval with ClientPolicy.tend_interval, a u32 number of milliseconds (not a std::time::Duration):

let mut policy = ClientPolicy::default();
policy.tend_interval = 5_000; // 5 seconds, expressed in milliseconds

The Aerospike Client instance is thread-safe and can be used concurrently. Most get/set calls are asynchronous and therefore non-blocking. However, you can use await or various tools found in Tokio to synchronize code. Connections are cached with a connection pool for each server node.

Cleanup

When all commands complete and the application is prepared for a clean shutdown, call the close() method to remove resources held by the Client instance.

client.close().await?;

📖 API reference: Client::close

Note

The Client instance cannot be used after calling close().

Complete example

In your Cargo.toml file:

[package]
name = "aerospike_connect_create_close"
version = "0.1.0"
edition = "2021"

[dependencies]
aerospike = { version = "3.0.0", features = ["rt-tokio"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

In your src/main.rs file:

#[macro_use]
extern crate aerospike;

use aerospike::{
    as_bin, as_key,
    policy::RecordExistsAction,
    Client, ClientPolicy, WritePolicy,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to localhost Aerospike node (default port 3000).
    let client = Client::new(&ClientPolicy::default(), &"127.0.0.1:3000").await?;
    // Create a new record in namespace "test".
    let key = as_key!("test", "demo", "example-key-1");
    let bin1 = as_bin!("message", "hello from rust");
    let bin2 = as_bin!("count", 1);
    let mut write_policy = WritePolicy::default();
    // Enforce "create only" semantics: fail if record already exists.
    write_policy.record_exists_action = RecordExistsAction::CreateOnly;
    client.put(&write_policy, &key, &vec![bin1, bin2]).await?;
    println!("Record created successfully.");
    // Close client connection cleanly.
    client.close().await?;
    println!("Client closed.");
    Ok(())
}

📖 API reference: Client::new | Client::put | Client::close

Run the example with cargo run.

Expected output

Record created successfully.
Client closed.

Troubleshooting

Connection refused or timed out

Error: Unable to communicate with server cluster: ...
Error: Client Timeout: ...

• Verify the Aerospike server is running and reachable: nc -zv <host> 3000.
• Confirm the host and port match the seed nodes in Client::new().
• Check for a firewall blocking the connection.

TLS handshake failed

Error: ... failed to parse CA certificate ...

• Verify the certificate paths passed to tls_policy_no_client_auth() or tls_policy_with_client_auth() are correct and readable.
• Confirm the cluster has TLS enabled and is Aerospike Database Enterprise Edition.
• Check certificate expiration: openssl x509 -enddate -noout -in CA_CERT.pem.

Next steps

Create records

Ready for more code examples? We have usage examples for all the basic CRUD operations.

Create records →

Error handling

Actionable errors with recovery suggestions. Know exactly what went wrong and how to fix it.

Error handling →