CDC Sink: Configuration Reference (Client API)

• This article documents the Client API configuration classes used to define a CDC Sink task in code.
  Pass a CdcSinkConfiguration to AddCdcSinkOperation (create) or UpdateCdcSinkOperation (update).

• In this article:

  • CdcSinkConfiguration
  • CdcSinkPostgresSettings
  • CdcSinkTableConfig
  • CdcSinkEmbeddedTableConfig
  • CdcSinkLinkedTableConfig
  • CdcColumnMapping
  • CdcColumnType
  • CdcSinkOnDeleteConfig
  • CdcSinkRelationType

CdcSinkConfiguration

The top-level configuration object for a CDC Sink task.

Property	Type	Required	Description
Name	string	✓	Unique task name
ConnectionStringName	string	✓	Name of the SQL connection string (uses the existing SqlConnectionString type - the same as SQL ETL). The connection string's FactoryName determines the source database engine.
Tables	List<CdcSinkTableConfig>	✓	Root table configurations (at least one required)
Postgres	CdcSinkPostgresSettings		PostgreSQL-specific settings (slot and publication names)
SkipInitialLoad	bool		When true, skip the initial full-table scan and start streaming CDC changes immediately. Only applies on first startup - has no effect once the initial load has completed. Default: false
Disabled	bool		Create the task paused (without deleting it). Default: false
MentorNode	string		Preferred cluster node for execution
PinToMentorNode	bool		Pin the task to the mentor node. Default: false
TaskId	long		Server-assigned task ID. To update a task, pass the existing task ID to UpdateCdcSinkOperation(taskId, configuration); do not use this property as the update selector.

Supported FactoryName values (set on the connection string):

FactoryName	Database Engine
Npgsql	PostgreSQL
Microsoft.Data.SqlClient	SQL Server
MySql.Data.MySqlClient or MySqlConnector.MySqlConnectorFactory	MySQL / MariaDB

CdcSinkPostgresSettings

PostgreSQL-specific settings. Assigned to CdcSinkConfiguration.Postgres.
Leave null for non-PostgreSQL connections.

Property	Type	Description
SlotName	string	Name of the PostgreSQL logical replication slot. If omitted on creation, auto-generated as rvn_cdc_s_{taskId}. Immutable once set. Max 63 characters, alphanumeric and underscores only.
PublicationName	string	Name of the PostgreSQL publication. If omitted on creation, auto-generated as rvn_cdc_p_{taskId} (note the _p_ prefix vs. the slot's _s_). Same immutability rules as SlotName.

Setting these explicitly is useful when a DBA pre-creates the slot and publication with human-readable names,
when migrating from a previous task and reusing an existing slot, or when running multiple environments with predictable names.

CdcSinkTableConfig

Configures a root table - one SQL table mapped to one RavenDB collection.

Property	Type	Required	Description
CollectionName	string	✓	RavenDB collection name (e.g., "Orders")
SourceTableName	string	✓	SQL table name (e.g., "orders")
SourceTableSchema	string		SQL schema name. Default is provider-specific: PostgreSQL "public", SQL Server "dbo", MySQL/MariaDB the database name from the connection string.
PrimaryKeyColumns	List<string>	✓	SQL columns used for document ID generation
Columns	List<CdcColumnMapping>	✓	Column mappings - each entry defines a SQL column, its document property name, and how to store it
Patch	string		JavaScript patch for INSERT and UPDATE
OnDelete	CdcSinkOnDeleteConfig		Delete behavior. Default: delete document
EmbeddedTables	List<CdcSinkEmbeddedTableConfig>		Nested table configurations
LinkedTables	List<CdcSinkLinkedTableConfig>		Foreign key reference configurations
Disabled	bool		Skip this table. Default: false

CdcSinkEmbeddedTableConfig

Configures a table whose rows are embedded as nested objects within a parent document.

Property	Type	Required	Description
SourceTableName	string	✓	SQL table name
SourceTableSchema	string		SQL schema name (provider-specific default)
PropertyName	string	✓	Property name in the parent document (e.g., "Lines")
Type	CdcSinkRelationType	✓	Array, Map, or Value
JoinColumns	List<string>	✓	FK columns referencing parent's PrimaryKeyColumns
PrimaryKeyColumns	List<string>	✓	PK columns for matching items on UPDATE/DELETE
Columns	List<CdcColumnMapping>	✓	Column mappings
Patch	string		JavaScript patch on parent document for INSERT/UPDATE
OnDelete	CdcSinkOnDeleteConfig		Delete behavior for embedded items
CaseSensitiveKeys	bool		Case-sensitive PK matching. Default: false
EmbeddedTables	List<CdcSinkEmbeddedTableConfig>		Nested embedded tables
LinkedTables	List<CdcSinkLinkedTableConfig>		Linked tables within embedded items

CdcSinkLinkedTableConfig

Configures a foreign key reference that becomes a document ID in the parent document.

Property	Type	Required	Description
SourceTableName	string	✓	SQL table name of the referenced table
SourceTableSchema	string		SQL schema name (provider-specific default)
PropertyName	string	✓	Property name in the parent document (e.g., "Customer")
LinkedCollectionName	string	✓	Target RavenDB collection for ID generation (e.g., "Customers")
JoinColumns	List<string>	✓	FK columns used to build the referenced document ID

CdcColumnMapping

A single column mapping entry within a Columns list.

Property	Type	Required	Description
Column	string	✓	SQL column name (case-insensitive)
Name	string	✓	Document property name (or attachment name when Type = Attachment)
Type	CdcColumnType		How to store the value. Default: Default

CdcColumnType

Controls how a SQL column value is stored in RavenDB.

Value	Behavior
Default	Standard type conversion: int→long, numeric/decimal→decimal, real→float, double precision→double, date→DateOnly, timestamp→DateTime, uuid→string, varchar/text→string. SQL arrays→JSON arrays. JSON/JSONB stored as plain string.
Json	Parses the string value as a native JSON value (object, array, string, number, boolean, etc.) in the document. Use for PostgreSQL json/jsonb or SQL Server nvarchar(max) with JSON content.
Attachment	Stores the raw column value as a RavenDB attachment. byte[]→binary (application/octet-stream), string→UTF-8 text (text/plain; charset=utf-8), float[]/double[]→raw binary vector data (application/octet-stream), not JSON arrays. The Name field becomes the attachment name.

CdcSinkOnDeleteConfig

Controls how DELETE events are handled for a table or embedded table.

Property	Type	Default	Description
Patch	string	null	JavaScript patch that runs when a DELETE event arrives
IgnoreDeletes	bool	false	When true, CDC Sink skips the automatic document delete or embedded-item removal. If Patch is set, the patch still runs.

Available patch variables for OnDelete:

• this - the document (root or parent for embedded)
• $row - all SQL columns from the DELETE event
• $old - the previous stored document or embedded item before the DELETE event

Behavior matrix:

IgnoreDeletes	Patch	Result
false	null	Normal delete (default)
false	set	Patch runs, then delete proceeds
true	null	DELETE discarded silently
true	set	Patch runs, delete skipped

CdcSinkRelationType

Specifies the structure of embedded data in the document.

Value	Description
Array	One-to-many: stored as a JSON array. Items matched by PK for UPDATE/DELETE
Map	One-to-many: stored as a JSON object keyed by PK value(s)
Value	Many-to-one: stored as a single embedded object