Sync ClusterDefinition

class aerospike_sdk.sync.cluster_definition.ClusterDefinition

Bases: ClusterDefinitionBase

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

Mirrors ClusterDefinition with a blocking connect() and context-manager support on Cluster. Every builder method is inherited from ClusterDefinitionBase; only the blocking connect() lives here.

Example:

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

See also

ClusterDefinition

connect()

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

__init__(hostname=None, port=None, hosts=None)

Create a cluster definition.

Parameters:

• hostname (Optional[str]) – Hostname or IP address (single-host form).

• port (Optional[int]) – Port number (single-host form).

• hosts (Union[List[Host], tuple[Host, ...], None]) – List of Host objects (multi-host form).

Raises:

ValueError – If neither (hostname, port) nor hosts is given.

Example:

cd = ClusterDefinition("localhost", 3000)
cd = ClusterDefinition(hosts=[Host.of("host1", 3000), Host.of("host2", 3000)])

app_id(app_id)

Tag this client’s traffic with an application identifier.

The identifier is reported to the server (as the application portion of the client’s user-agent), letting operators attribute load per calling application. It is distinct from the client-library identifier the SDK sets automatically.

Parameters:

app_id (str) – A short label for the calling application, e.g. "billing-service".

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

cd = ClusterDefinition("localhost", 3000).app_id("billing-service")

property auth_mode: AuthMode

The current authentication mode.

cluster_name(cluster_name)

Declare the name of the cluster this definition connects to.

The client validates it against each node: nodes reporting a different cluster name are rejected, so the connection fails if none match. The name also selects the matching system.<name> profile in a dynamic SDK config file before the connection is built.

Parameters:

cluster_name (str) – The expected cluster name.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

cd = ClusterDefinition("localhost", 3000).cluster_name("prod-east")

See also

ClusterBase.cluster_name: The name the connected servers report.

fail_if_not_connected(fail)

Control 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 connects to the remaining nodes as they become available.

Parameters:

fail (bool) – Whether to raise on connection failure.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

cd = ClusterDefinition("localhost", 3000).fail_if_not_connected(False)

force_single_node(enabled=True)

Talk to the first seed only, bypassing peer discovery. Testing only.

Every other client names this force_single_node / forceSingleNode and documents it for testing, and so does the underlying flag’s own origin. Do not enable it in production.

With this set, peer discovery is skipped and the seed addresses become the whole cluster: peers reported by other nodes are ignored, seeds are retained across connection failures rather than dropped by the tend loop, and load-balancer detection is skipped so a seed address is treated as the canonical service endpoint. No tend task is spawned, so node restarts, master failover and rebalances are invisible.

Warning

On a multi-node cluster this yields partial availability, not a restricted-but-working view. The partition map still names the real owners, including nodes that discovery was told to ignore, so every partition the seed does not own becomes unroutable and its operations raise Cannot get appropriate node for namespace ... partition N. Measured against a 3-node cluster: 6 of 30 writes succeeded and 24 raised. Other clients avoid this by rewriting the partition map to point every partition at the seed; this client does not.

Use it only against a single-node cluster, or where a test or benchmark needs a node set that cannot shift under it.

Parameters:

enabled (bool) – Whether to talk to the first seed only. Defaults to True so the no-argument call reads as an enable.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

# Benchmark against a single-node cluster, with no tend noise.
cd = ClusterDefinition("localhost", 3000).force_single_node()

See also

using_services_alternate(): The production remedy when

advertised addresses are not routable — discovers peers, but addresses them by their alternate address.

ip_map(): Client-side translation of discovered

addresses.

ip_map(ip_map)

Set 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:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

cd = ClusterDefinition("localhost", 3000).ip_map({"10.0.0.1": "192.168.1.1"})

preferring_racks(*racks)

Set preferred racks for rack-aware operations.

Enables rack awareness and specifies which racks to prefer for read operations, improving performance by reading from local racks when possible.

Parameters:

*racks (int) – The rack IDs to prefer, in order of preference.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

cd = ClusterDefinition("localhost", 3000).preferring_racks(1, 2)

using_services_alternate(enabled=True)

Enable (or disable) alternate services for cluster discovery.

When enabled, the client discovers peers through each node’s alternate-access-address instead of its standard service address — useful in certain network configurations or service-mesh setups. Only enable it against a cluster that actually publishes those addresses: against one that does not, peer discovery comes back empty and the client falls back to a single node, so every key outside that node’s partitions fails to route.

Passing enabled=False is the only way to turn the setting back off once it defaults on, which it does whenever AEROSPIKE_USE_SERVICES_ALTERNATE is truthy in the environment.

Parameters:

enabled (bool) – Whether to use alternate service endpoints. Defaults to True so the no-argument call reads as an enable.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

cd = ClusterDefinition("bench-asd", 3000).using_services_alternate(False)

See also

ip_map(): Client-side address translation, for when the

cluster publishes no alternate addresses.

with_certificate_credentials()

Configure certificate-based (PKI) authentication.

The server identifies the client by its TLS client certificate instead of a user name and password, so the certificate and key must be set with with_tls_config().

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Raises:

ValueError – At connect time if no client certificate is configured or any host is missing a TLS name.

Example:

cd = (
    ClusterDefinition("db.example.com", 4333)
    .with_tls_config(
        tls_name="db.example.com",
        ca_file="/certs/ca.pem",
        client_cert_file="/certs/app.pem",
        client_key_file="/certs/app.key",
    )
    .with_certificate_credentials()
)

See also

with_tls_config(): Supplies the client certificate.

with_external_credentials(user_name, password)

Set 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:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

cd = ClusterDefinition("localhost", 3000).with_external_credentials("ldap_user", "pass")

with_external_insecure_credentials(user_name, password)

Set external (e.g. LDAP) credentials that may travel without TLS.

The same server-side external authentication as with_external_credentials(), but the clear password is sent on node login even when TLS is not configured. Use it only on a network you trust; prefer with_external_credentials() with TLS.

Parameters:

• user_name (str) – The username for authentication. An empty name clears the credentials.

• password (str) – The password for authentication.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

cd = ClusterDefinition("localhost", 3000).with_external_insecure_credentials(
    "ldap_user", "pass"
)

with_native_credentials(user_name, password)

Set 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:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

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

with_strict_config(strict=True)

Fail the connect if the SDK config file carries anything unrecognized.

By default an unrecognized key is warned about and skipped, so a config written for a different client or carrying a typo still connects — it simply does not apply the settings it names. That is the right default for a file shared across SDKs, and the wrong one if you would rather find out at deploy time than from behavior in production.

Strict mode raises on what the loader does not recognize, not on what it honors at a different scope: a key this SDK accepts elsewhere (for example wait_for_connection_to_complete, honored client-wide under system.<cluster>.connections) warns with a pointer to the right spelling and still connects.

Applies to the connect-time read only. Hot reload stays fail-soft whatever this is set to: the monitor runs in the background with no caller to raise to, so it warns and keeps the previous configuration.

Parameters:

strict (bool) – Whether to raise on unrecognized config entries. Defaults to True so the no-argument call reads as an enable.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

# Deployment-time gate: a stale key fails the rollout, not a request.
cd = ClusterDefinition("localhost", 3000).with_strict_config()

See also

with_system_settings(): Settings supplied in code, which the

file layers over.

with_system_settings(settings)

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

Parameters:

settings (SystemSettings) – The SystemSettings to apply.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Example:

from datetime import timedelta
cd = ClusterDefinition("localhost", 3000).with_system_settings(
    SystemSettings(max_connections_per_node=200, tend_interval=timedelta(seconds=2)),
)

with_tls_config(*, tls_name=None, ca_file=None, client_cert_file=None, client_key_file=None, protocols=None, ciphers=None, for_login_only=False)

Connect over TLS with these settings.

Each call replaces any earlier TLS settings on this definition. The settings are built into a TLS configuration at connect(), so that is where a missing file, an unknown protocol or cipher name, or a protocol and cipher restriction that leaves no usable suite is reported.

Parameters:

• tls_name (Optional[str]) – Name the server certificate must carry, also sent as SNI. It is applied to every Host that has no tls_name of its own.

• ca_file (Optional[str]) – PEM file of the certificate authorities that sign the server certificates. Without one, the system trust store is used.

• client_cert_file (Optional[str]) – PEM client certificate for mutual TLS. Requires client_key_file.

• client_key_file (Optional[str]) – PEM private key for client_cert_file.

• protocols (Optional[Sequence[str]]) – TLS versions to allow, for example ["TLSv1.3"]. Defaults to the client’s supported set.

• ciphers (Optional[Sequence[str]]) – Cipher-suite names to allow. Defaults to the client’s supported set. They must suit an allowed protocol: TLS 1.3 suites are separate from TLS 1.2 ones.

• for_login_only (bool) – Encrypt only the login exchange. The credential exchange runs over TLS, that connection closes once the session token is held, and every later connection to the node opens in cleartext at its cleartext service address; no socket is downgraded. Trades data-plane encryption for throughput on trusted networks, and requires credentials on this definition.

Return type:

Self

Returns:

This ClusterDefinition for method chaining.

Raises:

• ValueError – If only one of client_cert_file and client_key_file is given.

• ValueError – If protocols or ciphers is an empty list.

• TypeError – If protocols or ciphers is a single string rather than a list of names.

Example:

cd = (
    ClusterDefinition("db.example.com", 4333)
    .with_tls_config(tls_name="db.example.com", ca_file="/certs/ca.pem")
    .with_native_credentials("app", "secret")
)

See also

with_certificate_credentials(): Authenticate with the client certificate instead of a password.

Seed addresses use the shared Host class, which both the async and sync cluster definitions import from aerospike_sdk.cluster_shared.