Skip to content

Connecting

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Use the Aerospike Go client to connect and periodically ping nodes for cluster status by creating a Client object to specify the IP address and port of one or more cluster seed nodes.

Single seed node

When creating a new Client object, specify the server to connect to using the IP address and port. The client makes initial contact with the specified server, then automatically discovers all other cluster nodes.

To create a new Client object:

import (
  "log"


  as "github.com/aerospike/aerospike-client-go/v8"
)


client, err := as.NewClient("127.0.0.1", 3000)
if err != nil {
  log.Fatal(err)
}
defer client.Close()


// Fill the connection pool before serving traffic.
if _, err := client.WarmUp(0); err != nil {
  log.Fatal(err)
}

WarmUp opens connections on every node. Pass a positive count to open that many connections per node, or pass 0 to fill the pool to ClientPolicy.ConnectionQueueSize. One connection per node is reserved for cluster tending and is not used for commands.

Passing 0 opens ConnectionQueueSize connections, 100 by default, on every node at once. The total is that count multiplied by the number of nodes and by the number of application instances starting up, and it counts against the server’s proto-fd-max. Passing 0 suits a single instance against a small cluster, as in this example. Pass an explicit count instead where many instances connect to a large cluster, and size it using the connection pool guidance in Best practices.

Multiple seed nodes

To connect to any node in the cluster, specify each node in the cluster when creating the client. The client iterates through the array of nodes until it successfully connects to a node, then it discovers the other cluster nodes.

import (
  "log"


  as "github.com/aerospike/aerospike-client-go/v8"
)


hosts := []*as.Host{
  as.NewHost("a.host", 3000),
  as.NewHost("another.host", 3000),
  as.NewHost("and.another.host", 3000),
}


client, err := as.NewClientWithPolicyAndHost(nil, hosts...)
if err != nil {
  log.Fatal(err)
}
defer client.Close()

The NewClient initializer creates a maintenance goroutine to periodically ping nodes for cluster status. The Client instance is goroutine-safe and can be used concurrently.

Each Get and Put call blocks until the command completes or times out. Connections are cached in a connection pool for each server node.

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 for more information about setting up TLS on your Aerospike Database server.

Set the certificate name on Host.TLSName. The client clones ClientPolicy.TlsConfig for each connection and sets ServerName from Host.TLSName. If TLSName is empty, the client falls back to ClientPolicy.ClusterName, then to Host.Name. When you dial by IP address, set Host.TLSName to the certificate CN or SAN, which is usually the server tls-name.

In the following example, set the credential variables clientPolicy.User and clientPolicy.Password to the correct values for your database configuration.

Supply caCertAsString, credentialID, and credentialSecret from your own configuration or secret store. Do not hard-code credentials in source, and do not log them: the client does not redact them for you.

import (
  "crypto/tls"
  "crypto/x509"
  "log"


  as "github.com/aerospike/aerospike-client-go/v8"
)


serverPool := x509.NewCertPool()
if ok := serverPool.AppendCertsFromPEM([]byte(caCertAsString)); !ok {
  log.Fatal("unable to parse CA certificate")
}


host := as.NewHost("127.0.0.1", 4333)
host.TLSName = "example.server"


clientPolicy := as.NewClientPolicy()
clientPolicy.User = credentialID
clientPolicy.Password = credentialSecret
clientPolicy.TlsConfig = &tls.Config{
  RootCAs:    serverPool,
  MinVersion: tls.VersionTLS12,
}


client, err := as.NewClientWithPolicyAndHost(clientPolicy, host)
if err != nil {
  log.Fatalf("Failed to connect to Aerospike: %v", err)
}
defer client.Close()


if _, err := client.WarmUp(0); err != nil {
  log.Fatal(err)
}

See Managing mTLS with the Go client for mutual authentication TLS (mTLS) configuration, including client certificates and PKI-based authentication.

Cleaning up

When all commands complete and the application is ready for a clean shutdown, call the Close() method to free resources held by the Client object. The Client object cannot be used after a Close() call.

client.Close()