|
此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Data Cassandra 4.5.2！ |
架构管理
Apache Cassandra 是一个数据存储，在任何数据交互之前都需要架构定义。 Spring Data for Apache Cassandra 可以支持您创建模式。
CQL 规范
CQL 规范是表示 CQL DDL作（例如表创建或键空间删除）的抽象。 规范适用于以下 CQL 对象类型：
-
键空间
-
桌子
-
指数
-
用户定义类型
| Cassandra 的变体可以支持物化视图、用户定义的函数、角色和更多对象类型。 Spring Data for Apache Cassandra 仅提供上述类型的规范。 |
这些可用于通过流畅的接口创建、ALTER 和 DROP CQL 对象。SpecificationBuilder是构建此类规范的入口点。
您可以稍后使用CqlGenerator.toCql(…)轻松地从规范中呈现 CQL。
请参阅以下示例以创建键空间创建、表创建和索引创建规范。
CqlSpecification createKeyspace = SpecificationBuilder.createKeyspace("my_keyspace")
.with(KeyspaceOption.REPLICATION, KeyspaceAttributes.newSimpleReplication())
.with(KeyspaceOption.DURABLE_WRITES, true);
// results in CREATE KEYSPACE my_keyspace WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} AND durable_writes = true
String cql = CqlGenerator.toCql(createKeyspace);CreateTableSpecification createTable = CreateTableSpecification.createTable("my_table")
.partitionKeyColumn("last_name", DataTypes.TEXT)
.partitionKeyColumn("first_name", DataTypes.TEXT)
.column("age", DataTypes.INT);
// results in CREATE TABLE my_table (last_name text, first_name text, age int, PRIMARY KEY(last_name, first_name))
String cql = CqlGenerator.toCql(createTable);CreateIndexSpecification spec = SpecificationBuilder.createIndex()
.tableName("mytable").keys().columnName("column");
// results in CREATE INDEX ON mytable (KEYS(column))
String cql = CqlGenerator.toCql(createTable);您可以将规范与配置 API 一起使用，以定义密钥空间创建和模式作。
键空间和生命周期脚本
首先要开始的是 Cassandra 键空间。
密钥空间是共享相同复制因子和复制策略的表的逻辑分组。
Keyspace 管理位于CqlSession配置，其中具有KeyspaceSpecification以及启动和关闭 CQL 脚本执行。
使用规范声明键空间允许创建和删除键空间。 它从规范派生 CQL，因此您无需自己编写 CQL。 以下示例使用 XML 指定 Cassandra 密钥空间：
@Configuration
public class CreateKeyspaceConfiguration extends AbstractCassandraConfiguration implements BeanClassLoaderAware {
@Override
protected List<CreateKeyspaceSpecification> getKeyspaceCreations() {
CreateKeyspaceSpecification specification = SpecificationBuilder.createKeyspace("my_keyspace")
.with(KeyspaceOption.DURABLE_WRITES, true)
.withNetworkReplication(DataCenterReplication.of("foo", 1), DataCenterReplication.of("bar", 2));
return Arrays.asList(specification);
}
@Override
protected List<DropKeyspaceSpecification> getKeyspaceDrops() {
return Arrays.asList(DropKeyspaceSpecification.dropKeyspace("my_keyspace"));
}
// ...
}<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:cassandra="http://www.springframework.org/schema/data/cassandra"
xsi:schemaLocation="
http://www.springframework.org/schema/data/cassandra
https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd
http://www.springframework.org/schema/beans
https://www.springframework.org/schema/beans/spring-beans.xsd">
<cassandra:session>
<cassandra:keyspace action="CREATE_DROP" durable-writes="true" name="my_keyspace">
<cassandra:replication class="NETWORK_TOPOLOGY_STRATEGY">
<cassandra:data-center name="foo" replication-factor="1" />
<cassandra:data-center name="bar" replication-factor="2" />
</cassandra:replication>
</cassandra:keyspace>
</cassandra:session>
</beans>| 创建密钥空间允许快速引导，而无需外部密钥空间管理。 这对于某些方案可能很有用，但应谨慎使用。 在应用程序关闭时删除键空间会从键空间中的表中删除键空间和所有数据。 |
初始化SessionFactory
这org.springframework.data.cassandra.core.cql.session.initpackage 支持初始化现有的SessionFactory.
有时可能需要初始化在某处服务器上运行的键空间。
初始化键空间
您可以提供在CqlSession初始化和关闭，如以下 Java 配置示例所示：
@Configuration
public class KeyspacePopulatorConfiguration extends AbstractCassandraConfiguration {
@Nullable
@Override
protected KeyspacePopulator keyspacePopulator() {
return new ResourceKeyspacePopulator(new ClassPathResource("com/foo/cql/db-schema.cql"),
new ClassPathResource("com/foo/cql/db-test-data.cql"));
}
@Nullable
@Override
protected KeyspacePopulator keyspaceCleaner() {
return new ResourceKeyspacePopulator(scriptOf("DROP TABLE my_table;"));
}
// ...
}<cassandra:initialize-keyspace session-factory-ref="cassandraSessionFactory">
<cassandra:script location="classpath:com/foo/cql/db-schema.cql"/>
<cassandra:script location="classpath:com/foo/cql/db-test-data.cql"/>
</cassandra:initialize-keyspace>前面的示例针对键空间运行两个指定的脚本。
第一个脚本创建架构，第二个脚本使用测试数据集填充表。
脚本位置也可以是带有通配符的模式，该模式通常用于 Spring 中的资源（例如，classpath*:/com/foo/**/cql/*-data.cql).
如果使用模式，则脚本将按其 URL 或文件名的词法顺序运行。
键空间初始值设定项的默认行为是无条件运行提供的脚本。 这可能并不总是您想要的 — 例如，如果您针对已经包含测试数据的键空间运行脚本。 通过遵循先创建表然后插入数据的常见模式（如前面所示），可以减少意外删除数据的可能性。 如果表已存在，则第一步失败。
但是，为了更好地控制现有数据的创建和删除，XML 命名空间提供了一些附加选项。 第一个是用于打开和关闭初始化的标志。 您可以根据环境进行设置（例如从系统属性或环境 Bean 中提取布尔值）。 以下示例从系统属性获取值：
<cassandra:initialize-keyspace session-factory-ref="cassandraSessionFactory"
enabled="#{systemProperties.INITIALIZE_KEYSPACE}"> (1)
<cassandra:script location="..."/>
</cassandra:initialize-database>| 1 | 获取enabled从名为INITIALIZE_KEYSPACE. |
控制现有数据发生的情况的第二种选择是对故障更加容忍。 为此，您可以控制初始值设定项忽略它从脚本执行的 CQL 中的某些错误的能力，如以下示例所示：
@Configuration
public class KeyspacePopulatorFailureConfiguration extends AbstractCassandraConfiguration {
@Nullable
@Override
protected KeyspacePopulator keyspacePopulator() {
ResourceKeyspacePopulator populator = new ResourceKeyspacePopulator(
new ClassPathResource("com/foo/cql/db-schema.cql"));
populator.setIgnoreFailedDrops(true);
return populator;
}
// ...
}<cassandra:initialize-keyspace session-factory-ref="cassandraSessionFactory" ignore-failures="DROPS">
<cassandra:script location="..."/>
</cassandra:initialize-database>在前面的示例中，我们说我们期望，有时，脚本是针对空键空间运行的，并且有一些DROP因此，脚本中的语句会失败。
所以失败的 CQLDROP语句将被忽略，但其他失败将导致异常。
如果您不想使用 tu 支持，这很有用DROP … IF EXISTS（或类似），但您希望在重新创建之前无条件删除所有测试数据。
在这种情况下，第一个脚本通常是一组DROP语句，后跟一组CREATE语句。
这ignore-failures选项可以设置为NONE（默认值），DROPS（忽略失败的丢弃），或ALL（忽略所有失败）。
如果脚本中根本不存在字符，则每个语句都应用或换行符分隔。
您可以全局或逐个脚本控制该命令，如以下示例所示：;;
@Configuration
public class SessionFactoryInitializerConfiguration extends AbstractCassandraConfiguration {
@Bean
SessionFactoryInitializer sessionFactoryInitializer(SessionFactory sessionFactory) {
SessionFactoryInitializer initializer = new SessionFactoryInitializer();
initializer.setSessionFactory(sessionFactory);
ResourceKeyspacePopulator populator1 = new ResourceKeyspacePopulator();
populator1.setSeparator(";");
populator1.setScripts(new ClassPathResource("com/myapp/cql/db-schema.cql"));
ResourceKeyspacePopulator populator2 = new ResourceKeyspacePopulator();
populator2.setSeparator("@@");
populator2.setScripts(new ClassPathResource("classpath:com/myapp/cql/db-test-data-1.cql"), //
new ClassPathResource("classpath:com/myapp/cql/db-test-data-2.cql"));
initializer.setKeyspacePopulator(new CompositeKeyspacePopulator(populator1, populator2));
return initializer;
}
// ...
}<cassandra:initialize-keyspace session-factory-ref="cassandraSessionFactory" separator="@@">
<cassandra:script location="classpath:com/myapp/cql/db-schema.cql" separator=";"/>
<cassandra:script location="classpath:com/myapp/cql/db-test-data-1.cql"/>
<cassandra:script location="classpath:com/myapp/cql/db-test-data-2.cql"/>
</cassandra:initialize-keyspace>在此示例中，两个test-data脚本使用 as 语句分隔符，并且仅使用@@db-schema.cql使用。
此配置指定默认分隔符为 并覆盖;@@db-schema脚本。
如果您需要比从 XML 命名空间获得的更多的控制，您可以使用SessionFactoryInitializer直接将其定义为应用程序中的组件。
初始化依赖于键空间的其他组件
一大类应用程序（那些直到 Spring 上下文启动后才使用数据库的应用程序）可以使用数据库初始值设定项，而不会再复杂化。 如果您的应用程序不是其中之一，您可能需要阅读本节的其余部分。
数据库初始值设定项依赖于SessionFactory实例并运行其初始化回调中提供的脚本（类似于init-method在 XML Bean 定义中，一个@PostConstruct组件中的方法，或afterPropertiesSet()实现InitializingBean).
如果其他 bean 依赖于相同的数据源并在初始化回调中使用会话工厂，则可能会出现问题，因为数据尚未初始化。
这方面的一个常见示例是缓存，它急切地初始化并在应用程序启动时从数据库加载数据。
要解决此问题，您有两个选择：将缓存初始化策略更改为后续阶段，或者确保首先初始化密钥空间初始值设定项。
如果应用程序在您的控制范围内，则更改缓存初始化策略可能很容易。有关如何实现此作的一些建议包括：
-
使缓存在首次使用时延迟初始化，从而缩短应用程序启动时间。
-
实现缓存或初始化缓存的单独组件
Lifecycle或SmartLifecycle. 当应用程序上下文启动时，您可以自动启动SmartLifecycle通过设置其autoStartup标志，您可以手动启动Lifecycle通过调用ConfigurableApplicationContext.start()在封闭上下文上。 -
使用弹簧
ApplicationEvent或类似的自定义观察者机制来触发缓存初始化。ContextRefreshedEvent总是在上下文准备好使用时发布（在所有 bean 都初始化之后），因此这通常是一个有用的钩子（这就是SmartLifecycle默认情况下有效）。
确保首先初始化键空间初始值设定项也很容易。 关于如何实现这一点的一些建议包括：
-
依赖 Spring 的默认行为
BeanFactory，即 bean 是按注册顺序初始化的。 您可以通过采用一组<import/>XML 配置中的元素，用于对应用程序模块进行排序，并确保首先列出数据库和数据库初始化。 -
将
SessionFactory以及使用它并通过将它们分开来控制其启动顺序的业务组件ApplicationContext实例（例如，父上下文包含SessionFactory，子上下文包含业务组件）。 这种结构在 Spring Web 应用程序中很常见，但可以更普遍地应用。 -
使用表和用户定义类型的模式管理，使用 Spring Data Cassandra 的内置模式生成器初始化密钥空间。
表和用户定义类型
Spring Data for Apache Cassandra 使用适合您的数据模型的映射实体类来访问数据。 您可以使用这些实体类创建 Cassandra 表规范和用户类型定义。
架构创建与CqlSession初始化方式SchemaAction.
支持以下作：
-
SchemaAction.NONE：不创建或删除任何表或类型。 这是默认设置。 -
SchemaAction.CREATE：从标有@Table和类型用@UserDefinedType. 如果尝试创建现有表或类型，则会导致错误。 -
SchemaAction.CREATE_IF_NOT_EXISTS：喜欢SchemaAction.CREATE但与IF NOT EXISTS应用的。 现有表或类型不会导致任何错误，但可能保持过时状态。 -
SchemaAction.RECREATE：删除并重新创建已知使用的现有表和类型。 不会删除未在应用程序中配置的表和类型。 -
SchemaAction.RECREATE_DROP_UNUSED：删除所有表和类型，并仅重新创建已知表和类型。
SchemaAction.RECREATE和SchemaAction.RECREATE_DROP_UNUSED删除您的表并丢失所有数据。RECREATE_DROP_UNUSED还会删除应用程序不知道的表和类型。 |
为模式管理启用表和用户定义类型
基于元数据的映射使用约定和注释解释对象映射。
为了防止将不需要的类创建为表或类型，模式管理仅对标注为@Table以及用@UserDefinedType.
通过扫描类路径来发现实体。
实体扫描需要一个或多个基本包。
使用TupleValue不要提供任何键入详细信息。
因此，您必须使用@CassandraType(type = TUPLE, typeArguments = …)以指定所需的列类型。
以下示例演示如何在 XML 配置中指定实体基础包：
@Configuration
public class EntityBasePackagesConfiguration extends AbstractCassandraConfiguration {
@Override
public String[] getEntityBasePackages() {
return new String[] { "com.foo", "com.bar" };
}
// ...
}<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:cassandra="http://www.springframework.org/schema/data/cassandra"
xsi:schemaLocation="
http://www.springframework.org/schema/data/cassandra
https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd
http://www.springframework.org/schema/beans
https://www.springframework.org/schema/beans/spring-beans.xsd">
<cassandra:mapping entity-base-packages="com.foo,com.bar"/>
</beans>