# Aerospike Store Settings

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

Aerospike is a high-performance NoSQL database used as a backend for Teranode's UTXO store. These settings control Aerospike connection, policies, and performance tuning.

**Related Topic**: [UTXO Store](https://bsvblockchain.com/docs/nodes/teranode/topics/stores/utxo/)

Aerospike is a high-performance NoSQL database used as a backend for Teranode's UTXO store. These settings control Aerospike connection, policies, and performance tuning.

## Configuration Settings

### Connection Settings

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| Host | string | "localhost" | aerospike_host | **CRITICAL** - Aerospike server hostname or IP |
| Port | int | 3000 | aerospike_port | Aerospike server port |

### Policy Settings

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| BatchPolicyURL | *url.URL | "defaultBatchPolicy" | aerospike_batchPolicy | **CRITICAL** - Batch operation policy URL |
| ReadPolicyURL | *url.URL | "defaultReadPolicy" | aerospike_readPolicy | **CRITICAL** - Read operation policy URL |
| WritePolicyURL | *url.URL | "defaultWritePolicy" | aerospike_writePolicy | **CRITICAL** - Write operation policy URL |
| QueryPolicyURL | *url.URL | "defaultQueryPolicy" | aerospike_queryPolicy | **CRITICAL** - Query operation policy URL |
| UseDefaultBasePolicies | bool | false | aerospike_useDefaultBasePolicies | Skips parsing the policy URLs; do not use (see Policy Configuration Behavior) |
| UseDefaultPolicies | bool | false | aerospike_useDefaultPolicies | Use Aerospike default policies |

### Performance and Debugging

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| WarmUp | bool | true | aerospike_warmUp | **CRITICAL** - Enable connection pool warm-up |
| StoreBatcherDuration | time.Duration | 0 (unset) | aerospike_storeBatcherDuration | DEPRECATED: overrides `utxostore_storeBatcherDurationMillis` when set |
| StatsRefreshDuration | time.Duration | 5s | aerospike_statsRefresh | Statistics refresh interval |
| EnableClientMetrics | bool | true | aerospike_enable_client_metrics | Gate the `client.Stats()` polling goroutine |
| Debug | bool | false | aerospike_debug | Enable Aerospike debug logging |

## Configuration Dependencies

### Policy URL Format

Policy URLs follow the `aerospike:///` scheme with query parameters:

```text
aerospike:///?MaxRetries=5&SleepBetweenRetries=500ms&TotalTimeout=1s&SocketTimeout=1s
```

**Supported Policy Parameters:**

`getAerospikeClient` (`util/aerospike.go`) reads only these query keys. It ignores any other key in the URL. A key that is not set keeps the Aerospike client default.

| Parameter | Type | Read | Write | Batch | Query | Description |
|-----------|------|------|-------|-------|-------|-------------|
| MaxRetries | int | yes | yes | yes | yes | Maximum retry attempts |
| TotalTimeout | duration | yes | yes | yes | yes | Total operation timeout |
| SocketTimeout | duration | yes | yes | yes | yes | Socket-level timeout |
| SleepBetweenRetries | duration | yes | yes | yes | yes | Delay between retry attempts |
| SleepMultiplier | float | yes | yes | yes | yes | Backoff multiplier for retries |
| ExitFastOnExhaustedConnectionPool | bool | yes | yes | no | no | Fail at once when the connection pool is exhausted |
| AllowInlineSSD | bool | no | no | yes | no | Process batch keys inline on SSD namespaces |
| ConcurrentNodes | int | no | no | yes | no | Number of nodes the batch is sent to at the same time; 0 sends to all |

The read mode and the commit level are not configurable:

- Reads use the client default read mode: `ReadModeAP=ONE` for an available-mode namespace, and `ReadModeSC=SESSION` for a strong-consistency namespace.
- Writes made with the write and batch write policies use `CommitLevel=COMMIT_ALL`. A write is acknowledged only when the master and every reachable replica hold it. The exception is the pruner's own record removals, which use `COMMIT_MASTER` while `pruner_relaxRemovalCommitLevel` is true (the default).

For the consistency mode of the UTXO namespace, see [UTXO Store](https://bsvblockchain.com/docs/nodes/teranode/topics/stores/utxo/#consistency-mode).

### Policy Types

**Batch Policy** (for bulk operations):

- `settings.conf`: 5m total, 60s socket
- Used for batch read and write operations
- `ConcurrentNodes` controls how many nodes the batch is sent to at the same time

**Read Policy** (for single record reads):

- `settings.conf`: 1s total, 1s socket
- Used for UTXO lookups

**Write Policy** (for single record writes):

- `settings.conf`: 1s total, 1s socket
- Used for unspend, the creation lock record, record deletes and the conflict write-ahead log
- UTXO creation does not use it: creation is batched and uses the Batch Policy

**Query Policy** (for query operations):

- Timeout and retry configuration for query operations

### Policy Configuration Behavior

- When `UseDefaultPolicies = true`:

    - The read, write, batch and query policies use the Aerospike client defaults
    - The policy URLs are ignored

- When `UseDefaultPolicies = false` (recommended):

    - The policy URLs are parsed and applied
    - Allows fine-tuned timeout and retry behavior

- When `UseDefaultBasePolicies = true`:

    - The policy URLs, and the connection settings in the Aerospike store URL, are not parsed
    - The connection settings use the Aerospike client defaults
    - Unless `UseDefaultPolicies` is also true, the read, write, batch and query policies are built from values that were never set: every operation runs with `TotalTimeout=0` (no timeout), `SocketTimeout=0` and `MaxRetries=0`. Do not use it; use `UseDefaultPolicies` instead.

### Connection Pool Warm-Up

- When `WarmUp = true`:

    - Pre-establishes connections to Aerospike cluster
    - Reduces initial request latency
    - Recommended for production deployments

- When `WarmUp = false`:

    - Connections established on-demand
    - May experience higher latency on first requests

### Batcher Configuration

- The store (Create) batcher timeout is `utxostore_storeBatcherDurationMillis`, the same key family as the get, spend and locked batchers:

    - Lower values (1-10ms): Lower latency, more frequent writes
    - Higher values (50-100ms): Better batching, higher throughput
    - Trade-off between latency and throughput

- `aerospike_storeBatcherDuration` is deprecated. When set it still overrides `utxostore_storeBatcherDurationMillis` and logs a warning at startup.

- Works in conjunction with UTXO store batcher settings

## UTXO Store Integration

When using Aerospike as the UTXO store backend, set the store URL:

```text
utxostore = aerospike://${aerospike_host}:${aerospike_port}/namespace?set=utxo&param=value
```

**UTXO Store URL Parameters:**

| Parameter                   | Type   | Default | Description                          |
|-----------------------------|--------|---------|--------------------------------------|
| set                         | string | "utxo"  | Aerospike set name                   |
| WarmUp                      | int    | 0       | Warm-up connection count             |
| ConnectionQueueSize         | int    | 128     | Connection queue size                |
| LimitConnectionsToQueueSize | bool   | false   | Limit connections to queue size      |
| MinConnectionsPerNode       | int    | 0       | Minimum connections per node         |
| externalStore               | string | ""      | External transaction cache store URL |

## Validation Rules

| Setting              | Validation                                 | Impact                        | When Checked                |
|----------------------|--------------------------------------------|-------------------------------|-----------------------------|
| Host                 | Must be valid hostname/IP                  | Connection failure if invalid | During store initialization |
| Port                 | Must be valid port number (1-65535)        | Connection failure if invalid | During store initialization |
| BatchPolicyURL       | Must be valid URL with aerospike:// scheme | Policy parsing failure        | During policy configuration |
| ReadPolicyURL        | Must be valid URL with aerospike:// scheme | Policy parsing failure        | During policy configuration |
| WritePolicyURL       | Must be valid URL with aerospike:// scheme | Policy parsing failure        | During policy configuration |
| QueryPolicyURL       | Must be valid URL with aerospike:// scheme | Policy parsing failure        | During policy configuration |
| StatsRefreshDuration | Must be positive duration                  | Statistics update frequency   | During store initialization |

## Configuration Examples

### Basic Configuration

```text
aerospike_host = localhost
aerospike_port = 3000
aerospike_useDefaultPolicies = false
aerospike_warmUp = true
```

### Production Configuration with Custom Policies

```text
aerospike_host = aerospike-cluster.example.com
aerospike_port = 3000
aerospike_debug = false
aerospike_warmUp = true
aerospike_useDefaultPolicies = false
aerospike_batchPolicy = aerospike:///?MaxRetries=5&SleepBetweenRetries=500ms&TotalTimeout=64s&SocketTimeout=10s&ConcurrentNodes=4
aerospike_readPolicy = aerospike:///?MaxRetries=3&SleepBetweenRetries=250ms&TotalTimeout=2s&SocketTimeout=1s
aerospike_writePolicy = aerospike:///?MaxRetries=3&SleepBetweenRetries=250ms&TotalTimeout=2s&SocketTimeout=1s
aerospike_statsRefresh = 5s
```

### High-Performance Configuration

```text
aerospike_warmUp = true
utxostore_storeBatcherDurationMillis = 5
aerospike_batchPolicy = aerospike:///?MaxRetries=5&TotalTimeout=30s&SocketTimeout=5s&ConcurrentNodes=8
aerospike_statsRefresh = 10s
```

### Development/Debug Configuration

```text
aerospike_host = localhost
aerospike_port = 3000
aerospike_debug = true
aerospike_useDefaultPolicies = true
aerospike_warmUp = false
```

### Multi-Node Cluster Configuration

```text
# Node-specific hosts using settings context
aerospike_host.docker.teranode1 = aerospike-1
aerospike_host.docker.teranode2 = aerospike-2
aerospike_host.docker.teranode3 = aerospike-3

aerospike_port.docker.teranode1 = 3100
aerospike_port.docker.teranode2 = 3200
aerospike_port.docker.teranode3 = 3300
```

### Complete UTXO Store with Aerospike

```text
utxostore = aerospike://${aerospike_host}:${aerospike_port}/utxo-store?set=utxo&WarmUp=32&ConnectionQueueSize=128&MinConnectionsPerNode=8&externalStore=file://${DATADIR}/${clientName}/external

aerospike_host = aerospike-cluster
aerospike_port = 3000
aerospike_warmUp = true
aerospike_useDefaultPolicies = false
aerospike_batchPolicy = aerospike:///?MaxRetries=5&TotalTimeout=64s&SocketTimeout=10s
aerospike_readPolicy = aerospike:///?MaxRetries=3&TotalTimeout=1s&SocketTimeout=1s
aerospike_writePolicy = aerospike:///?MaxRetries=3&TotalTimeout=1s&SocketTimeout=1s
aerospike_queryPolicy = aerospike:///?MaxRetries=3&TotalTimeout=2s&SocketTimeout=1s
```

## Performance Tuning Guidelines

### Latency-Optimized Configuration

- Lower `utxostore_storeBatcherDurationMillis` (5-10)
- Lower policy timeouts (1-2s total)
- Higher `MinConnectionsPerNode` (8-16)
- Enable `WarmUp`

### Throughput-Optimized Configuration

- Higher `utxostore_storeBatcherDurationMillis` (50-100)
- Higher policy timeouts (5-10s total)
- Higher `ConnectionQueueSize` (512-1024)
- Higher `ConcurrentNodes` in batch policy (8-16)

### Memory-Constrained Configuration

- Lower `ConnectionQueueSize` (64-128)
- Lower `MinConnectionsPerNode` (2-4)
- Higher `utxostore_storeBatcherDurationMillis` (reduce write frequency)
- Lower `ConcurrentNodes` (1-2)

## Monitoring and Debugging

- Set `Debug = true` for detailed Aerospike client logging
- Monitor `StatsRefreshDuration` for performance statistics updates
- Set `EnableClientMetrics = false` to stop the `client.Stats()` polling loop
  entirely on deployments that do not consume those cluster-stats metrics. This
  gates only that goroutine — the client's own per-result-code and latency
  histograms are not collected either way, because `client.EnableMetrics` stays
  disabled pending [#1001](https://github.com/bsv-blockchain/teranode/issues/1001),
  so the flag cannot be used to relieve that contention
- Check Aerospike server logs for connection and operation errors
- Use Aerospike Management Console (AMC) for cluster monitoring

## Related Documentation

- [UTXO Store](https://bsvblockchain.com/docs/nodes/teranode/topics/stores/utxo/)
- [UTXO Store Settings](https://bsvblockchain.com/docs/nodes/teranode/references/settings/stores/utxo-settings/)