---
title: "Connecting"
description: "Connect Aerospike Java clients using seed nodes, user authentication, TLS/mTLS security, and data compression."
---

# Connecting

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

To connect to an Aerospike database, create an `AerospikeClient` object that specifies the IP address and port of one or more seed nodes in the cluster.

## Single Seed Node

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

```java
import com.aerospike.client.AerospikeClient;

AerospikeClient client = new AerospikeClient("127.0.0.1", 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.

```java
import com.aerospike.client.AerospikeClient;

import com.aerospike.client.Host;

import com.aerospike.client.policy.ClientPolicy;

Host[] hosts = new Host[] {

    new Host("a.host", 3000),

    new Host("another.host", 3000),

    new Host("and.another.host", 3000)

};

AerospikeClient client = new AerospikeClient(new ClientPolicy(), hosts);
```

## User Authentication

Aerospike enterprise servers may require user authentication.

```java
import com.aerospike.client.AerospikeClient;

import com.aerospike.client.Host;

import com.aerospike.client.policy.ClientPolicy;

Host[] hosts = new Host[] {

    new Host("a.host", 3000),

    new Host("another.host", 3000),

    new Host("and.another.host", 3000)

};

ClientPolicy policy = new ClientPolicy();

policy.user = "myuser";

policy.password = "mypass";

AerospikeClient client = new AerospikeClient(policy, hosts);
```

## TLS secured connection

TLS connections require certificate configuration on both client and server. The TLS connection port is usually set to 4333 instead of the typically unsecured port 3000. See [TLS configuration](https://aerospike.com/docs/database/manage/network/tls/) for more information about setting up TLS on your Aerospike Database. See [mTLS](https://aerospike.com/docs/develop/client/java/mtls/) for more information about configuring a Java application to connect to an Aerospike cluster that uses mutual authentication TLS (mTLS).

A Java application that connects to an Aerospike cluster using TLS:

-   Must enable TLS in the client policy.
-   Must specify the host’s TLS name.
-   Must use the TrustStore with the CA certificate.
-   Must use the KeyStore with the client certificate chain (for mTLS only).
-   Should log Aerospike debug messages.
-   Should log debug messages during the TLS handshake when troubleshooting.

The client TLS name (`clusterTLSName` in this example) should match either the certificate common name (CN) or the certificate subject alternative name. Usually, the client TLS name is also the server’s `tls-name` configuration value.

### Add CA certificate to Java TrustStore on client nodes

The CA certificate is a public certificate which verifies that the certificate presented by the Aerospike Database is signed by a trusted authority.

Replace all placeholder certificate filenames with the correct filenames for your system.

1.  The following command imports `example.ca.crt` into a new Java TrustStore named `example.ca.jks`. The new TrustStore will be used exclusively by the intended Java application.

Terminal window

```bash
keytool -importcert -storetype jks -alias example.ca \

-keystore example.ca.jks -file example.ca.crt \

-storepass changeit
```

Create a strong password

The previous example follows the Java convention of using “changeit” as the password. Change this to a strong password governed by your organization’s password policy.

2.  Verify the certificate is in the TrustStore with the `keystore -list` command:

Terminal window

```bash
keytool -list -keystore example.ca.jks -storepass changeit

Keystore type: jks

Keystore provider: SUN

Your keystore contains 1 entry

example.ca, Apr 5, 2022, trustedCertEntry,

Certificate fingerprint (SHA1): 85:99:36:F8:20:A7:42:AA:ED:E6:9B:7B
```

The entry is listed as `trustedCertEntry`. This file can be stored on the filesystem with other public certificates.

Truststore Storage

Do not import the CA certificate into the default _system-wide_ TrustStore of trusted CA certificates used by the Java runtime. Default system-wide trusted CA certificates present security issues, and are not allowed by many enterprise security requirements.

The `TlsPolicy` can also be configured to limit protocols or ciphers, and to revoke certificates. See [documentation](https://javadoc.io/doc/com.aerospike/aerospike-client-jdk21/latest/com/aerospike/client/policy/TlsPolicy.html) for client TLS configuration options.

```java
import com.aerospike.client.AerospikeClient;

import com.aerospike.client.Host;

import com.aerospike.client.policy.ClientPolicy;

import com.aerospike.client.policy.TlsPolicy;

Host host = new Host("192.168.10.10", "clusterTLSName", 4333);

TlsPolicy tlsPolicy = new TlsPolicy();

ClientPolicy policy = new ClientPolicy();

policy.tlsPolicy = tlsPolicy;

AerospikeClient client = new AerospikeClient(policy, host);
```

## TLS secured connection with PKI authentication

TLS connections can be extended with PKI authentication. PKI user authentication specifies that the username is located directly in the client certificate’s common name (CN). PKI requires that mutual authentication (both client and server validate each other’s certificates) is configured on the server. The server must examine the client’s certificate to obtain the username.

```java
import com.aerospike.client.AerospikeClient;

import com.aerospike.client.Host;

import com.aerospike.client.policy.AuthMode;

import com.aerospike.client.policy.ClientPolicy;

import com.aerospike.client.policy.TlsPolicy;

Host host = new Host("192.168.10.10", "clusterTLSName", 4333);

TlsPolicy tlsPolicy = new TlsPolicy();

ClientPolicy policy = new ClientPolicy();

policy.tlsPolicy = tlsPolicy;

policy.authMode = AuthMode.PKI;

AerospikeClient client = new AerospikeClient(policy, host);
```

## Compression

You can enable data compression on both the client side and the server side. The Java client uses zlib (DEFLATE) for compression. For information about configuring compression on the server side, see [Configuring Storage Compression](https://aerospike.com/docs/database/manage/namespace/storage/compression).

::: note
Use of compression requires Aerospike Database Enterprise Edition.
:::

Compression only applies to commands whose payload exceeds a 128-byte threshold. Setting `policy.compress = true` on a command with a smaller payload has no effect, since the client skips compression below that size.

```java
AerospikeClient client = new AerospikeClient("localhost", 3000);

String sighting = "{\"sighting\": {\"occurred\": 20200912, \"reported\": 20200916, \"posted\": 20201105, \"report\": {\"city\": \"Kirkland\", \"duration\": \"~30 minutes\", \"shape\": [\"circle\"], \"state\": \"WA\", \"summary\": \"4 rotating orange lights in the Kingsgate area above the Safeway. Around 9pm the power went out in the Kingsgate area.  Four lights were spotted rotating above the local Safeway and surrounding streets.  They were rotating fast but staying relatively in the same spots.  Also described as orange lights. About thirty minutes later they disappeared.  The second they disappeared the power was restored.  Later a station of police from Woodinville and Kirkland came to guard the street where it happened.  They wouldn't let anyone go past the street, putting out search lights and flare signals so people couldn't drive past Safeway.  The police also would not let people walk past to go home.\"}, \"location\": \"\\\"{\\\"type\\\":\\\"Point\\\",\\\"coordinates\\\":[-122.1966441,47.69328259]}\\\"\"}}";

Key compressExampleKey = new Key("sandbox", "ufo", Value.get(1));

// Create write policy and enable compression on the policy

WritePolicy policy = client.copyWritePolicyDefault();

policy.compress = true;

client.put(policy, compressExampleKey, new Bin("sighting", Value.get(sighting)));

// Create read policy and enable compression on the policy

Policy readPolicy = client.copyReadPolicyDefault();

readPolicy.compress = true;

client.get(readPolicy, compressExampleKey);
```

## Connection failure at startup

By default, `ClientPolicy.failIfNotConnected` is `true`, so the `AerospikeClient` constructor throws a connection exception if it cannot reach any seed node at startup.

Set `ClientPolicy.failIfNotConnected` to `false` to allow the client to construct successfully even when no seed node is reachable. In this case, the client stays in a disconnected state and retries connecting in the background, automatically becoming usable once connectivity is restored.

## Maintenance Thread

The AerospikeClient constructor creates a maintenance thread that periodically pings nodes for cluster status. If a network disturbance is detected and the client can‘t reach any nodes, the seed nodes are used until client-server connection is reestablished.

The AerospikeClient instance is thread-safe and can be used concurrently. Connections are cached with connection pool(s) 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 AerospikeClient object.

```java
client.close();
```

::: note
The `AerospikeClient` object cannot be used after calling `close()`.
:::