aerospike-development
Guides Aerospike application development with official clients for Java/Go/Python/C#/Node.js/Rust including data modeling collection types expression APIs indexes and batch or scan workflows. Use when users build or review client code or tune data access against a model that already exists. For greenfield model design from requirements, or a schema redesign, use aerospike-data-modeling instead. Redirect cluster deployment sizing XDR and backup questions to Aerospike Operations documentation. Core database only; not Aerospike Graph.
aerospike · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add aerospike/agent-skills --skill aerospike-development技能说明
name: aerospike-development description: >- Guides Aerospike application development with official clients for Java/Go/Python/C#/Node.js/Rust including data modeling collection types expression APIs indexes and batch or scan workflows. Use when users build or review client code or tune data access against a model that already exists. For greenfield model design from requirements, or a schema redesign, use aerospike-data-modeling instead. Redirect cluster deployment sizing XDR and backup questions to Aerospike Operations documentation. Core database only; not Aerospike Graph. license: Apache-2.0 metadata: last_verified: "2026-04-21" server_versions: "7.0+"
Aerospike: application development
Role
Act as a solutions-architect–level assistant: help developers build performant, scalable, resilient apps with official Aerospike client libraries. Be pragmatic; prioritize throughput, low latency, and correct client usage.
When to use
- Data modeling, denormalization, and access-pattern design.
- Client API usage: CDTs, Document API, filter/operation expressions, secondary indexes, generations, batch/scan/query.
- Client-side performance: policies, pooling, compute-to-data patterns.
- Code review or debugging of Aerospike client code.
Scope
| In scope | Out of scope |
|---|---|
| Data modeling; client APIs; CDTs; Document API; expressions; secondary indexes; optimistic concurrency; batch/scan/query; client tuning | Cluster deployment; node config; hardware sizing; network topology; XDR setup; backup/restore; general administration |
If the user asks an operational question (for example adding nodes or choosing replication factor), decline that depth and point them to Aerospike Operations documentation (see reference.md).
Design-time vs implementation-time. The data modeling covered here is implementation-time: working effectively against a model that already exists — choosing CDT operations, shaping access paths, sizing records, avoiding hot keys. If no schema exists yet and the task is deriving one from requirements, or redesigning an existing model, that is design-time work: use the aerospike-data-modeling skill, which produces a schema guide and schema summary before any code is written.
Mental model for developers
- Key-value first: Primary-key get/put/delete is the fastest path; design for it.
- Schemaless bins, typed values: Bins need no fixed schema; stored values are typed.
- No server-side joins: Denormalize or embed; use lists/maps (CDTs) where appropriate; see model-bin-cdt-multiple-records.md for when to use flat bins, nested CDTs, or more than one record per entity.
- Namespace and set boundaries sit with retention, isolation, and configuration choices; see model-namespace-set-boundaries.md. Index design follows from enumerating read/write paths first; see query-sindex-by-access-path.md.
- Compute to data: Prefer filter expressions and CDT/record operations on the server over shipping large payloads to the client; for choosing operate vs batch vs expressions, see model-client-api-choice.md.
Client best practices (enforce in generated or reviewed code)
- Singleton client: One
AerospikeClient(or language equivalent) per process; it is thread-safe and holds pools and cluster state. Creating a client per request is a common cause of port exhaustion and latency spikes. - Pool and warmup: Size
maxConnsPerNode(or equivalent) appropriately; use connection warmup on startup when available. - Reuse policies: Do not allocate new read/write policies on every call—set defaults on the client or reuse policy instances.
- Replace when replacing: If overwriting a whole record, use replace existence semantics where the API allows it so the server avoids unnecessary read-before-write work.
- Typed values: Prefer explicit bin/value constructors over generic boxing when the API offers them.
- Logging: Encourage enabling client logging so cluster tend/thread issues surface early.
- Direct node access: The client must reach every node (not only seeds); there is no proxy in the data path. If advertised IPs are wrong for the app network, use server access / alternate-access addresses and the client policy for alternate services (see client-direct-node-access.md).
Common pitfalls
| Pitfall | Better direction |
|---|---|
| Load balancer or proxy only to seeds; app cannot reach all node addresses | Clients need direct TCP to every node; use access-address / alternate-access-address (and client useServicesAlternate when needed)—not a proxy in the data path; see client-direct-node-access.md |
| RDBMS-style joins in app code | Denormalize; use CDTs; see model-access-paths-denormalization.md |
| Unbounded list/map growth | Respect max record size; cap or trim; use bounded CDT ops; see cdt-bounded-collections.md |
| Read-modify-write races | Generation checks or server-side operations/expressions; see policy-generation-cas.md, expr-compute-to-data.md |
| Error 22 / “Operation not allowed at this time” on TTL writes | Often nsup-period 0 (NSUP off) while the client sends a positive TTL; enable NSUP or avoid positive TTLs; see single-ttl-nsup-default-ttl.md |
| Shortening TTL on updates | Avoid reducing void-time casually; can contribute to record resurrection after cold restart; see [si |