Persistent shape catalog + lazy restart recovery

Aperta
  • Qualcosa non va?
#8 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
postgres, rust
Ambito
api, backend, databases, distributed-systems

Direzione di ricerca

Inizia tracciando l’entry point /v1/shape, lo stream durevole __meta/shapes e il percorso di avvio del tailer per tabella; confronta la gestione dei backfill incompleti con shape_status.ex:54-81. Mappa come si integrano il caricamento del catalogo, il recupero lazy al primo accesso, gli ID privi di collisioni e la GC degli orfani. Il lavoro è completato quando il recupero dopo un riavvio è lazy e condiviso per tabella, i backfill incompleti vengono scartati, gli ID rimangono univoci e gli shape stream non referenziati vengono ripuliti.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Foundation for restart-safety (closes the root cause behind #3 and #4) and prerequisite for HTTP caching and retention work.

Scope (aligned in discussion):

  • Catalog: persist {shapeId, table, canonical predicate, columns, kind, backfill-complete, tailer offset, last_read}. Proposed store: a __meta/shapes durable stream — keeps the engine node-stateless (all durable state = PG slot + DS log); boot folds the catalog stream only. last_read flushed periodically/batched, never per-read.
  • Lazy recovery — boot must be O(catalog), not O(shapes × stream folds). With thousands of shapes, per-shape DS reads at boot are too slow. Boot does: load catalog index → register predicates into the shared routers (cheap, in-memory) → resume per-table tailers from the min persisted offset per table (one shared replay per table catches every shape up — no per-shape work). Expensive per-shape state is rebuilt on first touch: /v1/shape key sets by folding the shape stream on first unknown-handle request (no more restart 409 stampede), gates only if a backfill was incomplete.
  • Incomplete backfills are discarded at boot (catalog row + stream removed), same policy as upstream (shape_status.ex:54-81).
  • Collision-free shape ids across restarts (persist the counter or random ids) — fixes #3.
  • Orphan GC: background sweep of DS shape/* streams not present in the catalog.

Interactions: table-stream trimming (future) must never trim below the min persisted tailer offset; dormant-shape reactivation (retention issue, TBD) reuses the same lazy catch-up path.

🤖 Generated with Claude Code

Lingua principale
Rust
Stelle
32
Fork
7
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di electric-sql/electric-circuits

Tutte le issue di electric-sql/electric-circuits

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.