BSV blockchainBSV blockchain

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

SettingTypeDefaultEnvironment VariableUsage
Hoststring“localhost”aerospike_hostCRITICAL - Aerospike server hostname or IP
Portint3000aerospike_portAerospike server port

Policy Settings

SettingTypeDefaultEnvironment VariableUsage
BatchPolicyURL*url.URL“defaultBatchPolicy”aerospike_batchPolicyCRITICAL - Batch operation policy URL
ReadPolicyURL*url.URL“defaultReadPolicy”aerospike_readPolicyCRITICAL - Read operation policy URL
WritePolicyURL*url.URL“defaultWritePolicy”aerospike_writePolicyCRITICAL - Write operation policy URL
QueryPolicyURL*url.URL“defaultQueryPolicy”aerospike_queryPolicyCRITICAL - Query operation policy URL
UseDefaultBasePoliciesboolfalseaerospike_useDefaultBasePoliciesSkips parsing the policy URLs; do not use (see Policy Configuration Behavior)
UseDefaultPoliciesboolfalseaerospike_useDefaultPoliciesUse Aerospike default policies

Performance and Debugging

SettingTypeDefaultEnvironment VariableUsage
WarmUpbooltrueaerospike_warmUpCRITICAL - Enable connection pool warm-up
StoreBatcherDurationtime.Duration0 (unset)aerospike_storeBatcherDurationDEPRECATED: overrides utxostore_storeBatcherDurationMillis when set
StatsRefreshDurationtime.Duration5saerospike_statsRefreshStatistics refresh interval
EnableClientMetricsbooltrueaerospike_enable_client_metricsGate the client.Stats() polling goroutine
Debugboolfalseaerospike_debugEnable 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=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.

ParameterTypeReadWriteBatchQueryDescription
MaxRetriesintyesyesyesyesMaximum retry attempts
TotalTimeoutdurationyesyesyesyesTotal operation timeout
SocketTimeoutdurationyesyesyesyesSocket-level timeout
SleepBetweenRetriesdurationyesyesyesyesDelay between retry attempts
SleepMultiplierfloatyesyesyesyesBackoff multiplier for retries
ExitFastOnExhaustedConnectionPoolboolyesyesnonoFail at once when the connection pool is exhausted
AllowInlineSSDboolnonoyesnoProcess batch keys inline on SSD namespaces
ConcurrentNodesintnonoyesnoNumber 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.

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:

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

UTXO Store URL Parameters:

ParameterTypeDefaultDescription
setstring“utxo”Aerospike set name
WarmUpint0Warm-up connection count
ConnectionQueueSizeint128Connection queue size
LimitConnectionsToQueueSizeboolfalseLimit connections to queue size
MinConnectionsPerNodeint0Minimum connections per node
externalStorestring""External transaction cache store URL

Validation Rules

SettingValidationImpactWhen Checked
HostMust be valid hostname/IPConnection failure if invalidDuring store initialization
PortMust be valid port number (1-65535)Connection failure if invalidDuring store initialization
BatchPolicyURLMust be valid URL with aerospike:// schemePolicy parsing failureDuring policy configuration
ReadPolicyURLMust be valid URL with aerospike:// schemePolicy parsing failureDuring policy configuration
WritePolicyURLMust be valid URL with aerospike:// schemePolicy parsing failureDuring policy configuration
QueryPolicyURLMust be valid URL with aerospike:// schemePolicy parsing failureDuring policy configuration
StatsRefreshDurationMust be positive durationStatistics update frequencyDuring store initialization

Configuration Examples

Basic Configuration

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

Production 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 = 5s

High-Performance Configuration

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

Development/Debug Configuration

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

Multi-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 = 3300

Complete 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=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, 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