Create and Configure Changefeeds

Changefeeds offer different levels of configurability. Changefeeds emitting to a sink allow for active changefeed jobs to be paused, resumed, and canceled. Sinkless changefeeds stream changes directly to the SQL session.

This page describes:

• Guidelines to consider before creating a changefeed.
• Reference examples for creating and managing a changefeed.

Before you create a changefeed

1. Enable rangefeeds on CockroachDB Advanced and CockroachDB self-hosted. Refer to Enable rangefeeds for instructions.
2. Decide on whether you will run a changefeed that emits to a sink or a sinkless changefeed. Refer to the page for a comparative capability table.
3. Plan the number of changefeeds versus the number of tables to include in a single changefeed for your cluster. We recommend limiting the number of changefeeds per cluster to 80. Refer to and .
   • If you’re using a CockroachDB Cloud cluster, refer to for detail on how CDC is billed monthly based on usage.
4. Consider whether your changefeed use case would be better served by that can filter data on a single table. CDC queries can improve the efficiency of changefeeds because the job will not need to encode as much change data.
5. Read the following:
   • The reference for details on planning changefeeds, monitoring basics, and schema changes.
   • The Considerations section that provides information on changefeed interactions that could affect how you configure or run your changefeed.

Enable rangefeeds

Changefeeds connect to a long-lived request called a rangefeed, which pushes changes as they happen. This reduces the latency of row changes, as well as reduces transaction restarts on tables being watched by a changefeed for some workloads.

Rangefeeds must be enabled for a changefeed to work. To :

SET CLUSTER SETTING kv.rangefeed.enabled = true;

Any created changefeeds will error until this setting is enabled. If you are working on a CockroachDB Basic or Standard cluster, the kv.rangefeed.enabled cluster setting is enabled by default.

Enabling rangefeeds has a small performance cost (about a 5–10% increase in write latencies), whether or not the rangefeed is being used in a changefeed. When kv.rangefeed.enabled is set to true, a small portion of the latency cost is caused by additional write event information that is sent to the and for . The remainder of the latency cost is incurred once a changefeed is running; the write event information is reconstructed and sent to an active rangefeed, which will push the event to the changefeed.

For further detail on performance-related configuration, refer to the page.

is a subsystem that improves the performance of rangefeeds with scale, which is enabled by default in v24.1 and later versions.

Considerations

• If you require message frequency under 30s, then you must set the option to at least the desired resolved frequency.
• Many DDL queries (including , , and queries that add a column family) will cause errors on a changefeed watching the affected tables. You will need to . If a table is truncated that a changefeed with on_error='pause' is watching, you will also need to start a new changefeed. Refer to the change data capture Known Limitations for more detail.
• Partial or intermittent sink unavailability may impact changefeed stability. If a sink is unavailable, messages can’t send, which means that a changefeed’s high-water mark timestamp is at risk of falling behind the cluster’s . Throughput and latency can be affected once the sink is available again. However, will still hold for as long as a changefeed .
• When an statement is run, any current changefeed jobs targeting that table will fail.
• After you , changefeed jobs will not resume on the new cluster. It is necessary to manually create the changefeeds following the full-cluster restore.
• As of v22.1, changefeeds filter out from events by default. This is a . To maintain the changefeed behavior in previous versions where values are emitted for virtual computed columns, see the option for more detail.

The following sections outline how to create and configure each type of changefeed:

Changefeeds

Configure a changefeed

A changefeed streams row-level changes in a to one of the following sinks:

• (in Preview)
• / HTTP

You can create, pause, resume, and cancel a changefeed emitting messages to a sink. For a step-by-step example connecting to a specific sink, see the page.

Create

To create a changefeed:

CREATE CHANGEFEED FOR TABLE table_name, table_name2 INTO '{scheme}://{sink_host}:{port}?{query_parameters}';

Parameters should always be URI-encoded before they are included the changefeed’s URI, as they often contain special characters. Use Javascript’s encodeURIComponent function or Go language’s url.QueryEscape function to URI-encode the parameters. Other languages provide similar functions to URI-encode special characters.

For more information, see .

Show

To show a list of changefeed jobs:

SHOW CHANGEFEED JOBS;

    job_id             |                                                                                   description                                                                  | ...
+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ ...
  685724608744325121   | CREATE CHANGEFEED FOR TABLE mytable INTO 'kafka://localhost:9092' WITH confluent_schema_registry = 'http://localhost:8081', format = 'avro', resolved, updated | ...
  685723987509116929   | CREATE CHANGEFEED FOR TABLE mytable INTO 'kafka://localhost:9092' WITH confluent_schema_registry = 'http://localhost:8081', format = 'avro', resolved, updated | ...
(2 rows)

To show an individual changefeed:

SHOW CHANGEFEED JOB {job_id};

        job_id        |                                               description                                               | user_name | status  |              running_status              |            created            |            started            | finished |           modified            |      high_water_timestamp      | readable_high_water_timestamptz | error |                          sink_uri                          |         full_table_names         | topics | format
----------------------+---------------------------------------------------------------------------------------------------------+-----------+---------+------------------------------------------+-------------------------------+-------------------------------+----------+-------------------------------+--------------------------------+---------------------------------+-------+------------------------------------------------------------+----------------------------------+--------+---------
  1053639803034894337 | CREATE CHANGEFEED FOR TABLE customers INTO 'gs://bucket-name?AUTH=specified&CREDENTIALS=redacted'       | root      | running | running: resolved=1741616141.951323000,0 | 2025-03-10 14:09:10.047524+00 | 2025-03-10 14:09:10.047524+00 | NULL     | 2025-03-10 14:15:44.955653+00 | 1741616141951323000.0000000000 | 2025-03-10 14:15:41.951323+00   |       | gs://bucket-name?AUTH=specified&CREDENTIALS=redacted       | {online_retail.public.customers} | NULL   | json
(1 row)

SHOW CHANGEFEED JOBS will return all changefeed jobs from the last 12 hours. For more information on the retention of job details, refer to the section.

You can filter the columns that SHOW CHANGEFEED JOBS displays using a SELECT statement:

SELECT job_id, sink_uri, status, format FROM [SHOW CHANGEFEED JOBS] WHERE job_id = 997306743028908033;

        job_id       |    sink_uri      | status   | format
---------------------+------------------+----------+---------
  997306743028908033 | external://kafka | running  | json

For more information, refer to .

Pause

To pause a changefeed:

PAUSE JOB job_id;

For more information, refer to .

Resume

To resume a paused changefeed:

RESUME JOB job_id;

For more information, refer to .

Cancel

To cancel a changefeed:

CANCEL JOB job_id;

For more information, refer to .

Modify a changefeed

To modify a changefeed, the job and then use:

ALTER CHANGEFEED job_id {ADD table DROP table SET option UNSET option};

You can add new table targets, remove them, set new , and unset them.

For more information, see .

Configuring all changefeeds

It is useful to be able to pause all running changefeeds during troubleshooting, testing, or when a decrease in CPU load is needed.

To pause all running changefeeds:

PAUSE JOBS (WITH x AS (SHOW CHANGEFEED JOBS) SELECT job_id FROM x WHERE status = ('running'));

This will change the status for each of the running changefeeds to paused, which can be verified with .

To resume all running changefeeds:

RESUME JOBS (WITH x AS (SHOW CHANGEFEED JOBS) SELECT job_id FROM x WHERE status = ('paused'));

This will resume the changefeeds and update the status for each of the changefeeds to running.

Sinkless changefeeds

Create a sinkless changefeed

When you create a changefeed without specifying a sink (a sinkless changefeed), CockroachDB sends the changefeed events to the SQL client indefinitely until the underlying connection is closed or the changefeed is canceled:

CREATE CHANGEFEED FOR TABLE table_name, table_name2;

Consider the following regarding the in your SQL client:

• If you do not define a display format, the CockroachDB SQL client will automatically use ndjson format.
• If you specify a display format, the client will use that format (e.g., --format=csv ).
• If you set the client display format to ndjson and set the changefeed to csv, you’ll receive JSON format with CSV nested inside.
• If you set the client display format to csv and set the changefeed to json, you’ll receive a comma-separated list of JSON values.

For more information, see .

Known limitations

• Changefeed target options are limited to tables and .
• and in CockroachDB Advanced clusters do not support connecting to a sink’s internal IP addresses for . To connect to a Kafka sink from CockroachDB Advanced, it is necessary to expose the Kafka cluster’s external IP address and open ports with firewall rules to allow access from a CockroachDB Advanced cluster.
• Webhook sinks only support HTTPS. Use the parameter when testing to disable certificate verification; however, this still requires HTTPS and certificates.
• Formats for changefeed messages are not supported by all changefeed sinks. Refer to the page for details on compatible formats with each sink and the option to specify a changefeed message format.
• Using the and options on the same changefeed will cause an error when using the following : Kafka and Google Cloud Pub/Sub. Instead, use the individual FAMILY keyword to specify column families when creating a changefeed.
• Changefeed types are not fully integrated with . Running changefeeds with user-defined composite types is in . Certain changefeed types do not support user-defined composite types. Refer to the change data capture for more detail. The following limitations apply:
  • A changefeed in will not be able to serialize .
  • A changefeed emitting will include AS labels in the message format when the changefeed serializes a .
• is not fully supported with changefeeds that use . You can alter the options that a changefeed uses, but you cannot alter the changefeed target tables.
• Creating a changefeed with on tables with more than one is not supported.
• When you create a changefeed on a table with more than one , the changefeed will emit messages per column family in separate streams. As a result, for different column families will arrive at the under separate topics.

See also