EXPERIMENTAL CHANGEFEED FOR

On this page

The EXPERIMENTAL CHANGEFEED FOR statement creates a new core changefeed, which streams row-level changes to the client indefinitely until the underlying connection is closed or the changefeed is canceled. A core changefeed can watch one table or multiple tables in a comma-separated list.

For more information, see Change Data Capture Overview.

Required privileges

New in v22.2: You can grant a user the CHANGEFEED privilege to allow them to create changefeeds on a specific table:

GRANT CHANGEFEED ON TABLE example_table TO user;

This privilege model provides a more granular way to grant users the ability to create a changefeed on a table. A user granted the CHANGEFEED privilege can create changefeeds on the target table even if the user does not have the CONTROLCHANGEFEED role option or the SELECT privilege on the table.

Since you can grant the CHANGEFEED privilege to a user or role without them needing the SELECT privilege on a table, these users will be able to create changefeeds, but they will not be able to run a SELECT query on that data directly. However, these users will be able to read this data indirectly as EXPERIMENTAL CHANGEFEED FOR emits changefeed messages to the SQL session.

You can add CHANGEFEED to the user or role's default privileges with ALTER DEFAULT PRIVILEGES:

ALTER DEFAULT PRIVILEGES GRANT CHANGEFEED ON TABLES TO user;

Legacy privilege model

Changefeeds can only be created by superusers, i.e., members of the admin role. The admin role exists by default with root as the member.

Considerations

• Because core changefeeds return results differently than other SQL statements, they require a dedicated database connection with specific settings around result buffering. In normal operation, CockroachDB improves performance by buffering results server-side before returning them to a client; however, result buffering is automatically turned off for core changefeeds. Core changefeeds also have different cancellation behavior than other queries: they can only be canceled by closing the underlying connection or issuing a CANCEL QUERY statement on a separate connection. Combined, these attributes of changefeeds mean that applications should explicitly create dedicated connections to consume changefeed data, instead of using a connection pool as most client drivers do by default.

  This cancellation behavior (i.e., close the underlying connection to cancel the changefeed) also extends to client driver usage; in particular, when a client driver calls Rows.Close() after encountering errors for a stream of rows. The pgwire protocol requires that the rows be consumed before the connection is again usable, but in the case of a core changefeed, the rows are never consumed. It is therefore critical that you close the connection, otherwise the application will be blocked forever on Rows.Close().

• In most cases, each version of a row will be emitted once. However, some infrequent conditions (e.g., node failures, network partitions) will cause them to be repeated. This gives our changefeeds an at-least-once delivery guarantee. For more information, see Ordering Guarantees.

• As of v22.1, changefeeds filter out VIRTUAL computed columns from events by default. This is a backward-incompatible change. To maintain the changefeed behavior in previous versions where NULL values are emitted for virtual computed columns, see the virtual_columns option for more detail.

Synopsis

> EXPERIMENTAL CHANGEFEED FOR table_name [ WITH (option [= value] [, ...]) ];

Parameters

Options

Avro limitations

Below are clarifications for particular SQL types and values for Avro changefeeds:

• Decimals must have precision specified.
• BYTES (or its aliases BYTEA and BLOB) are often used to store machine-readable data. When you stream these types through a changefeed with format=avro, CockroachDB does not encode or change the data. However, Avro clients can often include escape sequences to present the data in a printable format, which can interfere with deserialization. A potential solution is to hex-encode BYTES values when initially inserting them into CockroachDB. This will ensure that Avro clients can consistently decode the hexadecimal. Note that hex-encoding values at insertion will increase record size.

• BIT and VARBIT types are encoded as arrays of 64-bit integers.

  For efficiency, CockroachDB encodes BIT and VARBIT bitfield types as arrays of 64-bit integers. That is, base-2 (binary format) BIT and VARBIT data types are converted to base 10 and stored in arrays. Encoding in CockroachDB is big-endian, therefore the last value may have many trailing zeroes. For this reason, the first value of each array is the number of bits that are used in the last value of the array.

  For instance, if the bitfield is 129 bits long, there will be 4 integers in the array. The first integer will be 1; representing the number of bits in the last value, the second integer will be the first 64 bits, the third integer will be bits 65–128, and the last integer will either be 0 or 9223372036854775808 (i.e., the integer with only the first bit set, or 1000000000000000000000000000000000000000000000000000000000000000 when base 2).

  This example is base-10 encoded into an array as follows:

  {"array": [1, <first 64 bits>, <second 64 bits>, 0 or 9223372036854775808]}
  

  For downstream processing, it is necessary to base-2 encode every element in the array (except for the first element). The first number in the array gives you the number of bits to take from the last base-2 number — that is, the most significant bits. So, in the example above this would be 1. Finally, all the base-2 numbers can be appended together, which will result in the original number of bits, 129.

  In a different example of this process where the bitfield is 136 bits long, the array would be similar to the following when base-10 encoded:

  {"array": [8, 18293058736425533439, 18446744073709551615, 13690942867206307840]}
  

  To then work with this data, you would convert each of the elements in the array to base-2 numbers, besides the first element. For the above array, this would convert to:

  [8, 1111110111011011111111111111111111111111111111111111111111111111, 1111111111111111111111111111111111111111111111111111111111111111, 1011111000000000000000000000000000000000000000000000000000000000]
  

  Next, you use the first element in the array to take the number of bits from the last base-2 element, 10111110. Finally, you append each of the base-2 numbers together — in the above array, the second, third, and truncated last element. This results in 136 bits, the original number of bits.

Examples

Create a changefeed

To start a changefeed:

EXPERIMENTAL CHANGEFEED FOR cdc_test;

In the terminal where the core changefeed is streaming, the output will appear:

table,key,value
cdc_test,[0],"{""after"": {""a"": 0}}"

For step-by-step guidance on creating a Core changefeed, see the Changefeed Examples page.

Create a changefeed with Avro

To start a changefeed in Avro format:

EXPERIMENTAL CHANGEFEED FOR cdc_test WITH format = avro, confluent_schema_registry = 'http://localhost:8081';

In the terminal where the core changefeed is streaming, the output will appear:

table,key,value
cdc_test,\000\000\000\000\001\002\000,\000\000\000\000\002\002\002\000

For step-by-step guidance on creating a Core changefeed with Avro, see the Changefeed Examples page.

Create a changefeed on a table with column families

To create a changefeed on a table with column families, use the FAMILY keyword for a specific column family:

EXPERIMENTAL CHANGEFEED FOR TABLE cdc_test FAMILY f1;

To create a changefeed on a table and output changes for each column family, use the split_column_families option:

EXPERIMENTAL CHANGEFEED FOR TABLE cdc_test WITH split_column_families;

For step-by-step guidance creating a Core changefeed on a table with multiple column families, see the Changefeed Examples page.

See also

• Change Data Capture Overview
• SQL Statements

Was this helpful?