x/data Primer
x/data Primer
Section titled “x/data Primer”Experimental — API compatibility is not frozen. Evaluate before adopting in production. Check Release Posture for current maturity status.
Open this page after x/* Family when the change is about high-level data topology that should not live in the stable store layer: read-write splitting orchestration, sharding and routing topology, durable KV engines beyond store/kv, or idempotency providers beyond store/idempotency.
x/data is the canonical entrypoint for topology-heavy data capabilities. Its subordinate package — x/data/cache (distributed cache with consistent hashing, replication, failover, and Redis adapter) — is reached through x/data first, not opened directly.
Stability note
Section titled “Stability note”x/data is experimental at the family level. Two subordinate packages carry a narrower beta-surface promise as of v1.1.0 — their exported APIs were unchanged across v1.0.0 → v1.1.0 with owner sign-off on record:
| Subpackage | Tier | What it means |
|---|---|---|
file | beta surface | API unchanged across two consecutive releases; adopt behind an app-local adapter |
idempotency | beta surface | API unchanged across two consecutive releases; adopt behind an app-local adapter |
cache, kvengine, migrate, pgx, rw, sharding, sqlx | experimental | May change without a deprecation period |
Check Release Posture before relying on any x/data subpackage in a stable production path.
Start here when
Section titled “Start here when”- you are implementing read-write splitting with primary/replica routing (
rw/) - you are adding sharding or data routing topology logic (
sharding/) - you are building a durable KV engine implementation beyond the stable
store/kvprimitive (kvengine/) - you are implementing an idempotency provider with durable storage beyond
store/idempotency(idempotency/) - you are adding tenant-aware topology adapters that scope data access by tenant
- you need distributed or Redis-backed cache topology — confirm placement here before opening
x/data/cache
Do not start here when
Section titled “Do not start here when”- the change is about stable persistence primitives — that belongs in
store(cache, db, file, kv, idempotency interfaces) - the work is business repository logic such as domain-specific query builders or data mappers — keep that in application code
- the change is about HTTP transport for file operations — that belongs in
x/fileapi - the work is a simple in-process cache — prefer
cache.MemoryCachefromstore/cachedirectly
First files to read in the current repository
Section titled “First files to read in the current repository”x/data/module.yamlx/data/rw/(read-write splitting)x/data/sharding/(routing topology)x/data/kvengine/(durable KV)x/data/idempotency/(idempotency providers)x/data/cache/(if distributed or Redis cache topology is involved)
Concrete ownership examples
Section titled “Concrete ownership examples”Keep it in x/data when the work is about | Move out when the work becomes |
|---|---|
rw: primary/replica selection, read preference routing, failover coordination | stable store/db interface definitions |
sharding: shard key resolution, ring topology, shard-aware query routing | business-specific partition strategies baked into domain queries |
kvengine: durable KV implementations with WAL, compaction, or tiered storage | stable store/kv interface — that is a kernel contract |
idempotency: durable idempotency providers with TTL and storage backends | stable store/idempotency interface or business deduplication logic |
distributed or Redis cache topology → reach through x/data/cache | making x/data/cache a competing family entrypoint for new data work |
Why this primer exists
Section titled “Why this primer exists”The stable store layer defines interfaces and simple primitives. Topology-heavy behaviors — sharding, read-write splitting, failover — belong here because they introduce complexity and optionality that the stable layer must not absorb. x/data/cache is a subordinate: starting directly there for new distributed cache work bypasses the family placement check that prevents boundary drift.