Sync ClusterDefinition & Host¶

ClusterDefinition - Builder for configuring Aerospike cluster connections (sync version).

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

Bases: object

Represents an Aerospike server host.

__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.

Return type:: Host

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)

Return type:: List[Host]

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

Bases: object

Sync builder for seeds, auth, TLS, and validation; connect() returns Cluster.

Mirrors ClusterDefinition with blocking connect() and context-manager support on Cluster.

Example:

with (
    ClusterDefinition("localhost", 3100)
    .with_native_credentials("username", "password")
    .connect()
) as cluster:
    session = cluster.create_session(Behavior.DEFAULT)

See also

ClusterDefinition

__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

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

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 ClusterDefinition for method 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 ClusterDefinition for method 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 ClusterDefinition for method 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 ClusterDefinition for method 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 ClusterDefinition for method chaining.

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

connect()[source]¶

Establishes a connection to the Aerospike cluster (synchronously).

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 context manager:

with 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