Ensure database.history.kafka.topic (MySQL) or schema.history.internal.kafka.topic (PostgreSQL with schema history) is configured with infinite retention; this topic stores the full DDL history needed for schema reconstruction.
When a DDL change occurs (e.g., ALTER TABLE ADD COLUMN), Debezium emits a schema change event on the schema history topic before the subsequent DML events, capturing the new schema.
Downstream consumers using the Debezium Kafka Avro converter and Schema Registry automatically receive the updated schema when the first event with the new schema arrives; Schema Registry assigns a new schema ID.
For JSON converters without Schema Registry, the schema field in each event envelope reflects the current schema at event time; consumers must handle schema evolution by checking the schema block in each message.
Test schema change handling by executing an ALTER TABLE in the source and verifying that downstream consumers process events both before and after the DDL without errors.
Known gotchas
If the schema history topic is deleted or becomes corrupted, the connector cannot reconstruct the schema for binlog events that predate the current snapshot; the connector must be reset and re-snapshot the source.
Some schema changes that are backward-incompatible with the Schema Registry compatibility mode (e.g., deleting a required field) will cause Schema Registry registration to fail; review compatibility settings before performing DDL on captured tables.
Debezium does not capture DDL changes on tables that are not in the captured table list; if a JOIN or view dependency changes schema, downstream consumers may see unexpected null values without any schema change event.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp