Worum es geht
SQLite kennt standardmäßig den Rollback-Journal-Modus. Dabei sperrt ein Schreibvorgang die gesamte Datenbank, bis die Transaktion abgeschlossen ist. In einer Pipeline mit mehreren Prozessen, die zeitgleich lesen und schreiben wollen, führt das regelmäßig zu database is locked-Fehlern.
Der WAL-Modus ändert das Prinzip: Änderungen landen zunächst in einer separaten Write-Ahead-Log-Datei (Endung -wal). Leser greifen weiterhin auf den letzten konsistenten Stand zu, während ein Schreiber parallel in die WAL-Datei schreibt. Erst ein Checkpoint überträgt die Einträge aus der WAL-Datei in die eigentliche Datenbankdatei.
Für eine Pipeline aus Collector, SQLite, Klassifikation und Benachrichtigung bedeutet das: Der Collector kann neue Einträge schreiben, während die Klassifikation parallel liest, ohne dass einer der beiden Prozesse blockiert wird. Das reduziert Lock-Konflikte deutlich, eliminiert sie aber nicht vollständig.
Anforderungen
Bevor du den WAL-Modus aktivierst, solltest du drei Punkte klären. Erstens: Liegt die Datenbankdatei auf einem lokalen Dateisystem, das Locking korrekt unterstützt? Netzwerkfreigaben wie NFS oder SMB gelten als ungeeignet, weil WAL auf Memory-Mapped-Dateizugriffe und zuverlässiges fcntl-Locking angewiesen ist.
Zweitens: Wie viele Prozesse schreiben gleichzeitig? WAL erlaubt genau einen Schreiber zur selben Zeit, zusätzliche Schreibversuche warten oder scheitern je nach Timeout. Bei einer Pipeline mit Collector, Klassifikation und Benachrichtigung als getrennten Prozessen kollidieren Schreibzugriffe weiterhin, nur seltener als ohne WAL.
Drittens: Wer übernimmt das Checkpointing? SQLite checkpointet automatisch, sobald die WAL-Datei eine bestimmte Größe überschreitet (standardmäßig etwa 1000 Seiten). In einer Pipeline mit dauerhaft offenen Lesern kann dieser automatische Checkpoint ausbleiben, was die WAL-Datei unkontrolliert wachsen lässt.
Möglichkeiten im Vergleich
Für den Umgang mit WAL im Dauerbetrieb gibt es grundsätzlich drei Strategien, die sich kombinieren lassen.
Die erste Strategie ist der passive Checkpoint, den SQLite automatisch auslöst. Er ist unauffällig, kann aber von aktiven Lesetransaktionen verzögert werden. Für eine Pipeline, die stündlich klassifiziert und benachrichtigt, reicht das in vielen Fällen aus, solange keine Dauerverbindung offen bleibt.
Die zweite Strategie ist der manuelle Checkpoint per PRAGMA wal_checkpoint. Du rufst ihn gezielt nach einem Schreibzyklus auf, etwa am Ende eines Collector-Laufs. Das gibt dir Kontrolle über den Zeitpunkt, erfordert aber zusätzlichen Code und Monitoring der WAL-Dateigröße.
Die dritte Strategie ist der geplante Checkpoint über einen separaten Wartungs-Job, der unabhängig vom Heartbeat läuft. Das entkoppelt die Wartung von der eigentlichen Pipeline-Logik, bedeutet aber einen weiteren Prozess, der überwacht werden muss. Für kleine Setups mit einem täglichen Heartbeat über cron oder systemd-Timer lässt sich der Checkpoint einfach in diesen Lauf integrieren, ohne einen eigenen Job zu benötigen.
Umsetzung
Der WAL-Modus lässt sich pro Datenbankverbindung mit einem einzigen PRAGMA-Befehl aktivieren. Die Einstellung wird dauerhaft in der Datenbankdatei gespeichert, muss also nicht bei jeder Verbindung neu gesetzt werden. Trotzdem ist es sinnvoll, sie explizit zu setzen, damit das Verhalten unabhängig von Vorzuständen nachvollziehbar bleibt.
import logging
import sqlite3
from pathlib import Path
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("watch_pipeline.db")
DB_PATH = Path("watch_pipeline.sqlite3")
def get_connection(db_path: Path) -> sqlite3.Connection:
"""Öffnet eine SQLite-Verbindung im WAL-Modus mit sinnvollen Defaults."""
conn = sqlite3.connect(db_path, timeout=10.0)
conn.execute("PRAGMA journal_mode=WAL;")
conn.execute("PRAGMA synchronous=NORMAL;")
conn.execute("PRAGMA busy_timeout=5000;")
return conn
def write_entry(conn: sqlite3.Connection, title: str, source: str) -> None:
"""Schreibt einen neuen Feed-Eintrag in die Tabelle entries."""
with conn:
conn.execute(
"INSERT INTO entries (title, source, status) "
"VALUES (?, ?, 'new');",
(title, source),
)
def run_checkpoint(conn: sqlite3.Connection) -> None:
"""Führt einen manuellen WAL-Checkpoint aus und loggt das Ergebnis."""
cursor = conn.execute("PRAGMA wal_checkpoint(TRUNCATE);")
busy, log_pages, checkpointed = cursor.fetchone()
if busy:
logger.warning(
"Checkpoint blockiert: %s Seiten im Log, %s übertragen",
log_pages,
checkpointed,
)
else:
logger.info("Checkpoint erfolgreich, Log auf 0 Seiten reduziert")
def main() -> None:
conn = None
try:
conn = get_connection(DB_PATH)
conn.execute(
"CREATE TABLE IF NOT EXISTS entries ("
"id INTEGER PRIMARY KEY, "
"title TEXT NOT NULL, "
"source TEXT NOT NULL, "
"status TEXT NOT NULL"
");"
)
write_entry(conn, "Beispiel-Eintrag", "feed-beispiel")
run_checkpoint(conn)
except sqlite3.OperationalError as exc:
logger.error("Datenbankfehler: %s", exc)
finally:
if conn is not None:
conn.close()
if __name__ == "__main__":
main()
Der Parameter TRUNCATE beim Checkpoint sorgt dafür, dass die WAL-Datei nach erfolgreichem Übertragen auf Länge null zurückgesetzt wird. Das hält den Speicherbedarf konstant. Alternativ steht PASSIVE, FULL oder RESTART zur Verfügung, je nachdem wie aggressiv du vorgehen willst.
synchronous=NORMAL ist im WAL-Modus ein gängiger Kompromiss zwischen Datensicherheit und Geschwindigkeit. Bei einem Systemabsturz können die letzten Commits verloren gehen, die Datenbankdatei selbst bleibt aber konsistent. Für eine Watch-Pipeline, die ohnehin aus wiederholbaren Quellen wie Feeds speist, ist dieser Trade-off meist vertretbar.
Den Checkpoint-Aufruf kannst du direkt in den täglichen Heartbeat-Job integrieren, der ohnehin per cron oder systemd-Timer läuft. Das spart einen zusätzlichen Prozess und stellt sicher, dass die WAL-Datei regelmäßig zurückgesetzt wird, auch wenn der automatische Checkpoint durch offene Leser verzögert wurde.
Typische Fallstricke
Der häufigste Fehler ist eine offene Verbindung, die über den gesamten Lauf der Klassifikationsstufe bestehen bleibt, ohne dass eine Transaktion jemals explizit beendet wird. Solange eine Lesetransaktion aktiv ist, kann SQLite den Checkpoint nicht vollständig durchführen, die WAL-Datei wächst weiter.
Ein zweiter Fallstrick betrifft die Dateiverwaltung. Der WAL-Modus erzeugt neben der Hauptdatei zusätzlich eine -wal- und eine -shm-Datei. Wer die Datenbankdatei per Skript kopiert oder sichert, ohne diese beiden Begleitdateien zu berücksichtigen, erhält ein inkonsistentes Backup. Ein konsistentes Backup erreichst du entweder über die SQLite-eigene Backup-API oder über einen vorherigen vollständigen Checkpoint.
Ein dritter Punkt ist der busy_timeout. Ohne diese Einstellung schlägt ein Schreibzugriff sofort fehl, wenn ein anderer Prozess gerade schreibt. Gerade bei mehreren unabhängigen Prozessen in der Pipeline, Collector, Klassifikation und Benachrichtigung, führt das ohne Timeout zu sporadischen, schwer reproduzierbaren Fehlern.
Schließlich unterschätzen viele die Auswirkung von synchronous=FULL in Kombination mit WAL. Diese Einstellung erzwingt bei jedem Checkpoint einen zusätzlichen fsync-Aufruf, was auf langsamen Datenträgern zu messbaren Verzögerungen führt. Für die meisten Watch-Pipelines reicht NORMAL aus.
Wann sich das lohnt (und wann nicht)
Der WAL-Modus lohnt sich, sobald mehr als ein Prozess gleichzeitig auf die Datenbank zugreift, etwa wenn Collector und Klassifikation getrennt laufen. Die Reduktion von Lock-Konflikten ist in diesem Szenario spürbar und mit wenig Konfigurationsaufwand verbunden.
Er lohnt sich weniger, wenn die gesamte Pipeline ohnehin als ein einziger sequenzieller Prozess läuft, der Schritt für Schritt Collector, Klassifikation und Benachrichtigung abarbeitet. In diesem Fall gibt es keine echte Parallelität, die vom WAL-Modus profitieren würde, und der Standardmodus bleibt einfacher zu verwalten.
Verzichten solltest du auf WAL, wenn die Datenbankdatei auf einem Netzwerklaufwerk liegt oder wenn das Backup-Verfahren die zusätzlichen Begleitdateien nicht berücksichtigen kann. In diesen Fällen überwiegt das Risiko inkonsistenter Zustände den Vorteil der besseren Parallelität.