ClusterDefinition & Host¶

ClusterDefinition - Builder for configuring Aerospike cluster connections.

class aerospike_sdk.aio.cluster_definition.Host[source]¶

Bases: object

Seed address for cluster discovery.

Example:

host = Host("192.168.1.10", 3000)
# or use the convenience parser
hosts = Host.parse_hosts("host1:3000,host2:3000", 3000)

__init__(name, port, tls_name=None)[source]¶

Initialize a Host.

Parameters:

name (str) – Hostname or IP address
port (int) – Port number
tls_name (Optional[str]) – Optional TLS name for certificate validation

static of(name, port)[source]¶

Create a Host instance.

Parameters:

name (str) – Hostname or IP address.
port (int) – Port number.

Return type:

Host

Returns:

A Host with the given name and port.

static parse_hosts(host_string, default_port)[source]¶

Parse a host string into a list of Host objects.

Format: host1:port1,host2:port2 or host1,host2 (uses default_port).

Raises:: ValueError – If a port segment is present but not a valid integer.
Return type:: List[Host]

class aerospike_sdk.aio.cluster_definition.ClusterDefinition[source]¶

Bases: object

Configure seeds, auth, TLS, rack awareness, and validation before connect().

Call connect() to obtain a live Cluster. The sync counterpart lives under aerospike_sdk.sync.cluster_definition.

Example:

cluster = await (
    ClusterDefinition("localhost", 3100)
    .with_native_credentials("user", "secret")
    .using_services_alternate()
    .preferring_racks(1, 2)
    .validate_cluster_name_is("my-cluster")
    .connect()
)

See also

Cluster

__init__(hostname=None, port=None, hosts=None)[source]¶

Create a cluster definition.

Parameters:

hostname (Optional[str]) – Hostname or IP address (if single host)
port (Optional[int]) – Port number (if single host)
hosts (Union[List[Host], tuple[Host, ...], None]) – List of Host objects (if multiple hosts)

Examples

ClusterDefinition(“localhost”, 3000) ClusterDefinition(hosts=[Host.of(“host1”, 3000), Host.of(“host2”, 3000)])

with_native_credentials(user_name, password)[source]¶

Sets authentication credentials using Aerospike’s internal authentication.

Hashed password is stored on the server. Pass empty strings for both parameters to disable authentication.

Parameters:

user_name (str) – The username for authentication
password (str) – The password for authentication

Return type:

ClusterDefinition

Returns:

This ClusterDefinition for method chaining

Example:

cd = ClusterDefinition("localhost", 3000).with_native_credentials("admin", "pass123")

with_external_credentials(user_name, password)[source]¶

Sets authentication credentials using external authentication (e.g. LDAP).

External authentication is configured on the server. If TLS is configured, the clear password is sent on node login via TLS. Raises an error at connect time if TLS is not configured.

Parameters:

user_name (str) – The username for authentication
password (str) – The password for authentication

Return type:

ClusterDefinition

Returns:

This ClusterDefinition for method chaining

with_certificate_credentials()[source]¶

Configures certificate-based (PKI) authentication.

Uses client certificates instead of username/password credentials. Automatically enables TLS if not already configured. Requires server version 5.7.0+.

Return type:: ClusterDefinition
Returns:: This ClusterDefinition for method chaining
Raises:: ValueError – If any host is missing a TLS name

property auth_mode: AuthMode¶: The current authentication mode.

validate_cluster_name_is(cluster_name)[source]¶

Validates that the cluster name matches the expected value.

This enables cluster name validation to ensure the client connects to the expected cluster. If the actual cluster name doesn’t match, the connection will fail.

Parameters:: cluster_name (str) – The expected cluster name to validate against
Return type:: ClusterDefinition
Returns:: This ClusterDefinition for method chaining

Example:

cd = ClusterDefinition("localhost", 3000).validate_cluster_name_is("my-cluster")

preferring_racks(*racks)[source]¶

Sets preferred racks for rack-aware operations.

This enables rack awareness and specifies which racks should be preferred for read operations. Rack awareness helps improve performance by reading from local racks when possible.

Parameters:: *racks (int) – The rack IDs to prefer, in order of preference
Return type:: ClusterDefinition
Returns:: This builder for chaining.

using_services_alternate()[source]¶

Enables the use of alternate services for cluster discovery.

When enabled, the client will use alternate service endpoints for cluster discovery, which can be useful in certain network configurations or when using service mesh solutions.

Return type:: ClusterDefinition
Returns:: This builder for chaining.

fail_if_not_connected(fail)[source]¶

Controls whether connect() raises if the cluster is unreachable.

If True (the default), connect() raises a ConnectionError when all seed connections fail or a seed connects but none of its peers are reachable.

If False, a partial cluster is created and the client will automatically connect to the remaining nodes when they become available.

Parameters:: fail (bool) – Whether to raise on connection failure.
Return type:: ClusterDefinition
Returns:: This builder for chaining.

with_ip_map(ip_map)[source]¶

Sets an IP address translation table for cluster node discovery.

Used when clients from different networks need different IP addresses to reach the same server nodes (e.g. inside vs. outside a VPN or NAT). The key is the IP address returned from server info requests; the value is the actual IP address the client should connect to.

Consider using using_services_alternate() instead, which lets the server handle address translation without client-side configuration.

Parameters:: ip_map (dict[str, str]) – Mapping of server-reported IPs to actual connection IPs
Return type:: ClusterDefinition
Returns:: This builder for chaining.

with_system_settings(settings)[source]¶

Set cluster-wide system settings (connection pool, tend interval, etc.).

Parameters:: settings (SystemSettings) – The SystemSettings to apply.
Return type:: ClusterDefinition
Returns:: This builder for chaining.

Example:

cluster = await ClusterDefinition("localhost", 3000) \
    .with_system_settings(SystemSettings(
        max_connections_per_node=200,
        tend_interval=timedelta(seconds=2),
    )) \
    .connect()

with_tls_config_of()[source]¶

Begins TLS configuration using a chainable builder pattern.

This method returns a TlsBuilder that allows you to configure various TLS settings such as TLS name, CA file, protocols, ciphers, and other TLS-specific options. Call done() on the TlsBuilder to return to this ClusterDefinition for further configuration.

Return type:: TlsBuilder
Returns:: A TlsBuilder for configuring TLS settings.

async connect()[source]¶

Establishes a connection to the Aerospike cluster.

This method creates and returns a Cluster instance using the configured parameters. The returned Cluster should be closed when no longer needed to properly release resources.

Example with async context manager:

async with await ClusterDefinition("localhost", 3100).connect() as cluster:
    session = cluster.create_session(Behavior.DEFAULT)
    # Use the session...

Return type:

Cluster

Returns:

A connected Cluster instance

Raises:

ValueError – If PKI auth is configured but hosts are missing TLS names
ConnectionError – If fail_if_not_connected is True (default) and the cluster is unreachable