YugabyteDB: Handling Schema Changes

Prerequisites for Handling Schema Changes

To support any schema changes at the table and column levels in Yugabyte databases, the following configurations are required in both T-Server and Master gflag lists:

cdcsdk_publication_list_refresh_interval_secs

Defines the refresh interval for the publication list.
Configure according to the wait time suitable for your environment (default: 900 seconds).

cdcsdk_enable_dynamic_table_support

Enables dynamic table support in CDC.
By default, it is set to true. Confirm it is explicitly true for both T-Server and Master gflags.

Guidelines for handling schema changes in Oracle GoldenGate for Yugabyte

The following guidelines are important and must be considered when performing DDL operations on the Yugabyte database:

Always respect the cdcsdk_publication_list_refresh_interval_secs interval before performing DML operations.
Stop the Extract to ensure safe schema changes and prevent potential data capture issues.
After restarting the Extract, always validate that new or remaining columns are properly captured.
Yugabyte database does not support dropping a table. Refer to the following link to know more:

https://docs.yugabyte.com/stable/additional-features/change-data-capture/using-logical-replication/#limitations

Handling Table Level Schema Changes

Learn about handling table level schema changes in Oracle GoldenGate for YugabyteDB.

Add a New Table to an Existing Extract Process

This procedure depends on the publication configuration of Yugabyte. There are two types of publications:

Publication Configured for All Tables: In this type of publication, new tables are added dynamically and no changes are required to the publication.
Publication Configured for a Set of Tables: If a new table is created, then the publication must be altered to include the new table.

Add a new table to an exisiting Extract process

Following are the common steps to add a new table for an existing Extract process:

Stop the Extract process before making changes.
Update the Extract parameter file to add the new table or tables to the Extract configuration.
Wait for Refresh Interval defined in cdcsdk_publication_list_refresh_interval_secs.

Optionally, allow a small buffer window to ensure the table is fully refreshed in the CDC module.
Restart the Extract process after the refresh interval completes.
Perform DML operations on the new table.
Verify that the Extract captures the new records successfully.

Add a New Table to an Existing Extract Process - Example

Consider the scenario for this example:

One table exists with two configured publications:

Publication 1 (pub1): Specific table
Publication 2 (pub2): All tables
Two Extracts (Ext1 using pub1, Ext2 using pub2) with static table lists
DML operations on the static table are captured by both Extracts

The following example provides the steps to add a new table to an existing Extract process based on the preceding considerations:

Stop Ext1 and Ext2.
Create new tables (table2, table3).
Update extract parameter files for Ext1 and Ext2.
Alter pub1 to include new tables. Pub2 does not require changes.
Restart Ext1 and Ext2.
Wait for the refresh interval (cdcsdk_publication_list_refresh_interval_secs).
Perform DML operations on new tables and verify that both Extracts capture them successfully.

Drop a Table from an Extract Process

There are two scenarios to consider when dropping a table:

Table is Part of a Publication

If the table is included in a publication, dropping the table is not allowed. If you attempt drop the table in this scenario, it make the stream or replication slot used by the Extract, unusable, and you may encounter errors such as:

2026-03-04 11:21:44 ERROR OGG-30611 Yugabyte has closed the streaming client and has caused the Extract to abend. 
Error: ERROR: XX000: LookupByIdRpc(tablet: d092b524eff34d21b45c78ead108122a, num_attempts: 1) failed: Tablet deleted: Table deleted at 2026-03-04 11:21:44 UTC. 
CONTEXT: Catalog Version Mismatch: A DDL occurred while processing this query. Try again.LOCATION: YBPrepareCacheRefreshIfNeeded, postgres.c:4160.

Or

2026-03-04 11:22:51 ERROR OGG-30605 Dropping any table used by the Extract will cause the Extract to abend and disconnect the YDB streaming client. 
Error: ERROR: XX000: VirtualWAL initialisation failed for stream_id: afdaa2e91ebc288be74724e8fb780342 & session_id: 51: Table 000033cf00003000800000000000400f not found under stream
CONTEXT: Catalog Version Mismatch: A DDL occurred while processing this query. Try again.LOCATION: YBPrepareCacheRefreshIfNeeded, postgres.c:4160.

Caution:

If such errors occur, the only resolution is to unregister the affected Extract and register it again. This step is critical to restore normal operation.This may also cause data loss. So caution is needed.

Table is Not Part of a Publication: If the table is not included in any publication, dropping it has no impact on the stream. No action is required, and replication will continue as usual.

Handling Column Level Schema Changes

Learn about handling column level schema changes such as adding and dropping columns in Oracle GoldenGate for YugabyteDB.

Add a Column

To perform an ALTER TABLE … ADD COLUMN operation on a table that is part of a publication:

Stop the Extract process before you begin adding a column to the table. This prevents Extract from abending.
Add the column in the table that is included in the publication using the following command:
```
ALTER TABLE...ADD COLUMN
```
Wait for the duration specified in the cdcsdk_publication_list_refresh_interval_secs to ensure that the CDC module refreshes and recognizes the new column.
Run any DML operations (INSERTS, UPDATES, or DELETES) on the new column.
Restart the Extract process and verify that the changes, including the DML operations on the new column are captured successfully.

Drop a Column

To drop a column(s) from a table that is part of a publication:

Stop the Extract process. Although dropping a column usually does not cause the Extract to abend, it is still recommended to stop the Extract before making schema changes.
Run the following command on the table included in the publication:
```
ALTER TABLE … DROP COLUMN
```
Wait for the duration specified in cdcsdk_publication_list_refresh_interval_secs to ensure the CDC module is updated.
Run any DML operations (INSERT, UPDATE, DELETE), as required.
Restart the Extract and confirm that the DML operations on the remaining columns continue to be captured correctly.