Context

Debezium connectors are capable of detecting and emitting schema change events, which occur when a source database's structure is modified. A Quarkus-native way to observe these events is necessary to fully integrate Debezium into event-driven microservices or monitoring workflows.

Decision

Introduce a new annotation: @DebeziumSchemaChangeListener.

import io.debezium.engine.InsertEvent;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped  
class SchemaChangeListener {  
  
    @DebeziumSchemaChangeListener()  
    public void listener(SchemaChangeEvent event) {  
        /// some logic to apply
    }  
}

This annotation allows CDI-managed beans in a Quarkus application to react to schema change events directly. Annotated methods should accept a single argument of type SchemaChangeEvent, which provides metadata about the change.

The Quarkus Debezium extension will route schema change events from the Debezium engine to all appropriately annotated listener methods.

Consequences

• Requires integration with Debezium’s internal schema change reporting API.

• Listeners must be scanned at build time and registered for invocation at runtime.

• The SchemaChangeEvent class and any referenced types must be made compatible with GraalVM native image generation.

• Error handling policies (e.g., whether to suppress or propagate listener exceptions) must be defined and documented.

References:

Debezium Design Document: https://github.com/debezium/debezium-design-documents/pull/16