Change Data Capture

Streamen Sie zeilenbezogene Änderungen aus einer Datenbank. Eine CDC-Quelle erfasst Inserts, Updates und Deletes, übergibt jedem Abonnenten optional zuerst einen konsistenten Snapshot der vorhandenen Zeilen und liefert alles als treiberneutrale Änderungsereignisse. Quellen sind über ihre Entry-ID adressierbar und werden aus Lua über das cdc-Modul konsumiert.

Entry-Typen

Beide Kinds stellen dieselbe Lua-API, denselben Quellinformations-Datensatz und dieselbe Form von Änderungsereignissen bereit. Was sich unterscheidet, ist die Menge der Garantien, veröffentlicht pro Quelle als Capabilities.

Postgres-Konfiguration

- name: pg_cdc
  kind: db.cdc.postgres
  host: ${env:DB_HOST}
  port: 5432
  database: app
  username: ${env:DB_USER}
  password: ${env:app.secrets:db_password}
  slot_name: wippy_slot
  publication: wippy_pub
  tables:
    - public.users
    - public.orders
  snapshot: true
  streaming: true
  standby_interval: "10s"
  status_interval: "10s"
  lifecycle:
    auto_start: true

Eine Null in einem beliebigen max_*-Feld wählt den Standardwert; der Decoder ist nie unbegrenzt. Negative Werte werden abgelehnt.

Zugangsdaten lösen ${env:NAME}-Platzhalter beim Dekodieren über die Environment-Registry auf.

SQLite-Konfiguration

Eine SQLite-Quelle öffnet keine eigene Datenbank. Sie leiht sich eine vorhandene db.sql.sqlite-Ressource und abonniert deren Beobachter für committete Mutationen, erfasst also genau die Schreibvorgänge, die über diese Wippy-SQL-Ressource erfolgen — Schreibvorgänge eines anderen Prozesses, einer anderen Verbindung oder eines externen Werkzeugs werden nicht beobachtet.

- name: cdcdb
  kind: db.sql.sqlite
  file: /var/data/app.db
  lifecycle:
    auto_start: true

- name: changes
  kind: db.cdc.sqlite
  db_resource: app:cdcdb
  tables:
    - users
    - orders
  snapshot: true
  status_interval: "30s"
  lifecycle:
    auto_start: true

Die Quelle deklariert die SQL-Ressource als Lebenszyklus-Anforderung, sodass der Supervisor die Datenbank zuerst startet und die Quelle neu startet, wenn die Datenbankgeneration ersetzt wird.

Abonnementgrenzen

Jede Quelle lässt eine begrenzte Anzahl von Abonnenten zu und reserviert deren Worst-Case-Rückstand im Voraus. Ein Snapshot-Slot bleibt reserviert, bis der snapshot-fähige Stream geschlossen wird.

subscriptions:
  max_subscriptions: 1024
  max_snapshot_subscriptions: 4
  max_bytes: 268435456

Null wählt den Standardwert; negative Werte werden abgelehnt. Das Ausschöpfen einer Grenze lässt das Abonnement mit einem wiederholbaren errors.UNAVAILABLE scheitern.

Funktionsweise

1. Eine Postgres-Quelle verbindet sich als Replikationsbenutzer und erstellt (oder setzt fort) den in slot_name benannten Slot. Eine SQLite-Quelle leiht sich ihre db_resource und abonniert deren Beobachter für committete Mutationen.
2. Zeilenänderungen werden in treiberneutrale Änderungsereignisse mit op gleich insert, update, delete oder truncate dekodiert.
3. Ein Abonnent, dessen Stream snapshot aktiviert hat — über das Feld snapshot des Eintrags oder über opts.snapshot am Stream — erhält zuerst die vorhandenen Zeilen als Ereignisse mit op = "snapshot" und setzt dann ohne Lücke zwischen beiden mit Live-Änderungen fort.
4. Eine Postgres-Quelle bestätigt regelmäßig die LSN, damit der Server WAL-Segmente freigeben kann (standby_interval).
5. Die Quelle registriert sich unter ihrer Entry-ID; Lua-Code abonniert mit cdc.stream.

Capabilities

Jede Quelle veröffentlicht, was sie garantiert, sodass Konsumenten über Capabilities verzweigen statt über den Entry-Typ.

Capability-Flags beschreiben den Fortschritt der Quelle, nicht dauerhafte Zustellung: Kein Treiber spielt Ereignisse für einen einzelnen Abonnenten erneut ab, der zurückgefallen ist oder die Verbindung verloren hat.

Quellinformationen

Jede Quelle wird durch einen Info-Datensatz beschrieben, den cdc.source und cdc.list_sources zurückgeben.

admission zählt Reservierungen, nicht die Warteschlangenfüllung: active ist die Anzahl zugelassener Abonnements, snapshots die snapshot-fähige Teilmenge, reserved_bytes das reservierte Rückstandsbudget und rejected die kumulierte Anzahl der von den Grenzwerten abgelehnten Abonnements.

Berechtigungen

CDC-Autorität ist von Datenbankzugriff getrennt: Eine Quelle kann jede erfasste Zeile offenlegen, einschließlich der Abbilder vor der Änderung. Stream-Filter schränken nur die Zustellung ein; sie gewähren nie Zugriff auf eine Quelle.

- name: cdc_reader
  kind: security.policy
  policy:
    effect: allow
    actions: [cdc.source, cdc.subscribe]
    resources: [app:changes]

Siehe auch

• CDC-Modul - Lua-Streaming-API
• Datenbank - SQL-Datenbankdienste
• Environment - Zugangsdaten über ${env:NAME} auflösen
• Sicherheit - Richtlinien und Aktionen