cdc
CDC is Turso's change data capture system that records INSERT, UPDATE, and DELETE operations at the bytecode translation layer. Changes are written to a dedicated CDC table and consumed by the sync engine to replicate local modifications remotely. The system supports two schema versions and operates per-connection via PRAGMA configuration.
CDC tracks database INSERT, UPDATE, and DELETE changes by writing records to a dedicated table, operating at the bytecode generation layer.
AI-generated summary based on this skill's SKILL.md
Install
tursodatabase/turso/cdc · repository language: Rust
git clone https://github.com/tursodatabase/turso
cp -r turso/.claude/skills/cdc ~/.claude/skills/cdcFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What is change data capture and how does CDC table tracking work for INSERT UPDATE DELETE?
CDC (change data capture) is Turso's system that records INSERT, UPDATE, and DELETE operations at the bytecode translation layer. When enabled, cdc writes all row modifications to a dedicated CDC table. The sync engine consumes these records to replicate local changes remotely. Each change includes a transaction ID for grouping related operations and before/after image data for understanding what changed.
How do I enable change data capture on a database connection?
To enable CDC on a database connection, use PRAGMA cdc = true. This activates CDC mode for that connection and begins writing change records to the turso_cdc table. The cdc system operates per-connection, so you must enable it on each connection where you want to capture modifications. Once enabled, all INSERT, UPDATE, and DELETE operations are automatically tracked.
How does the sync engine integrate with CDC to replicate changes?
CDC integrates with Turso's sync engine by providing a stream of change records that the sync engine consumes to replicate local modifications remotely. When you enable CDC on a connection, the system emits CDC instructions at the bytecode level. The sync engine reads these records from the CDC table and uses the transaction ID grouping and before/after images to reconstruct and replay changes on remote replicas.
How do I decode and interpret CDC binary record format?
CDC records contain before/after image binary data that encodes row state changes. The cdc table structure includes change_id, change_time, and change_type fields alongside the binary representations. To interpret these records, you decode the before and after images to understand what values changed. The record format preserves the full row state before and after each modification, allowing you to reconstruct the exact transaction.
What should I know about CDC version detection and backward compatibility?
CDC supports two schema versions (v1 and v2) and includes version detection to maintain backward compatibility. When debugging CDC, check the schema version of your turso_cdc table to ensure compatibility with your sync engine. The cdc system handles version detection automatically, but older v1 tables may require migration or compatibility checks if you're upgrading to v2 features.
How does CDC handle DDL schema changes and transaction grouping?
CDC tracks database row modifications through transaction ID grouping, which associates related changes within a single transaction. While CDC primarily captures DML operations (INSERT, UPDATE, DELETE), the system uses transaction IDs to group these changes together. The cdc autocommit and commit records mark transaction boundaries, allowing the sync engine to replay changes in the correct order and maintain consistency across replicas.
SKILL.md
rendered from the published skill — quoted content, verbatim
CDC (Change Data Capture) - Internal Feature Map
Overview
CDC tracks INSERT/UPDATE/DELETE changes on database tables by writing change records into a
dedicated CDC table (turso_cdc by default). It is per-connection, enabled via PRAGMA, and
operates at the bytecode generation (translate) layer. The sync engine consumes CDC records
to push local changes to the remote.
Architecture Diagram
``` User SQL (INSERT/UPDATE/DELETE/DDL) | v ┌─────────────────────────────────────────────────┐ │ Translate layer (core/translate/) │ │ ┌───────────────────────────────────────────┐ │ │ │ prepare_cdc_if_necessary() │ │ │ │ - checks CaptureDataChangesInfo │ │ │ │ - opens CDC table cursor (OpenWrite) │ │ │ │ - skips if target == CDC table itself │ │ │ └───────────────────────────────────────────┘ │ │ ┌───────────────────────────────────────────┐ │ │ │ emit_cdc_insns() │ │ │ │ - writes (change_id, change_time, │ │ │ │
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
.claude/skills/cdc/SKILL.md