Store (Clave-Valor)

Wippy proporciona almacenes clave-valor con TTL respaldados por memoria, SQL, Raft o un CRDT.

Esta página es una referencia de configuración de entradas. Los fences YAML son fragmentos para una lista de entradas existente, y el fence SQL es la preparación del esquema que debe ejecutarse antes de que se inicie una entrada store.sql.

Tipos de Entrada

Tipo Descripción
store.memory Almacén en memoria con limpieza automática
store.sql Almacén respaldado por SQL con persistencia
store.kv.raft KV replicado en cluster, fuertemente consistente, sobre el Raft compartido
store.kv.crdt KV replicado en cluster, eventualmente consistente, sobre gossip (CRDT)

Almacén en Memoria

- name: sessions
  kind: store.memory
  max_size: 10000
  cleanup_interval: "5m"
  lifecycle:
    auto_start: true
Campo Tipo Por Defecto Descripción
max_size int 10000 Número máximo de entradas; 0 se sustituye por el valor predeterminado (10000)
cleanup_interval duration 5m Intervalo de limpieza de entradas expiradas

Cuando se alcanza max_size, se rechazan nuevas entradas. Los datos se pierden al reiniciar.

Almacén SQL

- name: cache
  kind: store.sql
  database: app:postgres
  table_name: kv_store
  cleanup_interval: "10m"
  lifecycle:
    auto_start: true
Campo Tipo Por Defecto Descripción
database referencia requerido Referencia de entrada de base de datos
table_name string requerido Nombre de tabla para almacenamiento
id_column_name string key Columna para claves
payload_column_name string value Columna para valores
expire_column_name string expires_at Columna para expiración
cleanup_interval duration 0 Intervalo de limpieza de entradas expiradas

Los nombres de columna se validan contra inyección SQL. El siguiente requisito previo es DDL de PostgreSQL; use los tipos binario/blob y timestamp equivalentes para MySQL o SQLite:

CREATE TABLE kv_store (
    key VARCHAR(255) PRIMARY KEY,
    value BYTEA NOT NULL,
    expires_at TIMESTAMPTZ NULL
);

CREATE INDEX idx_expires_at ON kv_store(expires_at) WHERE expires_at IS NOT NULL;

Almacenes KV de cluster :id=cluster-kv-stores

store.kv.raft y store.kv.crdt replican datos clave-valor entre los nodos del cluster. Ambos requieren que el clustering esté habilitado y reutilizan la misma API Lua del módulo Store. Cada entrada es una vista con namespace sobre un único motor a nivel de nodo; namespace aísla las claves de esta entrada y debe coincidir con ^[a-z][a-z0-9._-]*$ (no puede comenzar con _).

Raft (consistencia fuerte)

- name: deployments
  kind: store.kv.raft
  namespace: deploy
Campo Tipo Requerido Descripción
namespace string Sí Namespace de claves en el motor compartido

Las escrituras se proponen a través del Raft compartido (los seguidores las reenvían al líder); las lecturas son linealizables. Se soportan escrituras condicionales (put con only_if_absent/if_version). El estado de Raft es duradero en disco por defecto bajo cluster.raft.data_dir (por defecto ~/.wippy/store); consulte Configuración.

CRDT (consistencia eventual)

- name: sessions
  kind: store.kv.crdt
  namespace: sess
  durable: false
Campo Tipo Requerido Por Defecto Descripción
namespace string Sí - Namespace de claves
durable bool No false Persiste snapshots en disco para que el namespace sobreviva a un reinicio completo del cluster

Las escrituras mutan el estado local y se diseminan por gossip; las escrituras concurrentes en conflicto convergen mediante last-writer-wins. Las lecturas son locales. No se soportan escrituras condicionales. Con durable: false el almacén está en memoria y se reconstruye desde los peers; con durable: true toma snapshots en <data_dir>/_sys/kvcrdt.

data_dir es a nivel de nodo (cluster.raft.data_dir), no por entrada. El estado de Raft compartido y los snapshots durables de CRDT residen bajo <data_dir>/_sys/.

Comportamiento TTL

Los cuatro tipos de almacén aceptan valores de tiempo de vida, pero la visibilidad de la expiración varía según el backend.

  • store.memory trata una clave expirada como ausente al leerla y elimina las entradas expiradas según su cleanup_interval, que de forma predeterminada es 5m. Un valor cero configurado se sustituye por ese valor predeterminado.
  • store.sql filtra las filas expiradas al leer y las elimina según cleanup_interval; su valor predeterminado 0 deshabilita la limpieza en segundo plano sin volver legibles las filas expiradas.
  • store.kv.raft adjunta las claves con expiración a leases gestionadas por el líder. El barrido de leases, aproximadamente cada segundo, propone la eliminación a través de Raft, por lo que una clave puede seguir siendo legible hasta que se aplica por consenso esa eliminación.
  • store.kv.crdt también elimina las claves expiradas durante su barrido de leases, aproximadamente cada segundo, y luego propaga el tombstone resultante por gossip. El plazo del lease es local al nodo que aceptó la escritura; si ese origen falla antes de la expiración, otro nodo no reproduce de forma independiente el plazo y la clave puede permanecer hasta que un estado posterior o una limpieza administrativa la eliminen.

API Lua

Consulte el módulo Store para las operaciones get, set, has y delete, además de put, entry, list e info para acceso versionado y condicional.

Ver También