aerospike_driver

# Policies
Policies control how commands are executed: timeouts, record-existence behavior,
generation checks (CAS), replica routing, and other per-command options.
This client uses trailing keyword options (for example `Aerospike.put(conn, key, bins, opts)`)
instead of dedicated `WritePolicy`/`ReadPolicy` structs. You can set defaults once at
`start_link/1` and override them per call.
## How Policy Resolution Works
For each command, the client merges policy options in this order:
1. Connection defaults from `start_link(defaults: [...])`
2. Per-call options passed to the command
Per-call values always win on key conflicts.
```elixir
{:ok, _pid} =
  Aerospike.start_link(
    name: :aero,
    hosts: ["127.0.0.1:3000"],
    defaults: [
      write: [timeout: 2_000, ttl: 3_600],
      read: [timeout: 1_500]
    ]
  )
# timeout is overridden to 500 ms for this call only.
:ok = Aerospike.put(:aero, key, %{"name" => "Ada"}, timeout: 500)
```
## Write Policies
Used by `put/4`, `add/4`, `append/4`, `prepend/4`.
| Option | Type | Meaning |
| --- | --- | --- |
| `:ttl` | non-negative integer | Record TTL in seconds |
| `:timeout` | non-negative integer | Command timeout in milliseconds |
| `:generation` | non-negative integer | Expected record generation |
| `:gen_policy` | `:none` \| `:expect_gen_equal` \| `:expect_gen_gt` | Generation check strategy |
| `:exists` | `:create_only` \| `:update_only` \| `:replace_only` \| `:create_or_replace` | Record existence behavior |
| `:send_key` | boolean | Store the user key on the server |
| `:durable_delete` | boolean | Tombstone-based delete behavior where applicable |
| `:filter` | `%Aerospike.Exp{}` | Server-side expression filter |
| `:pool_checkout_timeout` | non-negative integer | Pool checkout timeout in milliseconds |
| `:replica` | `:master` \| `:sequence` \| `:any` \| non-negative integer | Replica routing |
| `:txn` | `%Aerospike.Txn{}` | Transaction handle |
### Existence Policies
```elixir
# Create only if missing.
:ok = Aerospike.put(:aero, key, bins, exists: :create_only)
# Update only if present.
:ok = Aerospike.put(:aero, key, bins, exists: :update_only)
# Replace existing record bins only (no merge).
:ok = Aerospike.put(:aero, key, bins, exists: :replace_only)
# Create if absent, replace if present.
:ok = Aerospike.put(:aero, key, bins, exists: :create_or_replace)
```
### Generation Policy (CAS)
When `:generation` is provided and `:gen_policy` is omitted, the client defaults to
`gen_policy: :expect_gen_equal`.
```elixir
{:ok, rec} = Aerospike.get(:aero, key)
case Aerospike.put(:aero, key, %{"counter" => 1}, generation: rec.generation) do
  :ok ->
    :updated
  {:error, %Aerospike.Error{code: :generation_error}} ->
    :conflict
end
```
## Read Policies
Used by `get/3`.
| Option | Type | Meaning |
| --- | --- | --- |
| `:timeout` | non-negative integer | Command timeout in milliseconds |
| `:bins` | list of strings/atoms | Read only selected bins |
| `:header_only` | boolean | Read metadata (generation/ttl) without bins |
| `:read_touch_ttl_percent` | non-negative integer | Read-touch TTL percent |
| `:filter` | `%Aerospike.Exp{}` | Server-side expression filter |
| `:pool_checkout_timeout` | non-negative integer | Pool checkout timeout in milliseconds |
| `:replica` | `:master` \| `:sequence` \| `:any` \| non-negative integer | Replica routing |
| `:txn` | `%Aerospike.Txn{}` | Transaction handle |
If you pass `:bins`, it must be a non-empty list. Omit `:bins` to read all bins.
## Delete, Exists, and Touch Policies
### `delete/3`
`delete/3` accepts: `:timeout`, `:durable_delete`, `:filter`, `:pool_checkout_timeout`, `:replica`, `:txn`.
### `exists/3`
`exists/3` accepts: `:timeout`, `:filter`, `:pool_checkout_timeout`, `:replica`, `:txn`.
### `touch/3`
`touch/3` accepts: `:ttl`, `:timeout`, `:filter`, `:pool_checkout_timeout`, `:replica`, `:txn`.
## Operate Policies
`operate/4` combines read and write semantics. Supported options:
- `:ttl`
- `:timeout`
- `:generation`
- `:gen_policy`
- `:exists`
- `:send_key`
- `:durable_delete`
- `:respond_per_each_op`
- `:pool_checkout_timeout`
- `:replica`
- `:txn`
`respond_per_each_op` is specific to operate responses when multiple operations are present.
## Batch, Scan, Query, and Info Policies
### Batch (`batch_get/3`, `batch_exists/3`, `batch_operate/3`)
Supported options:
- `:timeout`
- `:pool_checkout_timeout`
- `:replica`
- `:respond_all_keys`
- `:filter`
- `:txn`
For `batch_get/3`, read options such as `:bins` and `:header_only` are also supported.
### Scan and Query (`stream!/3`, `all/3`, `count/3`, `page/3`)
Supported options:
- `:timeout`
- `:pool_checkout_timeout`
- `:replica`
### Info/Admin (`info/3`, `info_node/4`, truncate/index helpers)
Supported options:
- `:timeout`
- `:pool_checkout_timeout`
## Defaults at Startup
Set per-command defaults when starting the client:
```elixir
{:ok, _pid} =
  Aerospike.start_link(
    name: :aero,
    hosts: ["127.0.0.1:3000"],
    defaults: [
      write: [timeout: 2_000, ttl: 3_600],
      read: [timeout: 1_500],
      delete: [timeout: 1_500, durable_delete: true],
      operate: [timeout: 2_000],
      batch: [timeout: 4_000, respond_all_keys: true],
      scan: [timeout: 30_000],
      query: [timeout: 30_000]
    ]
  )
```
If a command has no configured defaults, it runs with only explicit per-call options.
## Validation and Error Shape
All policy options are validated. Invalid options return:
```elixir
{:error, %Aerospike.Error{code: :parameter_error}}
```
Use this to fail fast on typos and invalid values (for example unsupported atoms for `:exists`).
## Practical Recommendations
- Set conservative `:timeout` defaults at connection start.
- Use `:generation` (+ optional `:gen_policy`) for concurrent updates.
- Use `exists: :create_only` for idempotent create flows.
- Use `header_only: true` for metadata checks when bins are unnecessary.
- Keep policy overrides close to the callsite when behavior is operation-specific.