Migrate from 5.x to 6.0

Version 6.0 is a major release with breaking changes. The configuration schema is the same as in 5.x, so the upgrade is an in-place plugin replacement. Check the changes on this page before you replace the plugin. For generic plugin upgrade steps, see Confluent Documentation → Upgrade a Connector Plugin.

Platform requirements

Version 6.0 requires:

  • Java 17 or later.

  • Apache Kafka Connect 4.3.0 or later.

  • Confluent Platform 8.3 or later.

Upgrade the Kafka Connect runtime before you upgrade the connector.

Replace neo4j.query.force-maps-as-struct

This section applies to source connectors with the QUERY strategy.

neo4j.query.force-maps-as-struct is removed. Use neo4j.query.map-encoding instead.

The connector ignores neo4j.query.force-maps-as-struct. If you set it to false and do not replace it, the connector uses the default STRUCT encoding, and the schemas of your topics change.

Replace the old property as follows:

neo4j.query.force-maps-as-struct neo4j.query.map-encoding Result

true or not set

STRUCT or not set

Every map is a STRUCT. Same behavior as true in 5.x.

false

LEGACY

A map is a MAP when its values share a type, and a STRUCT otherwise. Same behavior as false in 5.x.

For example, replace:

"neo4j.query.force-maps-as-struct": "false"

with:

"neo4j.query.map-encoding": "LEGACY"

The new MAP value describes every map as a MAP, and fails when the values of a map do not share a type. Use it only for maps with values of a single type. For details, see neo4j.query.map-encoding.

Check the exactly-once offset constraint

This section applies to sink connectors with neo4j.eos-offset-label set.

The sink task fails to start when the label has no node key constraint on the strategy, topic and partition properties. On Neo4j Community Edition, the label needs a uniqueness constraint instead. In 5.x, the connector did not check the constraint.

Before you upgrade, do one of the following:

  • Create the constraint on the target database. For example, if neo4j.eos-offset-label is __KafkaOffset, run:

    CREATE CONSTRAINT kafka_offset_key IF NOT EXISTS FOR (n:__KafkaOffset) REQUIRE (n.strategy, n.topic, n.partition) IS NODE KEY

  • Set neo4j.eos-offset-auto-constraint to true, so that the connector creates the constraint when a task starts. The connector user must have permission to create constraints.

Schema changes

After the upgrade, the connector can register new schema versions for existing topics. Check the compatibility mode of your Schema Registry subjects before you upgrade.

CDC strategy

Node and relationship events use one event schema, org.neo4j.connectors.kafka.cdc.Event. You can publish both to the same topic.

  • Every event has all fields. Fields that do not apply are null: type, start and end in node events, and labels, state.before.labels and state.after.labels in relationship events.

  • keys is an array of entries with name and rows fields, in node and relationship events, and in start and end. name is a label, or the relationship type. Each row holds the key properties in properties, as a map of EXTENDED structures, in both payload modes. In 5.x, node keys were a STRUCT with one field per label, and relationship keys were an array of STRUCT.

  • Message keys produced with the ENTITY_KEYS key strategy use the same keys format.

  • With the COMPACT payload mode, state.before.properties and state.after.properties are still a STRUCT with one field per property. Events with different properties have different schemas. With the EXTENDED payload mode, they are a MAP, and the schema does not depend on the properties.

A 6.0 sink connector cannot read CDC messages produced by a 5.x source connector. Before you upgrade a CDC sink connector, make sure that it has processed all messages produced by 5.x source connectors.

QUERY strategy

  • With LEGACY, a message is always a STRUCT with one field per returned column. In 5.x, a message was a MAP when all columns had values of the same type.

  • With the EXTENDED payload mode, a list is described as a STRUCT with fields e0, e1, and so on, when its elements hold an empty list and a list of maps under the same key.

EXTENDED payload mode

The EXTENDED structure has two new fields, UI and LUI, for Neo4j UUID values and lists of UUID values. Every topic with the EXTENDED payload mode gets a new schema version. For details, see Kafka Source Connector: Payload Mode Configuration.

Authentication

  • neo4j.authentication.type values are lowercase: none, basic, kerberos, bearer, custom. The value is case-insensitive, so uppercase values from 5.x still work.

  • The new oidc provider obtains and refreshes tokens from an OAuth 2.0 or OpenID Connect identity provider.

  • You can add an authentication provider of your own.

For details, see Authentication.

Neo4j UUID type

Version 6.0 supports the Neo4j UUID type, available in Neo4j 2026.08 and later.

  • Source connectors publish a UUID value as a string. With the COMPACT payload mode, the string has the org.neo4j.connectors.kafka.UUID schema name. With the EXTENDED payload mode, the value is in the UI field.

  • Sink connectors write these values as UUID values. If the target database does not support the UUID type, sink connectors write them as strings.