Aerospike Store Settings
Related Topic: UTXO Store
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:
aerospike:///?MaxRetries=5&SleepBetweenRetries=500ms&TotalTimeout=1s&SocketTimeout=1sSupported 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=ONEfor an available-mode namespace, andReadModeSC=SESSIONfor 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 useCOMMIT_MASTERwhilepruner_relaxRemovalCommitLevelis true (the default).
For the consistency mode of the UTXO namespace, see UTXO Store.
Policy Types
Batch Policy (for bulk operations):
settings.conf: 5m total, 60s socket- Used for batch read and write operations
ConcurrentNodescontrols 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
UseDefaultPoliciesis also true, the read, write, batch and query policies are built from values that were never set: every operation runs withTotalTimeout=0(no timeout),SocketTimeout=0andMaxRetries=0. Do not use it; useUseDefaultPoliciesinstead.
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_storeBatcherDurationis deprecated. When set it still overridesutxostore_storeBatcherDurationMillisand 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:
utxostore = aerospike://${aerospike_host}:${aerospike_port}/namespace?set=utxo¶m=valueUTXO 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
aerospike_host = localhost
aerospike_port = 3000
aerospike_useDefaultPolicies = false
aerospike_warmUp = trueProduction Configuration with Custom Policies
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 = 5sHigh-Performance Configuration
aerospike_warmUp = true
utxostore_storeBatcherDurationMillis = 5
aerospike_batchPolicy = aerospike:///?MaxRetries=5&TotalTimeout=30s&SocketTimeout=5s&ConcurrentNodes=8
aerospike_statsRefresh = 10sDevelopment/Debug Configuration
aerospike_host = localhost
aerospike_port = 3000
aerospike_debug = true
aerospike_useDefaultPolicies = true
aerospike_warmUp = falseMulti-Node Cluster Configuration
# 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 = 3300Complete UTXO Store with Aerospike
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=1sPerformance 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
ConcurrentNodesin 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 = truefor detailed Aerospike client logging - Monitor
StatsRefreshDurationfor performance statistics updates - Set
EnableClientMetrics = falseto stop theclient.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, becauseclient.EnableMetricsstays disabled pending #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