In Debezium, what does the required topic.prefix connector property control?

## What the property is `topic.prefix` is a required property on every Debezium connector. It gives the source a *logical name*, chosen by you, that is independent of hostnames or database names. It replaced `database.server.name` in Debezium 2.0; older tutorials and blog posts still show the old key, which is the most common source of confusion when reading examples. The value must be unique among all connectors writing to the same Kafka cluster, and it is validated: only alphanumeric characters, hyphens, dots and underscores are accepted, because the value ends up inside Kafka topic names. ## Where the value shows up **Data-change topics.** One topic per captured table, named by fully-qualified source identifier prefixed with the logical name. For Postgres, SQL Server and Oracle that is `<topic.prefix>.<schemaName>.<tableName>`; for MySQL, which has no schema layer, `<topic.prefix>.<databaseName>.<tableName>`. With `topic.prefix=inventory`, changes to `public.customers` land on `inventory.public.customers`. **Schema-change topic.** Named exactly `<topic.prefix>` — the bare value, no suffix. This surprises people who expect a suffix and then find an unexplained topic sitting next to their data topics. **Heartbeat topic.** `__debezium-heartbeat.<topic.prefix>`, when `heartbeat.interval.ms` is enabled. **Transaction metadata topic.** `<topic.prefix>.transaction`, when `provide.transaction.metadata` is on. **Metrics.** The connector's JMX beans carry the logical name as the `server` attribute, so dashboards and alerts key off it too. Rename the prefix and every metric series starts fresh. **Stored state.** This is the part that turns a naming convention into an identity. The prefix is part of the source-partition key under which Debezium persists its position in the source log, and part of how schema history is scoped. The connector looks up its position using that key on every restart. ## Why uniqueness is not optional Two connectors configured with the same prefix are not merely writing to the same topics — they are reading and writing the same stored state. Each will find the other's recorded position on startup and try to resume from it, on a log it may not even share. On MySQL, both will also try to own the same schema history. The result is not a clean error; it is corrupted position tracking and events that appear or vanish unpredictably. Treat the prefix as a primary key across your whole capture estate, and keep an explicit registry of allocated names if several teams deploy connectors. ## Changing it after the fact Changing `topic.prefix` on a running connector is effectively deleting the connector and creating a new one. On restart it computes a new state key, finds nothing under it, and behaves as a first-time deployment — meaning it will take an initial snapshot if its snapshot configuration says to, or start from the current log position if not. Meanwhile it begins writing to an entirely new set of topics; the old topics stay behind, frozen, and every downstream consumer subscribed to them silently stops receiving data. Nothing is renamed and nothing is migrated. The practical consequence: pick the prefix before you go live, and pick it for what the source *means* rather than where it currently runs. `inventory` survives a database migration from one host to another; `pg-prod-eu-west-1b` does not, and the day you move the database someone will be tempted to rename it. ## Choosing a good value A workable convention is `<domain>` or `<system>_<environment>` — short, stable, meaningful to consumers who will see it in every topic name. Avoid embedding hostnames, IPs, replica identifiers or version numbers. Keep environments separated: staging and production connectors against copies of the same database must not share a prefix, or their state and topics collide. Also remember that the prefix is only the first segment. Downstream teams frequently want a different topic layout — a single topic per aggregate, or a flatter name. That is a routing concern handled by transformations in the pipeline layer, not by bending `topic.prefix`; the prefix should stay a stable identity for the source. ## Interview framing The question usually starts as trivia about topic naming and then pivots: *what happens if you change it?* The strong answer names all three roles at once — namespace for topics, identity for stored offsets and schema history, and label on metrics — and concludes that renaming is a re-deployment, not a rename.