Quick start

This Quick Start guide walks you through the essentials of deploying an Aerospike Database and building a simple application to interact with it. You’ll learn how to quickly spin up a local development environment using Docker, set up your project in your preferred programming language, connect to the database, and perform basic read and write operations.

Tip

This Quick Start assumes a basic understanding of application development and experience issuing commands in a terminal.

Deploy Aerospike with Docker

The quickest and easiest way to get up and running quickly is with Docker.

The following command creates a single node Aerospike Enterprise database, using the latest version, equipped with a single node feature key and template configuration. No additional setup is needed.

docker run -d --name aerospike -p 3000-3002:3000-3002 aerospike/aerospike-server:latest

If you’d like to customize your deployment, see configuring Aerospike for more information. Aerospike has a variety of options when it comes to deploying the database.

• AeroLab is a community-supported tool for quickly spinning up development clusters.
• You can deploy containers directly using Docker or Kubernetes Operator.
• Aerospike supports the three major cloud providers, AWS, GCP, and Azure.
• Bare metal deployments are available with a variety of Linux distributions as well.

Set up your development environment

Grab your favorite IDE and create a new project.

Java

For this quick start we’ll be using Maven for our build manager. After creating your project, add the following dependency to the pom.xml file.

<dependencies>
    <dependency>
        <groupId>com.aerospike</groupId>
        <artifactId>aerospike-client</artifactId>
        <version>7.0.0</version>
    </dependency>
</dependencies>

If you’re using a different build manager, or looking for more information on getting started with the Java client, check out the Java client install docs.

C#

The compiled C# client library dll is available on NuGet. To install, run the following command in the Package Manager Console.

PM> Install-Package Aerospike.Client

If you’re looking for more information on getting started with the C# client, check out the C# client install docs.

Go

After setting up your Go project, run the following to get the Aerospike Go Client in your $GOPATH.

go get github.com/aerospike/aerospike-client-go/v7@v7.6.0
go run -tags as_proxy main.go

If you’re looking for more information on getting started with the Go client, check out the Go client install docs.

Python

Using Python3 and pip, run the following command to install the Aerospike client.

python3 -m pip install aerospike

If you’re looking for more information on getting started with the Python client, check out the Python client install docs.

Node.js

Using npm to install Aerospike, run the following command inside your project directory.

npm install aerospike

If you’re looking for more information on getting started with the Node.js client, check out the Node.js client install docs.

Application basics

The following code block contains the necessary imports and basic application shell to get started.

Java

package com.sample;

import com.aerospike.client.IAerospikeClient;
import com.aerospike.client.AerospikeClient;
import com.aerospike.client.AerospikeException;
import com.aerospike.client.Bin;
import com.aerospike.client.Host;
import com.aerospike.client.Key;
import com.aerospike.client.Record;
import com.aerospike.client.policy.WritePolicy;
import com.aerospike.client.policy.Policy;

public class App
{
    public static void main( String[] args )
    {

    }
}

C#

using System;
using Aerospike.Client;

public class App
{
    public static void main()
    {

    }
}

Go

package main

import (
  "log"
  "time"
  "github.com/aerospike/aerospike-client-go/v7@v7.6.0"
)

func main() {

}

Python

import aerospike
from aerospike import exception as ex

Node.js

const Aerospike = require('aerospike');

const main = async () => {

}

main();

Client connection

The minimum information you need to connect to an Aerospike database is the server IP address and port number. If you’re using the basic Docker install from step one, the following information should work just fine.

If your database is deployed with a cloud provider or installed elsewhere, you’ll need information specific to your cluster setup.

Create variables to store the connection information, as well as the namespace and set name.

Using the address and port from above, instantiate the Aerospike client.

Java

String address = "127.0.0.1";   // Aerospike address
Integer port = 3000;            // Aerospike port
String namespace = "test";      // Cluster namespace
String set = "foo";             // Set name within namespace

IAerospikeClient client = new AerospikeClient(address, port);

C#

string address = "127.0.0.1";   // Aerospike address
int port = 3000;                // Aerospike port
string name_space = "test";     // Cluster namespace
string set = "foo";             // Set name within namespace

AerospikeClient client = new AerospikeClient(null, new Host(address, port));

Go

address := "127.0.0.1"          // Aerospike address
port := 3000                    // Aerospike port
namespace := "test"             // Cluster namespace
set := "foo"                    // Set name within namespace

// Create the client and connect to the database
client, err := aerospike.NewClient(address, port)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

Python

address = "127.0.0.1"   # Aerospike address
port = 3000       # Aerospike port
namespace = "test"      # Cluster namespace
setname = "foo"      # Set name within namespace

client = aerospike.client({'hosts': [(address, port)]})

Node.js

const address = "127.0.0.1";    // Aerospike address
const port = "3000";            // Aerospike port
const namespace = "test";       // Cluster namespace
const set = "foo";              // Set name within namespace

let client = await Aerospike.connect({ hosts: `${address}:${port}` });

Write a record

Java

1. Create a WritePolicy to set the totalTimeout for writes.

   WritePolicy writePolicy = new WritePolicy();
   writePolicy.totalTimeout = 5000;

2. Create the record key, a tuple consisting of namespace, set name, and user defined key

   Key key = new Key(namespace, set, "bar");

3. Create a bin to store data within the new record

   Bin bin = new Bin("myBin", "Hello World!");

4. Write the record to Aerospike.

   try {
       client.put(writePolicy, key, bin);
       System.out.println("Successfully wrote record");
   }
   catch (AerospikeException e) {
       e.printStackTrace();
   }

C#

1. Create a WritePolicy to set the totalTimeout for writes.

   WritePolicy writePolicy = new WritePolicy();
   writePolicy.totalTimeout = 5000;

2. Create the record key, a tuple consisting of namespace, set name, and user defined key

   Key key = new Key(name_space, set, "bar");

3. Create a bin to store data within the new record

   Bin bin = new Bin("myBin", "Hello World!");

4. Write the record to Aerospike.

   try
   {
       client.Put(writePolicy, key, bin);
       Console.WriteLine("Successfully wrote record");
   }
   catch (AerospikeException e)
   {
       Console.WriteLine(e);
   }

Go

1. Create a WritePolicy to set the TotalTimeout for writes.

   writePolicy := aerospike.NewWritePolicy(0, 0)
   writePolicy.TotalTimeout = 5000 * time.Millisecond

2. Create the record key, a tuple consisting of namespace, set name, and user defined key

   key, err := aerospike.NewKey(namespace, set, "bar")
   if err != nil {
       log.Fatal(err)
   }

3. Create a bin to store data within the new record

   bin := aerospike.NewBin("myBin", "Hello World!")

4. Write the record to Aerospike.

   err = client.PutBins(writePolicy, key, bin)
   if err != nil {
       log.Fatal(err)
   }
   log.Println("Succesfully wrote record")

Python

1. Create a WritePolicy to set the totalTimeout for writes.

   write_policy = {'total_timeout': 5000}

2. Create the record key, a tuple consisting of namespace, set name, and user defined key

   key = (namespace, setname, "bar")

3. Create a bin to store data within the new record

   bins = {'myBin': 'Hello World!'}

4. Write the record to Aerospike.

   try:
       client.put(key, bins, policy=write_policy)
       print("Successfully wrote record")
   except ex.ClientError as e:
       print(e)

Node.js

1. Create a WritePolicy to set the totalTimeout for writes.

   let writePolicy = new Aerospike.WritePolicy({
       totalTimeout: 5000
   });

2. Create the record key, a tuple consisting of namespace, set name, and user defined key

   let key = new Aerospike.Key(namespace, set, "bar");

3. Create a bin to store data within the new record

   let bin = { myBin: "Hello World!" };

4. Write the record to Aerospike.

   try {
       await client.put(key, bin, [], writePolicy);
       console.info("Successfully wrote record");
   }
   catch (err) {
       console.error(err);
   }

Read a record

Java

1. Create a Policy to set the totalTimeout for reads.

   Policy readPolicy = new Policy();
   readPolicy.totalTimeout = 5000;

2. Using the same key from our write command, read the record back.

   try {
       Record record = client.get(readPolicy, key);
       System.out.format("Record: %s", record.bins);
   }
   catch (AerospikeException e) {
       e.printStackTrace();
   }
   finally {
       client.close();
   }

C#

1. Create a Policy to set the totalTimeout for reads.

   Policy readPolicy = new Policy();
   readPolicy.totalTimeout = 5000;

2. Using the same key from our write command, read the record back.

   try
   {
       client.Get(readPolicy, key);
       Console.WriteLine("Record: {0}", record);
   }
   catch (AerospikeException e)
   {
       Console.WriteLine(e);
   }
   finally
   {
       client.Close();
   }

Go

1. Create a Policy to set the TotalTimeout for reads.

   readPolicy := aerospike.NewPolicy()
   readPolicy.TotalTimeout = 5000 * time.Millisecond

2. Read the record.

   record, err := client.Get(readPolicy, key)
   if err != nil {
       log.Fatal(err)
   }
   
   log.Printf("Record: %s", record.Bins)

Python

1. Create a Policy to set the totalTimeout for reads.

   read_policy = {'total_timeout': 5000}

2. Using the same key from our write command, read the record back.

   try:
       (key_, meta, bins) = client.get(key, policy=read_policy)
       print(bins)
   except ex.ClientError as e:
       print(e)
   finally:
       client.close()

Node.js

1. Create a Policy to set the totalTimeout for reads.

   let readPolicy = new Aerospike.ReadPolicy({
       totalTimeout: 5000
   });

2. Using the same key from our write command, read the record back.

   try {
       let record = await client.get(key, readPolicy);
       console.info("Record: %o", record);
   }
   catch (err) {
       console.error(err);
   }
   finally {
       client.close();
   }

Check out the Develop topic for more in-depth code samples and content to help you get started!

Put it all together

Check out the full code sample

Java

package com.sample;

import com.aerospike.client.IAerospikeClient;
import com.aerospike.client.AerospikeClient;
import com.aerospike.client.AerospikeException;
import com.aerospike.client.Bin;
import com.aerospike.client.Host;
import com.aerospike.client.Key;
import com.aerospike.client.Record;
import com.aerospike.client.policy.WritePolicy;
import com.aerospike.client.policy.Policy;

public class App
{
    public static void main( String[] args )
    {
        // ***
        // Setup
        // ***

        String address = "127.0.0.1";   // Aerospike address
        Integer port = 3000;            // Aerospike port
        String namespace = "test";      // Cluster namespace
        String set = "foo";             // Set name within namespace

        // Create the client and connect to the database
        IAerospikeClient client = new AerospikeClient(address, port);

        // ***
        // Write a record
        // ***

        // Create a new write policy
        WritePolicy writePolicy = new WritePolicy();
        writePolicy.totalTimeout = 5000;

        // Create the record key
        // A tuple consisting of namespace, set name, and user defined key
        Key key = new Key(namespace, set, "bar");

        // Create a bin to store data within the new record
        Bin bin = new Bin("myBin", "Hello World!");

        //Write the record to your database
        try {
            client.put(writePolicy, key, bin);
            System.out.println("Successfully wrote record");
        }
        catch (AerospikeException e) {
            e.printStackTrace();
        }

        // ***
        // Read back the record we just wrote
        // ***

        // Create a new read policy
        Policy readPolicy = new Policy();
        readPolicy.totalTimeout = 5000;

        // Read the record
        try {
            Record record = client.get(readPolicy, key);
            System.out.format("Record: %s", record.bins);
        }
        catch (AerospikeException e) {
            e.printStackTrace();
        }
        finally {
            client.close();
        }
    }
}

C#

using System;
using Aerospike.Client;

public class App
{
    public static void main()
    {
        // ***
        // Setup
        // ***

        string address = "127.0.0.1";   // Aerospike address
        int port = 3000;                // Aerospike port
        string namespace = "test";      // Cluster namespace
        string set = "foo";             // Set name within namespace

        // Create the client and connect to the database
        AerospikeClient client = new AerospikeClient(null, new Host(address, port));

        // ***
        // Write a record
        // ***

        // Create a new write policy
        WritePolicy writePolicy = new WritePolicy();
        writePolicy.totalTimeout = 5000;

        // Create the record key
        // A tuple consisting of namespace, set name, and user defined key
        Key key = new Key(namespace, set, "bar");

        // Create a bin to store data within the new record
        Bin bin = new Bin("myBin", "Hello World!");

        //Write the record to your database
        try
        {
            client.Put(writePolicy, key, bin);
            Console.WriteLine("Successfully wrote record");
        }
        catch (AerospikeException e)
        {
            Console.WriteLine(e);
        }

        // ***
        // Read back the record we just wrote
        // ***

        // Create a new read policy
        Policy readPolicy = new Policy();
        readPolicy.totalTimeout = 5000;

        // Read the record
        try
        {
            Record record = client.Get(readPolicy, key);
            Console.WriteLine("Record: {0}", record);
        }
        catch (AerospikeException e)
        {
            Console.WriteLine(e);
        }
        finally
        {
            client.Close();
        }
    }
}

Go

package main

import (
  "log"
  "time"
  "github.com/aerospike/aerospike-client-go/v7@v7.6.0"
)

func main() {
  // ***
  // Setup
  // ***

  address := "127.0.0.1"      // Aerospike address
  port := 3000                // Aerospike port
  namespace := "test"         // Cluster namespace
  set := "foo"                // Set name within namespace

  // Create the client and connect to the database
  client, err := aerospike.NewClient(address, port)
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close()

  // ***
  // Write a record
  // ***

  // Create a WritePolicy to set the TotalTimeout for writes
  // default 1000 ms
  writePolicy := aerospike.NewWritePolicy(0, 0)
  writePolicy.TotalTimeout = 5000 * time.Millisecond

  // Create the record key
  // A tuple consisting of namespace, set name, and user defined key
  key, err := aerospike.NewKey(namespace, set, "bar")
  if err != nil {
    log.Fatal(err)
  }

  // Create a bin to store data within the new record
  bin := aerospike.NewBin("myBin", "Hello World!")

  //Write the record to your database
  err = client.PutBins(writePolicy, key, bin)
  if err != nil {
    log.Fatal(err)
  }
  log.Println("Succesfully wrote record")

  // ***
  // Read back the record we just wrote
  // ***

  // Create a Policy to set the TotalTimeout for reads
  // default 1000 ms
  readPolicy := aerospike.NewPolicy()
  readPolicy.TotalTimeout = 5000 * time.Millisecond

  // Read the record
  record, err := client.Get(readPolicy, key)
  if err != nil {
    log.Fatal(err)
  }

  log.Printf("Record: %s", record.Bins)
}

Python

import aerospike

# ***
# Setup
# ***

address = "127.0.0.1"       # Aerospike address
port = 3000                 # Aerospike port
namespace = "test"          # Cluster namespace
setname = "foo"             # Set name within namespace

# Create the client and connect to the database
client = aerospike.client({'hosts': [(address, port)]})

# ***
# Write a record
# ***

# Create a new write policy
write_policy = {'total_timeout': 5000}

# Create the record key
# A tuple consisting of namespace, set name, and user defined key
key = (namespace, setname, "bar")

# Create a bin to store data within the new record
bins = {'myBin': 'Hello World!'}

# Write the record to your database
try:
    client.put(key, bins, policy=write_policy)
    print("Successfully wrote record")
except ex.ClientError as e:
    print(e)

# ***
# Read back the record we just wrote
# ***

# Create a new read policy
read_policy = {'total_timeout': 5000}

# Read the record
try:
    (key_, meta, bins) = client.get(key, policy=read_policy)
    print(bins)
except ex.ClientError as e:
    print(e)
finally:
    client.close()

Node.js

const Aerospike = require('aerospike');

const main = async () => {
    // ***
    // Setup
    // ***

    const address = "127.0.0.1";    // Aerospike address
    const port = "3000";            // Aerospike port
    const namespace = "test";       // Cluster namespace
    const set = "foo";              // Set name within namespace

    // Create the client and connect to the database
    let client = await Aerospike.connect({ hosts: `${address}:${port}` });

    // ***
    // Write a record
    // ***

    // Create a new write policy
    let writePolicy = new Aerospike.WritePolicy({
        totalTimeout: 5000
    });

    // Create the record key
    // A tuple consisting of namespace, set name, and user defined key
    let key = new Aerospike.Key(namespace, set, "bar");

    // Create a bin to store data within the new record
    let bin = { myBin: "Hello World!" };

    //Write the record to your database
    try {
        await client.put(key, bin, [], writePolicy);
        console.info("Successfully wrote record");
    }
    catch (err) {
        console.error(err);
    }

    // ***
    // Read back the record we just wrote
    // ***

    // Create a new read policy
    let readPolicy = new Aerospike.ReadPolicy({
        totalTimeout: 5000
    });

    // Read the record
    try {
        let record = await client.get(key, readPolicy);
        console.info("Record: %o", record);
    }
    catch (err) {
        console.error(err);
    }
    finally {
        client.close();
    }
}

main();