CedroDB CLI: una orden y su evento en una transacción

El problema: dos escrituras relacionadas

Una orden confirmada y el evento que anuncia su confirmación deben persistir juntos. Guardarlos por separado permite que una operación falle después de guardar la otra.

Recorrido de arquitectura

CLI CedroDB → validación Python → transacción del motor Rust → colecciones orders y outbox en el mismo log.

El comando batch aplica las dos escrituras como un lote atómico. La colección outbox conserva el trabajo pendiente. Un consumidor separado puede leerlo y entregar el evento; este ejemplo no implementa ese consumidor.

Ejecutar el ejemplo

Instala cedrodb==0.8.0 con pip y ejecuta este archivo con Python 3.9 o superior. Utiliza un directorio temporal y no modifica tus bases existentes.

import json
import subprocess
import sys
from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as directory:
    database = str(Path(directory) / "orders")

    def cli(*arguments, payload=None):
        command = [sys.executable, "-m", "cedrodb", *arguments,
                   "--db", database, "--json"]
        if payload is not None:
            command.append("--stdin")
        result = subprocess.run(command, input=json.dumps(payload) if payload is not None else None,
                                text=True, capture_output=True, check=True)
        return json.loads(result.stdout)

    cli("init")
    cli("batch", payload=[
        {"kind": "put", "collection": "orders", "key": "order-001",
         "value": {"status": "confirmed"}},
        {"kind": "put", "collection": "outbox", "key": "order-001",
         "value": {"event": "order.confirmed", "delivered": False}},
    ])
    assert cli("get", "orders", "order-001")["value"]["status"] == "confirmed"
    assert cli("get", "outbox", "order-001")["found"] is True
    assert cli("verify")["records"] == 2
    print("OK: order and outbox persisted atomically")

Qué comprueba

Las aserciones leen la orden y su evento y verifican los dos registros del log. El resultado esperado es OK: order and outbox persisted atomically.

Límites que debes diseñar

La transacción local no hace atómica una llamada a un servicio externo. Para producción, define reintentos, claves de idempotencia, deduplicación y cuándo marcar el evento como entregado. Una prueba de éxito tampoco sustituye las pruebas de recuperación ante fallos.