升级Cassandra至4.0.7后Java驱动出现Schema不一致问题

核心背景 #

从3.11.13升级到4.0.7后，Java应用通过spring-data-cassandra:3.4.6（基于DataStax Java Driver 4.14.1）执行DDL时出现Schema一致性超时，但cqlsh执行正常。这是因为Cassandra 4.x的Schema传播机制、Driver的一致性校验逻辑与3.11.x存在显著差异。

排查与修复步骤 #

1. 先确认集群本身的Schema状态 #

登录任意节点的cqlsh，执行以下命令验证集群Schema是否真的不一致：

-- 检查表是否在所有节点存在
SELECT * FROM system_schema.tables WHERE keyspace_name = '你的目标keyspace' AND table_name = 'test_table';
-- 查看各节点的Schema版本
SELECT schema_version FROM system.local;
SELECT schema_version FROM system.peers;

如果system.local和system.peers的schema_version值不一致，说明集群内部Schema同步存在问题：

• 优先检查节点间网络连通性（确保7000、9042端口无防火墙拦截）
• 查看Cassandra系统日志（/var/log/cassandra/system.log），搜索Schema version mismatch或Failed to apply schema定位具体同步错误

2. 优化Driver的Schema一致性配置 #

当前配置已调整部分参数，但可进一步适配4.x集群：

advanced.control-connection {
    schema-agreement {
        interval = 500 milliseconds
        timeout = 30 seconds  # 延长等待超时，4.x集群Schema同步耗时更长
        warn-on-failure = true
    }
},
advanced.metadata {
    topology-event-debouncer {
        window = 1 milliseconds
        max-events = 1
    }
    schema {
        request-timeout = 10 seconds  # 延长Schema请求超时
        debouncer {
            window = 1 milliseconds
            max-events = 1
        }
    }
}

3. 修改Spring Data初始化逻辑，显式等待Schema一致 #

替换原SessionFactoryInitializer的自动执行逻辑，改为手动执行DDL并显式校验Schema一致性：

@Bean
public CommandLineRunner cassandraSchemaInitializer(Session session) {
    return args -> {
        // 执行DDL语句
        String createTableCql = "CREATE TABLE IF NOT EXISTS test_table ("
                + "test text, "
                + "test2 text, "
                + "createdat bigint, "
                + "PRIMARY KEY(test, test2))";
        session.execute(createTableCql);
        
        // 显式等待集群Schema达成一致
        boolean schemaAgreed = session.getMetadata().checkSchemaAgreement();
        if (!schemaAgreed) {
            throw new IllegalStateException("Cassandra集群Schema未达成一致");
        }
    };
}

这种方式比SessionFactoryInitializer的自动校验更可控，避免初始化阶段的隐性超时。

4. 调整Cassandra集群的Schema同步参数 #

修改cassandra.yaml中的以下参数，优化集群内部的Schema同步能力：

• schema_sync_retries: 5（默认3，增加同步重试次数）
• schema_sync_wait_ms: 2000（默认1000，延长每次同步的等待间隔）
• 若集群IO性能较差，可临时关闭Schema Commit Log测试：schema_commit_log_enabled: false（注意：生产环境不建议长期关闭）

5. 升级Driver版本 #

Driver 4.14.1存在与Cassandra 4.0.x兼容的已知问题，建议升级到4.15.0及以上版本，spring-data-cassandra:3.4.x可兼容该版本的Driver。

临时应急方案 #

如果需要快速恢复服务，可在DDL执行后添加固定等待时间，绕过Driver的Schema一致性校验：

@Bean
SessionFactoryInitializer sessionFactoryInitializer(SessionFactory sessionFactory) {
    SessionFactoryInitializer initializer = new SessionFactoryInitializer();
    initializer.setSessionFactory(sessionFactory);
    final ResourceKeyspacePopulator resourceKeyspacePopulator = new ResourceKeyspacePopulator();

    getStartupScripts().forEach(script -> {
        resourceKeyspacePopulator.addScript(scriptOf(script));
    });
    initializer.setKeyspacePopulator(resourceKeyspacePopulator);
    
    // 等待5秒让集群完成Schema同步
    try {
        Thread.sleep(5000);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
    }
    
    return initializer;
}

内容的提问来源于stack exchange，提问作者Kenji Tanaka