Migration Guide from 2.x to 3.x

  • 升级至 DataStax 驱动程序 4，带来了依赖项更改和配置调整。

  • Cluster 和 Session 对象合并，简化了配置。

  • 架构支持迁移到 cassandra:session-factory 命名空间元素。

  • 映射上下文、上下文和模板 API Bean 需要显式声明。

  • 某些数据模型功能（如 @CassandraType）需要更新。

  • 代码必须针对 DataStax 驱动程序 4 的 API 更改进行调整。

  • 弃用了某些功能，并引入了新的功能（如 StatementBuilder 和 KeyspacePopulator）。

3.0 版用于 Apache Cassandra 的 Spring Data 在从较早版本升级时引入了一组重大更改。

Spring Data for Apache Cassandra 3.0 introduces a set of breaking changes when upgrading from earlier versions.

Review dependencies

升级到 Spring Data Cassandra 需要升级到 DataStax Driver 版本 4。升级到新驱动程序会带来瞬态依赖项更改，最明显的是，Google Guava 已被驱动程序捆绑并遮蔽。有关与驱动程序相关的更改的详细信息，请查看 DataStax Java Driver for Apache Cassandra 4 Upgrade Guide。

Upgrading to Spring Data Cassandra requires an upgrade to the DataStax Driver version 4. Upgrading to the new driver comes with transitive dependency changes, most notably, Google Guava is bundled and shaded by the driver. Check out the DataStax Java Driver for Apache Cassandra 4 Upgrade Guide for details on the Driver-related changes.

Adapt Configuration

DataStax Java Driver 4 将 Cluster 和 Session 对象合并成单个 CqlSession 对象，因此已删除所有与 Cluster 相关的 API。配置已通过移除大多数已移至 DriverConfigLoader（主要基于文件）中的配置项进行了大范围修订。这意味着现在通过其他方式配置了 SocketOptions、AddressTranslator 和更多选项。

DataStax Java Driver 4 merges Cluster and Session objects into a single CqlSession object, therefore, all Cluster-related API was removed. The configuration was revised in large parts by removing most configuration items that were moved into DriverConfigLoader that is mostly file-based. This means that SocketOptions, AddressTranslator and many more options are configured now through other means.

如果你使用基于 XML 的配置，请务必将所有配置文件从 cql`名称空间 (`http://www.springframework.org/schema/cql [role="bare"]https://www.springframework.org/schema/cql/spring-cql.xsd) 迁移到 cassandra`名称空间 (`http://www.springframework.org/schema/data/cassandra [role="bare"]https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd)。

If you’re using XML-based configuration, make sure to migrate all configuration files from the cql namespace (http://www.springframework.org/schema/cql [role="bare"]https://www.springframework.org/schema/cql/spring-cql.xsd) to the cassandra namespace (http://www.springframework.org/schema/data/cassandra [role="bare"]https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd).

为了反映配置构建器的变更，ClusterBuilderConfigurer 已重命名为 SessionBuilderConfigurer，现在接受 CqlSessionBuilder 而不是 Cluster.Builder。请务必在配置中提供本地数据中心，因为它对于正确配置负载平衡是必需的。

To reflect the change in configuration builders, ClusterBuilderConfigurer was renamed to SessionBuilderConfigurer accepting now CqlSessionBuilder instead of the Cluster.Builder. Make sure to also provide the local data center in your configuration as it is required to properly configure load balancing.

Connectivity

Cluster（cassandra:cluster）和 Session（cassandra:session）的配置元素已合并到一个 CqlSession（cassandra:session）元素中，该元素配置了键空间和端点。

The configuration elements for Cluster (cassandra:cluster) and Session (cassandra:session) were merged into a single CqlSession (cassandra:session) element that configures both, the keyspace and endpoints.

在升级时，架构支持已移至新的命名空间元素：cassandra:session-factory，该元素提供了 SessionFactory Bean。

With the upgrade, schema support was moved to a new namespace element: cassandra:session-factory that provides a SessionFactory bean.

Example 1. Cluster, Session and Schema Configuration in version 2:
<cassandra:cluster contact-points="localhost" port="9042">
  <cassandra:keyspace action="CREATE_DROP" name="mykeyspace" />
</cassandra:cluster>

<cassandra:session keyspace-name="mykeyspace" schema-action="CREATE">
  <cassandra:startup-cql>CREATE TABLE …</cassandra:startup-cql>
</cassandra:session>
Example 2. Session and Schema Configuration in version 3:
<cassandra:session contact-points="localhost" port="9042" keyspace="mykeyspace" local-datacenter="datacenter1">
  <cassandra:keyspace action="CREATE_DROP" name="mykeyspace" />
</cassandra:session>

<cassandra:session-factory schema-action="CREATE">
  <cassandra:script location="classpath:/schema.cql"/>
</cassandra:session-factory>

在使用 XML 命名空间配置时，Spring Data Cassandra 3.0 不再注册默认映射上下文、上下文和模板 API bean。应在应用程序或 Spring Boot 级别上应用默认值。

Spring Data Cassandra 3.0 no longer registers default Mapping Context, Context and Template API beans when using XML namespace configuration. The defaulting should be applied on application or Spring Boot level.

Template API

如果你应用程序主要与映射实体或原始 Java 类型进行交互，那么用于 Apache Cassandra 的 Spring Data 封装了大多数随 Driver 升级而来的更改，如 Template API 和存储库支持。

Spring Data for Apache Cassandra encapsulates most of the changes that come with the driver upgrade as the Template API and repository support if your application mainly interacts with mapped entities or primitive Java types.

我们通常建议使用 SessionFactory 创建 CqlTemplate 和 CassandraTemplate 对象，因为工厂用法允许同步以创建架构，并在处理多个数据库时引入了一定程度的灵活性。

We generally recommend to create CqlTemplate and CassandraTemplate objects by using SessionFactory as the factory usage allows synchronization for schema creation and introduces a level of flexibility when working with multiple databases.

Example 3. Template API configuration in version 2:
<cql:template session-ref="…" />

<cassandra:template session-ref="…" cassandra-converter-ref="…"/>
Example 4. Template API configuration in version 3:
<cassandra:session-factory />

<cassandra:cql-template session-factory-ref="…" />

<cassandra:template session-factory-ref="…" cassandra-converter-ref="…"/>

在所有使用 DataStax Driver API 的地方都必须调整你的代码。典型情况包括：

You will have to adapt your code in all places, where you use DataStax driver API directly. Typical cases include:

  • Implementations of ResultSetExtractor

  • Implementations of RowCallbackHandler

  • Implementations of RowMapper

  • Implementations of PreparedStatementCreator including async and reactive variants

  • Calls to CqlTemplate.queryForResultSet(…)

  • Calling methods that accept Statement

Changes in AsyncCqlTemplate

DataStax Driver 4 已更改了异步运行的查询的结果类型。为了反映这些更改，你需要调整你的代码，以提供：

DataStax driver 4 has changed the result type of queries that are run asynchronously. To reflect these changes, you need to adapt your code that provides:

  • Implementations of AsyncSessionCallback

  • Implementations of AsyncPreparedStatementCreator

结果集提取需要一个新接口，用于 DataStax 的 AsyncResultSet。现 AsyncCqlTemplate 在它以前使用 ResultSetExtractor 的位置使用 AsyncResultSetExtractor。请注意，AsyncResultSetExtractor.extractData(…) 返回 Future 而不是标量对象，因此代码迁移为提取器使用完全非阻塞代码提供了可能性。

Result set extraction requires a new interface for DataStax' AsyncResultSet. AsyncCqlTemplate now uses AsyncResultSetExtractor in places where it used previously ResultSetExtractor. Note that AsyncResultSetExtractor.extractData(…) returns a Future instead of a scalar object so a migration of code comes with the possibility to use fully non-blocking code in the extractor.

Data model migrations

如果使用以下功能，则你的数据模型可能需要更新：

Your data model may require updates if you use the following features:

  • @CassandraType

  • forceQuote in @Table, @Column, @PrimaryKeyColumn, @PrimaryKey and @UserDefinedType

  • Properties using java.lang.Date

  • Properties using UDTValue or TupleValue

@CassandraType

DataStax Driver 4 不再使用 Name 枚举来描述 Cassandra 类型。我们决定使用 CassandraType.Name 重新引入枚举。请务必更新你的导入以使用新引入的替换类型。

DataStax driver 4 no longer ships with a Name enumeration to describe the Cassandra type. We decided to re-introduce the enumeration with CassandraType.Name. Make sure to update your imports to use the newly introduced replacement type.

Force Quote

此标志现已弃用，我们建议不再使用。针对 Apache Cassandra 的 Spring Data 在内部使用驱动程序的 CqlIdentifier，它确保在需要时加上引号。

This flag is now deprecated, and we recommend not to use it any longer. Spring Data for Apache Cassandra internally uses the driver’s CqlIdentifier that ensures quoting where it’s required.

Property Types

DataStax 驱动程序 4 不再使用 java.lang.Date。请升级你的数据模型，使用 java.time.LocalDateTime。请还将原始 UDT 和元祖类型迁移到新的驱动程序类型 UdtValue 和 TupleValue。

DataStax driver 4 no longer uses java.lang.Date. Please upgrade your data model to use java.time.LocalDateTime. Please also migrate raw UDT and tuple types to the new driver types UdtValue respective TupleValue.

Other changes

  • Driver’s ConsistencyLevel constant class was removed and reintroduced as DefaultConsistencyLevel. @Consistency was adapted to DefaultConsistencyLevel.

  • RetryPolicy on QueryOptions and …CqlTemplate types was removed without replacement.

  • Drivers’s PagingState type was removed. Paging state now uses ByteBuffer.

  • SimpleUserTypeResolver accepts CqlSession instead of Cluster.

  • SimpleTupleTypeFactory was migrated to enum. SimpleTupleTypeFactory.INSTANCE no longer requires a Cluster/CqlSession context.

  • Introduction of StatementBuilder to functionally build statements as the QueryBuilder API uses immutable statement types.

  • Session bean renamed from session to cassandraSession and SessionFactory bean renamed from sessionFactory to cassandraSessionFactory.

  • ReactiveSession bean renamed from reactiveSession to reactiveCassandraSession and ReactiveSessionFactory bean renamed from reactiveSessionFactory to reactiveCassandraSessionFactory.

  • ReactiveSessionFactory.getSession() now returns a Mono<ReactiveSession>. Previously it returned just ReactiveSession.

  • Data type resolution was moved into ColumnTypeResolver so all DataType-related methods were moved from CassandraPersistentEntity/CassandraPersistentProperty into ColumnTypeResolver (affected methods are MappingContext.getDataType(…), CassandraPersistentProperty.getDataType(), CassandraPersistentEntity.getUserType(), and CassandraPersistentEntity.getTupleType()).

  • Schema creation was moved from MappingContext to SchemaFactory (affected methods are CassandraMappingContext.getCreateTableSpecificationFor(…), CassandraMappingContext.getCreateIndexSpecificationsFor(…), and CassandraMappingContext.getCreateUserTypeSpecificationFor(…)).

Deprecations

  • CassandraCqlSessionFactoryBean, use CqlSessionFactoryBean instead.

  • KeyspaceIdentifier and CqlIdentifier, use com.datastax.oss.driver.api.core.CqlIdentifier instead.

  • CassandraSessionFactoryBean, use CqlSessionFactoryBean instead.

  • AbstractCqlTemplateConfiguration, use AbstractSessionConfiguration instead.

  • AbstractSessionConfiguration.getClusterName(), use AbstractSessionConfiguration.getSessionName() instead.

  • CodecRegistryTupleTypeFactory, use SimpleTupleTypeFactory instead.

  • Spring Data’s CqlIdentifier, use the driver CqlIdentifier instead.

  • forceQuote attributes as quoting is no longer required. CqlIdentifier properly escapes reserved keywords and takes care of case-sensitivity.

  • fetchSize on QueryOptions and …CqlTemplate types was deprecated, use pageSize instead

  • CassandraMappingContext.setUserTypeResolver(…), CassandraMappingContext.setCodecRegistry(…), and CassandraMappingContext.setCustomConversions(…): Configure these properties on CassandraConverter.

  • TupleTypeFactory and CassandraMappingContext.setTupleTypeFactory(…): TupleTypeFactory is no longer used as the Cassandra driver ships with a DataTypes.tupleOf(…) factory method.

  • Schema creation via CqlSessionFactoryBean (cassandra:session) is deprecated. Keyspace creation via CqlSessionFactoryBean (cassandra:session) is not affected.

Removals

Configuration API

  • PoolingOptionsFactoryBean

  • SocketOptionsFactoryBean

  • CassandraClusterFactoryBean

  • CassandraClusterParser

  • CassandraCqlClusterFactoryBean

  • CassandraCqlClusterParser

  • CassandraCqlSessionParser

  • AbstractClusterConfiguration

  • ClusterBuilderConfigurer (use SessionBuilderConfigurer instead

Utilities

  • GuavaListenableFutureAdapter

  • QueryOptions and WriteOptions constructor taking ConsistencyLevel and RetryPolicy arguments. Use the builder in conjunction of execution profiles as replacement.

  • CassandraAccessor.setRetryPolicy(…) and ReactiveCqlTemplate.setRetryPolicy(…) methods. Use execution profiles as replacement.

Namespace support

Additions

Configuration API

  • CqlSessionFactoryBean

  • InitializeKeyspaceBeanDefinitionParser

  • SessionFactoryFactoryBean including schema creation via KeyspacePopulator

  • KeyspacePopulator and SessionFactoryInitializer to initialize a keyspace

Namespace support

  • cassandra:cluster (endpoint properties merged to cassandra:session)

  • cassandra:initialize-keyspace namespace support

  • cassandra:session-factory with cassandra:script support