SQL Sink
The SQL sink connector writes records from KurrentDB to SQL databases by executing configurable SQL statements. Map event types to SQL statement templates to control how the connector persists each record.
Supported databases
Section titled “Supported databases”- Microsoft SQL Server
- PostgreSQL
Prerequisites
Section titled “Prerequisites”Before using the SQL sink connector, ensure you have:
- A data protection token configured in your KurrentDB instance (required to encrypt sensitive fields like passwords)
- A supported SQL database instance (SQL Server or PostgreSQL)
- Appropriate database credentials and network access
Quickstart
Section titled “Quickstart”SQL Server
Section titled “SQL Server”Create the SQL Server sink with client.Connectors. Replace example-sql with your own
connector id:
Dictionary<string, string> settings = new() { ["instanceTypeName"] = "sql-sink", ["type"] = "SqlServer", ["connectionString"] = "Server=127.0.0.1,1433;Database=master;User Id=sa;Password=YourPassword123;TrustServerCertificate=True", ["subscription:filter:scope"] = "stream", ["subscription:filter:filterType"] = "streamId", ["subscription:filter:expression"] = "vehicles", ["reducer:mappings"] = "<base64-encoded-mappings-json>"};
await client.Connectors.Create("example-sql", settings);await client.Connectors.Start("example-sql");PostgreSQL
Section titled “PostgreSQL”Dictionary<string, string> settings = new() { ["instanceTypeName"] = "sql-sink", ["type"] = "PostgreSql", ["connectionString"] = "Host=127.0.0.1;Port=54322;Database=postgres;Username=postgres;Password=postgres", ["subscription:filter:scope"] = "stream", ["subscription:filter:filterType"] = "streamId", ["subscription:filter:expression"] = "vehicles", ["reducer:mappings"] = "<base64-encoded-mappings-json>"};
await client.Connectors.Create("example-sql", settings);await client.Connectors.Start("example-sql");Settings
Section titled “Settings”Adjust these settings to control how the SQL sink connector behaves and how it interacts with KurrentDB.
The SQL sink connector can be configured with the following options:
Core options
Section titled “Core options”| Name | Details |
|---|---|
type |
Type: Enum Description: Type of SQL database to connect to. Accepted Values: SqlServer, PostgreSqlDefault: SqlServer |
connectionString |
required Description: Connection string to the SQL database. Authentication options override credentials in the connection string. |
reducer:mappings |
Description: Base64-encoded JSON object mapping schema names to SQL statement templates and parameter extractors. |
Authentication
Section titled “Authentication”Username/password
Section titled “Username/password”| Name | Details |
|---|---|
authentication:username |
Description: Username for database authentication. |
authentication:password |
Description: Password for database authentication. |
These settings overwrite any username/password specified in the connection string.
Client certificate (PostgreSQL)
Section titled “Client certificate (PostgreSQL)”| Name | Details |
|---|---|
authentication:clientCertificate |
Description: Base64 encoded client certificate for mutual TLS. |
authentication:certificatePassword |
Description: Password for the client certificate. |
Resilience
Section titled “Resilience”| Name | Details |
|---|---|
resilience:enabled |
Type: boolean Description: Enables resilience features for database operations. Default: true |
resilience:commandTimeout |
Type: int Description: Command timeout in seconds. Default: 30 |
resilience:connectionTimeout |
Type: int Description: Connection timeout in seconds for establishing the initial database connection. Default: 15 |
resilience:minPoolSize |
Type: int Description: Minimum number of connections in the pool. Default: 0 |
resilience:maxPoolSize |
Type: int Description: Maximum number of connections in the pool. Default: 100 |
resilience:connectionLifetime |
Type: int Description: Maximum lifetime of a connection in seconds. When a connection is returned to the pool, it is destroyed if its lifetime exceeds this value. Default: 0 (no limit) |
resilience:firstDelayBound:upperLimitMs |
Type: double Description: Upper time limit in milliseconds for the first backoff delay bound. Default: 60000 (1 minute) |
resilience:firstDelayBound:delayMs |
Type: double Description: Delay in milliseconds for the first backoff bound. Default: 5000 (5 seconds) |
resilience:secondDelayBound:upperLimitMs |
Type: double Description: Upper time limit in milliseconds for the second backoff delay bound. Default: 3600000 (1 hour) |
resilience:secondDelayBound:delayMs |
Type: double Description: Delay in milliseconds for the second backoff bound. Default: 600000 (10 minutes) |
resilience:thirdDelayBound:upperLimitMs |
Type: double Description: Upper time limit in milliseconds for the third backoff delay bound. -1 means unlimited.Default: -1 |
resilience:thirdDelayBound:delayMs |
Type: double Description: Delay in milliseconds for the third backoff bound. Default: 3600000 (1 hour) |
The settings commandTimeout, connectionTimeout, minPoolSize, maxPoolSize, and connectionLifetime override any corresponding values specified in the connection string.
Specifying SQL statements
Section titled “Specifying SQL statements”Define SQL statement templates with parameter placeholders, prefixed with @. Pair each template with a JavaScript extractor function that pulls values from the record.
Example configuration:
{ "VehicleRegistered": { "Statement": "INSERT INTO vehicle_registrations (id, vin) VALUES (@id, @vin)", "Extractor": "(record) => ({ id: record.value.registrationId, vin: record.value.vin })" }, "VehicleTransferred": { "Statement": "UPDATE vehicle_registrations SET owner_name = @newOwnerName WHERE vin = @vin", "Extractor": "(record) => ({ vin: record.value.vin, newOwnerName: record.value.newOwnerName })" }}The configuration is passed as a base64-encoded JSON string using the reducer:mappings option.
Helper functions
Section titled “Helper functions”Use helper functions to type values correctly for your database columns:
| Function | Use For | Example |
|---|---|---|
Guid(string) |
UUID/UNIQUEIDENTIFIER columns |
Guid(record.value.id) |
DateTime(string) |
TIMESTAMP/DATETIME columns |
DateTime(record.value.createdAt) |
TimeSpan(string) |
TIME/INTERVAL columns |
TimeSpan(record.value.duration) |
Example:
{ "OrderPlaced": { "Statement": "INSERT INTO orders (id, placed_at, customer_name) VALUES (@id, @placedAt, @customerName)", "Extractor": "(record) => ({ id: Guid(record.value.orderId), placedAt: DateTime(record.value.timestamp), customerName: record.value.customer.name })" }}Examples
Section titled “Examples”Inserting into PostgreSQL
Section titled “Inserting into PostgreSQL”This example uses the SQL sink connector to insert vehicle registration records into a local PostgreSQL instance on Supabase.
What you need for this example
Section titled “What you need for this example”- Supabase CLI installed and running locally
Step 1: Get the database connection string
Section titled “Step 1: Get the database connection string”Run the following command to get your local Supabase connection details:
supabase statusExpected output:
Database URL: postgresql://postgres:postgres@127.0.0.1:54322/postgresStudio URL: http://127.0.0.1:54323...Note down the Studio URL because you’ll need it to verify the data insertion in step 6.
Step 2: Format the connection string
Section titled “Step 2: Format the connection string”The SQL connector requires the connection string in ADO.NET format:
Host=<host>;Port=<port>;Database=<database>;Username=<username>;Password=<password>Example using the output above:
Host=127.0.0.1;Port=54322;Database=postgres;Username=postgres;Password=postgresStep 3: Create the database table
Section titled “Step 3: Create the database table”- Open the Supabase Studio at
http://127.0.0.1:54323 - Navigate to the SQL Editor
- Execute the following SQL:
CREATE TABLE vehicle_registrations ( id UUID PRIMARY KEY, vin VARCHAR(255) NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);Step 4: Create the statement mappings
Section titled “Step 4: Create the statement mappings”Define SQL statement templates with parameter extractors for each schema name. Use helper functions like Guid() to convert string values to their proper types:
{ "VehicleRegistered": { "Statement": "INSERT INTO vehicle_registrations (id, vin) VALUES (@id, @vin)", "Extractor": "(record) => ({ id: Guid(record.value.registrationId), vin: record.value.vin })" }}Step 5: Encode the mappings to base64
Section titled “Step 5: Encode the mappings to base64”PowerShell:
$mappings = @'{ "VehicleRegistered": { "Statement": "INSERT INTO vehicle_registrations (id, vin) VALUES (@id, @vin)", "Extractor": "(record) => ({ id: Guid(record.value.registrationId), vin: record.value.vin })" }}'@
$encoded = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($mappings))Write-Output $encodedBash/Linux:
echo -n '{ "VehicleRegistered": { "Statement": "INSERT INTO vehicle_registrations (id, vin) VALUES (@id, @vin)", "Extractor": "(record) => ({ id: Guid(record.value.registrationId), vin: record.value.vin })" }}' | base64 -w 0Expected output:
ewogICJWZWhpY2xlUmVnaXN0ZXJlZCI6IHsKICAgICJTdGF0ZW1lbnQiOiAiSU5TRVJUIElOVE8gdmVoaWNsZV9yZWdpc3RyYXRpb25zIChpZCwgdmluKSBWQUxVRVMgKEBpZCwgQHZpbikiLAogICAgIkV4dHJhY3RvciI6ICIocmVjb3JkKSA9PiAoeyBpZDogR3VpZChyZWNvcmQudmFsdWUucmVnaXN0cmF0aW9uSWQpLCB2aW46IHJlY29yZC52YWx1ZS52aW4gfSkiCiAgfQp9Step 6: Create and start the connector
Section titled “Step 6: Create and start the connector”Create the connector:
Dictionary<string, string> settings = new() { ["instanceTypeName"] = "sql-sink", ["type"] = "PostgreSql", ["connectionString"] = "Host=127.0.0.1;Port=54322;Database=postgres;Username=postgres;Password=postgres", ["reducer:mappings"] = "<base64-encoded-mappings-from-step-5>", ["subscription:filter:scope"] = "stream", ["subscription:filter:filterType"] = "streamId", ["subscription:filter:expression"] = "vehicles"};
await client.Connectors.Create("vehicles-to-postgres", settings);Start the connector:
await client.Connectors.Start("vehicles-to-postgres");Step 7: Test with sample data
Section titled “Step 7: Test with sample data”Append a test record to the vehicles stream. The record’s schema name must match the mapping
key from step 4, and properties serialize to camelCase, which is what the extractor reads:
public record VehicleRegistered(string RegistrationId, string Vin);
await client.Streams.AppendStream(new AppendRecord { Stream = "vehicles", Value = new VehicleRegistered("a1b2c3d4-e5f6-7890-abcd-ef1234567890", "1HGBH41JXMN109186")});Step 8: Verify the results
Section titled “Step 8: Verify the results”- Open Supabase Studio at
http://127.0.0.1:54323 - Navigate to Table Editor → vehicle_registrations
- You should see the inserted record:
| id | vin | created_at |
|---|---|---|
| a1b2c3d4-e5f6-7890-abcd-ef1234567890 | 1HGBH41JXMN109186 | 2025-11-26 14:23:15 |