Getting Started

This guide starts one supervised Aerospike cluster connection, writes a record, reads it back, and shuts the connection down.

Start Aerospike

From the repository root, start the default Community Edition container:

docker compose up -d

Then run iex -S mix from the package directory.

Start A Client

For application code, define a Repo module that owns one Aerospike cluster name:

defmodule MyApp.Repo do
  use Aerospike.Repo, otp_app: :my_app
end

Configure the Repo under its module name:

config :my_app, MyApp.Repo,
  transport: Aerospike.Transport.Tcp,
  hosts: ["127.0.0.1:3000"],
  namespaces: ["test"],
  pool_size: 2

Then add the Repo to your supervision tree:

def start(_type, _args) do
  children = [
    MyApp.Repo
  ]

  Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
end

The Repo uses its module name as the default cluster name. To use a different registered name, pass :name to use Aerospike.Repo.

Readiness is separate from supervision startup. Startup validates the options and starts the processes; Aerospike.Cluster.ready?/1 reports whether the client has published a routable cluster view.

true = Aerospike.Cluster.ready?(MyApp.Repo.conn())

Aerospike.Repo is a thin facade over the canonical Aerospike API. It does not perform schema mapping, changeset validation, or object reflection.

For scripts, experiments, or custom lifecycle management, you can still start a cluster directly:

{:ok, _pid} =
  Aerospike.start_link(
    name: :aerospike,
    transport: Aerospike.Transport.Tcp,
    hosts: ["127.0.0.1:3000"],
    namespaces: ["test"],
    pool_size: 2
  )

Write And Read

Build keys with MyApp.Repo.key/3. Bin maps may use string or atom keys, but string bin names are the clearest match for server-side data.

key = MyApp.Repo.key("test", "users", "user:1")

{:ok, metadata} =
  MyApp.Repo.put(key, %{
    "name" => "Ada",
    "visits" => 1
  })

{:ok, record} = MyApp.Repo.get(key)

metadata.generation
record.bins["name"]

Read only selected bins by passing a list as the second argument:

{:ok, record} = MyApp.Repo.get(key, ["name"])

Use get_header/1 when only metadata is needed:

{:ok, header} = MyApp.Repo.get_header(key)

Close The Client

The Repo closes its supervised cluster by the configured registered name.

:ok = MyApp.Repo.close()

Next Steps

• Record Operations covers single-record helpers and operation lists.
• Batch Operations covers multi-key helpers and heterogeneous batch requests.
• Operate, CDT, And Geo covers server-side list, map, bit, HyperLogLog, expression, and geo patterns.
• Queries And Scans covers scan streams, secondary-index queries, paging, and node targeting.
• Transactions covers Enterprise multi-record transaction usage and current lifecycle boundaries.