storage_rocksdb

RocksDB Storage – Layout & Betrieb

Stand: 22. Dezember 2025
Version: v1.3.0
Kategorie: 💾 Storage

---

📑 Inhaltsverzeichnis

• Schlüsselräume & Präfixe
• WAL & Snapshots
• Compaction

---

Dieser Leitfaden beschreibt das physische Storage-Verhalten der ThemisDB-Engine auf Basis von RocksDB: Schlüsselpräfixe, WAL, Snapshots und Compaction.

Schlüsselräume & Präfixe

Themis nutzt ein Präfix-Schema zur logischen Trennung von Datenbereichen:

• Entities (Primärdaten): entity:<table>:<pk> → Blob (BaseEntity-Serialisierung)
• Secondary Index: idx:<table>:<column>:<value>:<pk>
• Range Index: ridx:<table>:<column>:<value>:<pk>
• Sparse/TTL/Fulltext: sidx:/ttlidx:/ftidx: entsprechend der Funktion
• Graph Adjazenz: graph:out:<from_pk>:<edge_id> → <to_pk>, graph:in:<to_pk>:<edge_id> → <from_pk>
• Vector Index (Metadaten/Mapping): vector:<table>:<pk> → Vektorinfo (Embedding out-of-store in Index-Struktur)
• Changefeed (Audit): changefeed:<sequence> → Event JSON
• Time-Series (TSStore): ts:<metric>:<timestamp>:<tags> → Wert(e)

Siehe auch: docs/indexes.md, docs/temporal_time_range_queries.md, docs/change_data_capture.md, docs/time_series.md.

Column Families (CF)

• Standardbetrieb: Default Column Family (CF)
• Optional (für große Workloads): Trennung in CFs (z. B. cf_entities, cf_indexes, cf_graph, cf_changefeed, cf_ts) kann LSM-Compactions separieren.
• Hinweis: Aktuell verwendet Themis standardmäßig die Default CF; CF-Trennung ist als Betriebsoptimierung möglich und sollte konsistent in Engine-Config & Backups berücksichtigt werden.

Write-Ahead Log (WAL)

• WAL stellt Durability sicher und dient für Recovery nach Abstürzen.
• Empfohlen:
  • wal_bytes_per_sync und bytes_per_sync passend zur Hardware
  • max_total_wal_size dimensionieren (Spitzen abfangen, aber Platte nicht vollschreiben)
  • Sync-Strategie nach Latenzanforderungen (disableWAL=false, fsync je nach Durability-Ziel)

Snapshots & MVCC

• Snapshots fixieren ein Sichtfenster für Reads (Snapshot-Isolation)
• Transaktionen verwenden Snapshots, um Repeatable Reads zu ermöglichen
• Long-running Snapshots erhöhen Read Amplification: Überwachung und Begrenzung empfehlenswert

Compaction & Performance

• Trennung heißer/cold Daten (optional via CF) kann Write Amplification reduzieren
• Kompressions-Strategie (z. B. LZ4 für L0/L1, ZSTD für tiefere Ebenen) je nach Profil
• Bloom Filter für Punktabfragen (Secondary Index) aktivieren
• Prefix-Extractor gemäß Key-Schema (z. B. bis zum :value:-Teil bei idx:) beschleunigt Prefix-Scans

Backups & Restore

• RocksDB Backups (SST + MANIFEST + OPTIONS + ggf. WAL) regelmäßig erstellen
• Konsistenz über alle CFs sicherstellen (falls eingesetzt)
• Vor Restore: Version/Options-Kompatibilität prüfen

Monitoring

• Wichtige Kennzahlen: L0 File Count, Compaction Pending, Stall Time, WAL Größe, Read-/Write-Amp
• Prometheus-Export aus Themis (/metrics) ergänzen um Storage-Kennzahlen (Roadmap)

Troubleshooting (Kurz)

• Hohe Latenzen bei Scans: Prefix-Extractor/Bloom prüfen; CF-Trennung für Indizes erwägen
• Speicherverbrauch stark: Kompression/Block-Cache-Tuning; Retention (Changefeed/TS) aktivieren
• Lange Snapshots: Transaktionslaufzeiten begrenzen; cleanupOldTransactions nutzen

Weiterlesen:

• docs/mvcc_design.md
• docs/transactions.md
• RocksDB Tuning Guides (Block Cache, MemTables, Compaction)