rivven_cdc/lib.rs
1//! # rivven-cdc - Change Data Capture for Rivven
2//!
3//! Production-grade CDC support for PostgreSQL, MySQL, MariaDB, and SQL Server.
4//!
5//! ## Features
6//!
7//! - `postgres` - PostgreSQL logical replication via pgoutput
8//! - `mysql` - MySQL binlog replication
9//! - `mariadb` - MariaDB binlog replication (enables `mysql`)
10//! - `sqlserver` - SQL Server CDC via poll-based CDC tables
11//! - `full` - All CDC sources
12//!
13//! ## Architecture
14//!
15//! ```text
16//! ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
17//! │PostgreSQL │ │ MySQL │ │ MariaDB │ │SQL Server │
18//! │ WAL │ │ Binlog │ │ Binlog │ │CDC Tables │
19//! └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
20//! │ │ │ │
21//! ▼ ▼ ▼ ▼
22//! ┌──────────────────────────────────────────────────────────┐
23//! │ CdcSource Trait │
24//! └──────────────────────────────────────────────────────────┘
25//! │ │ │ │
26//! ▼ ▼ ▼ ▼
27//! ┌──────────────────────────────────────────────────────────┐
28//! │ CdcEvent │
29//! │ { op: Insert/Update/Delete, before, after, ... } │
30//! └──────────────────────────────────────────────────────────┘
31//! ```
32//!
33//! ## Quick Start
34//!
35//! ```rust,no_run
36//! # #[cfg(feature = "postgres")]
37//! # async fn example() -> anyhow::Result<()> {
38//! use rivven_cdc::postgres::{PostgresCdc, PostgresCdcConfig};
39//! use rivven_cdc::CdcSource;
40//!
41//! let config = PostgresCdcConfig::builder()
42//! .connection_string("postgres://user:pass@localhost/mydb")
43//! .slot_name("rivven_slot")
44//! .publication_name("rivven_pub")
45//! .build()?;
46//!
47//! let mut cdc = PostgresCdc::new(config);
48//! cdc.start().await?;
49//! # Ok(())
50//! # }
51//! ```
52//!
53//! ## Public API Organization
54//!
55//! This crate exposes types in three tiers:
56//!
57//! ### Tier 1: Core Types (crate root)
58//! Essential types for basic CDC operations - `CdcEvent`, `CdcOp`, `CdcSource`.
59//!
60//! ### Tier 2: Feature Types (crate root)
61//! Optional features for production use - SMT transforms, deduplication, encryption.
62//!
63//! ### Tier 3: Advanced Types (`common` module)
64//! Internal/advanced types for custom implementations - accessed via `common::*`.
65
66// Common module - always available (contains advanced/internal types)
67pub mod common;
68
69// =============================================================================
70// TIER 1: Core CDC Types - Essential for basic operations
71// =============================================================================
72
73pub use common::{
74 // Error handling
75 CdcError,
76 // Core event and operation types
77 CdcEvent,
78 // Filtering
79 CdcFilter,
80 CdcFilterConfig,
81 CdcOp,
82 CdcSource,
83 ErrorCategory,
84 Result,
85 TableColumnConfig,
86};
87
88// =============================================================================
89// TIER 2: Production Features - Optional but commonly used
90// =============================================================================
91
92// SMT (Single Message Transforms)
93pub use common::{
94 Cast, CastType, ComputeField, ContentRouter, ExtractNewRecordState, Filter, FilterCondition,
95 Flatten, HeaderSource, HeaderToValue, InsertField, MaskField, NullCondition, RegexRouter,
96 ReplaceField, SetNull, Smt, SmtChain, TimestampConverter, TimestampFormat, TimezoneConverter,
97 Unwrap, ValueToKey,
98};
99
100#[cfg(feature = "cloud-storage")]
101pub use common::ExternalizeBlob;
102
103// Deduplication
104pub use common::{Deduplicator, DeduplicatorConfig, KeyStrategy};
105
106// Schema Change Detection
107pub use common::{ColumnDefinition, SchemaChangeConfig, SchemaChangeEmitter, SchemaChangeEvent};
108
109// Transaction Topic
110pub use common::{TransactionEvent, TransactionTopicConfig, TransactionTopicEmitter};
111
112// Tombstone Emission
113pub use common::{TombstoneConfig, TombstoneEmitter};
114
115// Signal Processing
116pub use common::{Signal, SignalProcessor, SignalResult};
117
118// Field-Level Encryption
119pub use common::{EncryptionConfig, FieldEncryptor, MemoryKeyProvider};
120
121// =============================================================================
122// TIER 3: Advanced Types - Available via `common::` module
123// =============================================================================
124// The following are NOT re-exported at crate root but accessible via `common::`:
125//
126// Resilience (rivven-connect has its own implementations):
127// - common::CircuitBreaker, CircuitState
128// - common::RateLimiter
129// - common::ExponentialBackoff
130// - common::RetryConfig, RetryConfigBuilder
131// - common::GuardrailsConfig, GuardrailsConfigBuilder
132//
133// Routing (for custom event routing):
134// - common::EventRouter, RouteRule, RouteCondition, RouteDecision
135//
136// Snapshot (for custom snapshot implementations):
137// - common::SnapshotCoordinator, SnapshotConfig, SnapshotMode
138// - common::SnapshotProgress, SnapshotState, ProgressStore
139//
140// Validation (for custom validators):
141// - common::Validator
142//
143// Constants (for protocol-level customization):
144// - common::CONNECTION_TIMEOUT_SECS
145// - common::IO_TIMEOUT_SECS
146// - common::MAX_MESSAGE_SIZE
147
148// PostgreSQL CDC - feature-gated
149#[cfg(feature = "postgres")]
150pub mod postgres;
151
152// MySQL/MariaDB CDC - feature-gated
153#[cfg(feature = "mysql")]
154pub mod mysql;
155
156// SQL Server CDC - feature-gated
157#[cfg(feature = "sqlserver")]
158pub mod sqlserver;