Syncs

A sync reads a table or SQL query in your data warehouse on a schedule and writes the rows into Knock. Use syncs to keep your users, tenants, and other recipient data in Knock up to date from your warehouse.

To send Knock's message data to your warehouse instead, see warehouse export.

1. Connect a warehouse. Go to Platform > Sources and add your warehouse. You add a warehouse once for your whole account.
2. Create a sync. A sync reads a table or SQL query, then writes each changed row to the corresponding resource in Knock. You create a sync in each Knock environment you want to sync into, and choose how columns map to Knock fields and how often it runs. See create a sync.

When you publish a sync, it runs once right away and then on its schedule. Each run applies only the rows that changed since the last run.

Warehouse	How Knock connects
Amazon Redshift	An IAM role you give Knock access to
Snowflake	Key-pair authentication
PostgreSQL	A database user and password
Google BigQuery	A service account in your Google Cloud project
Databricks	Coming soon

If you'd like us to support a warehouse that isn't listed, let us know at support@knock.app.

A warehouse's page in the dashboard has three tabs:

• Syncs lists the warehouse's syncs in your current environment.
• Runs lists recent runs of those syncs.
• Details has the connection, which every environment shares.

Each sync writes to one of these resources in Knock:

Target	What each row does
Users	Creates or updates a user.
Tenants	Creates or updates a tenant.
Objects	Creates or updates an object in one collection.
Audience members	Updates members of a static audience.
Subscriptions	Manages a user's subscription to an object.

To create a sync, switch to the environment you want to sync into, go to Platform > Sources, open the warehouse, and click Create sync. Then complete the following steps.

To find a sync, go to Platform > Sources in the environment it syncs into and open its warehouse. The Syncs tab lists the warehouse's syncs with their status and last run.

A sync's page has four tabs:

• Overview shows the sync's recent and next runs and its current setup.
• Runs lists recent runs.
• Settings has the schedule and the option to archive the sync.
• Changes lists each published version.

Status	Meaning
Draft	Saved but never published, so it doesn't run.
Publishing	Knock is making the published version live.
Delivery failed	The published version didn't go live. Click Retry delivery on the sync.
Live	Runs on its schedule.
Needs attention	The last run failed. The sync keeps running on its schedule.
Paused	Published, but doesn't run until you resume it.

A published sync can also have a draft. When you save edits to a published sync without publishing them, it keeps its status, shows Unpublished changes, and keeps running the published version until you publish.

Click Run now on a published sync to run it right away. If a run is already in progress, Knock doesn't start another.

Click Pause on the sync, or turn off Run on schedule on its Settings tab. A run that has already started finishes. Click Resume to start running on the schedule again.

On the sync's Settings tab, change the Frequency. Schedule changes apply right away and don't create a new version.

On the sync's Overview tab, click the edit button on the section you want to change: Details, Source, Mappings, or Change detection. The key, target, and warehouse can't be changed.

Click Save to save a new version. The sync shows Unpublished changes until you click Publish.

When you publish a change to the table or query, the primary key, or a change detection column, the next run reads every row in the source again. Rows removed from the source before that run aren't treated as deleted.

The Changes tab lists every published version of the sync, newest first, with who published it and when. Click the revert button on a version to publish it again as a new version. You can revert in any environment, including Production.

Click Clone on a sync to copy its source, mappings, and schedule into a new sync. The copy can go in the same environment or another one.

Enter a name and key for the copy, and choose the warehouse it reads from. For object and subscription syncs, you can change the collection. For audience syncs, choose an audience in the environment you're cloning into.

The copy includes the sync's unpublished changes. It starts as a draft, with no runs.

On the sync's Settings tab, click Archive sync. Knock stops running the sync, and its key can be used again. Records it already wrote stay in Knock. This can't be undone.

The sync's Runs tab lists its 25 most recent runs, with when each started, its status, how many rows it read, and how many failed. The warehouse's Runs tab lists the 25 most recent runs across all its syncs, and you can filter it by sync or status.

Status	Meaning
Running	The run is in progress.
Completed	Every changed row was applied.
Completed with errors	Some rows were applied and some weren't.
Failed	The run stopped. The run details show why.

Each run only applies rows that changed since the last run. A run that finds no changes applies nothing.

Click a run to see its details:

• Rows read, Rejected, Applied, and Failed. Rejected rows never reached Knock. Failed rows reached Knock but couldn't be saved.
• For a failed run, where it stopped and the error.
• Rejected rows and Failed rows, with a sample of each grouped by error, and the primary keys each error affected.
• The batches Knock received. Large runs arrive in several batches, which Knock applies in order.

The sync shows Needs attention, and its Overview tab says why the last run failed. If the warehouse's connection works, the warehouse also shows Needs attention on the Sources page. The sync keeps running on its schedule, and the status clears after a run succeeds.

What happens when a row is deleted depends on what the sync writes to.

Subscriptions and audience members. When a row is deleted from your warehouse or no longer matches your query, Knock unsubscribes the user from the object or removes them from the audience. You can also use a deleted flag column to mark rows to remove. If the sync has a last modified column, Knock only sees rows that changed, so use a deleted flag column instead of deleting rows.

Users, tenants, and objects. Deleting a row doesn't delete the record in Knock. To delete records, add a deleted flag column and a last modified column to the sync. Knock deletes the records for rows where the flag is true. This can't be undone.

A warehouse is shared by every environment in your account. A sync belongs to one environment, so you can sync into Development and Production separately from the same warehouse. To copy a sync into another environment, clone it.

Syncs aren't part of the commit and promote flow. You create and edit a sync in the environment it syncs into, including Production. Each published version is listed on the sync's Changes tab, where you can revert to an earlier one. Syncs aren't available in branch environments.

Action	Built-in roles	Custom permission groups
Add, edit, test, and archive warehouses	Owner, Admin	Can manage integrations
View warehouses and syncs	Owner, Admin, Member, Production-only member	Can view recipient data
Create and manage syncs	Owner, Admin, Member, Production-only member	Can manage recipient data

Production-only members can view and manage syncs only in Production.

To open the Sources page, a custom permission group must also be allowed to view integrations. Recipient data permissions are set per environment, so it's possible for a custom group to manage syncs in Development and only view them in Production. See roles and permissions for more information.

The connection's status shows on the warehouse's page and in the Connected list on the Sources page:

Status	Meaning
Not configured	No connection has been saved yet.
Key not installed	Knock generated a key. Install it, then test the connection.
Connecting	Knock is setting up the connection.
Not tested	The connection is saved but hasn't been tested.
Connected	The last test succeeded.
Connection failed	The last test failed. The error shows on the Details tab.

If the connection works but one of the warehouse's syncs is failing in your current environment, the warehouse shows Needs attention. See when a run fails.

A connection change applies to every environment. Test the connection after you change it.

Redshift and PostgreSQL connections can go through a bastion host when the database isn't reachable from the internet.

1. Create a user for Knock on the bastion host, such as knock-sync.
2. On the warehouse's Details tab, click Connect through an SSH tunnel and enter the Tunnel host, Tunnel port, and Tunnel user.
3. Leave Public key empty and click Save connection. Knock generates a key pair and shows the public key, labeled knock-ssh-tunneling-public-key.
4. Click Copy public key and add it to the tunnel user's ~/.ssh/authorized_keys on the bastion host.
5. Click Test connection.

To use a key that's already authorized on the bastion host, paste its public key into Public key before saving.

To remove a warehouse, first archive its syncs in every environment. Then click Archive warehouse on its Details tab. Knock removes the warehouse from every environment and deletes its saved connection, including any password or key. This can't be undone. To sync from the database again, add it as a new warehouse.

Knock reads values as your warehouse returns them. Convert types in a SQL query when a column doesn't match its Knock field.

A user's created_at must include a timezone, such as 2026-09-26T20:19:49Z.

• Redshift and PostgreSQL. TIMESTAMP columns have no timezone, so Knock rejects rows that map one to created_at. Convert it in your query. For timestamps stored in UTC:

  For timestamps stored in another time zone, name it: CONVERT_TIMEZONE('America/New_York', 'UTC', created_at)::TIMESTAMPTZ in Redshift, or created_at AT TIME ZONE 'America/New_York' in PostgreSQL. TIMESTAMPTZ columns can be mapped directly.

• Snowflake. Timestamp columns, including TIMESTAMP_NTZ, can be mapped directly.

• Text columns. The value must include a timezone, such as Z or +00:00.

Record IDs are strings. If your ID column is a number, cast it in your query, such as CAST(account_id AS VARCHAR).

Problem	What to check
A table is missing from the table picker	Click the refresh icon next to the table picker. If it's still missing, check the database user's grants.
The preview or a run fails reading the source	That the database user can read every table the query uses.
Every row is rejected	A type mismatch, most often a Redshift or PostgreSQL TIMESTAMP mapped to created_at. See timestamps.
Some rows are rejected or failed	The Rejected rows and Failed rows on the run. Fix or filter those rows in a SQL query.
A record is still in Knock after its row is gone	See deleted rows. If the sync has a last modified column, set the row's deleted flag instead of deleting the row.
No runs appear	That the sync is published and not paused. Click Run now to run it without waiting.