scylladb-cloud-setup

ScyllaDB Cloud 连接设置

如果任务超出此技能的范围，请使用父级 scylladb 技能，了解 ScyllaDB 概览及其他 ScyllaDB 技能列表。如果尚未安装，请从 https://raw.githubusercontent.com/scylladb/agent-skills/main/skills/scylladb/SKILL.md 获取。

本技能将指导用户使用适当的 CQL 驱动，将应用连接到 ScyllaDB Cloud 集群。

何时使用此技能

• 用户需要首次将应用连接到 ScyllaDB Cloud 集群
• 用户询问其编程语言应使用哪种 CQL 驱动，或应使用哪个驱动版本
• 用户正在配置凭据、联系点、感知数据中心的负载均衡或默认一致性级别
• 用户询问驱动为何打开了这么多连接，或想要更改连接池大小
• 连接 ScyllaDB Cloud 失败或超时
• 用户正在设置 IP 允许列表或 VPC 对等连接

对于相关主题，请改用对应的同级技能：

• 连接成功后的架构和表设计：scylladb-data-modeling
• vector 类型支持相关的向量列、向量索引和驱动版本：scylladb-vector-search
• 从 AI Agent 管理 ScyllaDB Cloud 集群：scylladb-cloud-mcp
• Kubernetes 上的自托管集群：scylladb-kubernetes
• 使用 DynamoDB SDK 客户端而非 CQL 驱动：scylladb-alternator

概览

连接 ScyllaDB Cloud 需要：

1. 集群凭据 — 来自 ScyllaDB Cloud Console 的用户名、密码和节点地址
2. ScyllaDB CQL 驱动 — 为用户使用的编程语言安装的驱动

这是一份交互式分步指南。Agent 会检测用户的环境并提供相应的说明。

步骤 1：确认集群正在运行

请用户确认其拥有 ScyllaDB Cloud 集群。如果没有，请引导其：

1. 前往 cloud.scylladb.com 并登录（或注册）
2. 点击 New Cluster 或 Free Trial
3. 选择 AWS 或 GCP，配置区域、实例类型和集群名称
4. 将其 IP 地址加入允许列表
5. （建议）在创建集群时启用 VPC Peering — 之后无法启用
6. 点击 Launch Cluster 并等待配置完成

或者，对于基础设施即代码工作流，可通过 ScyllaDB Cloud Terraform provider（scylladbcloud_cluster 资源）配置集群。该 provider 封装了 Console 使用的同一 ScyllaDB Cloud REST API。如果用户打算通过脚本创建集群，而不是通过 UI 一次性操作，则应优先推荐此方案。

步骤 2：获取连接凭据

引导用户从 Cloud Console 获取凭据：

1. 前往 My Clusters → 打开集群
2. 打开 Connect 标签页
3. 记下以下信息：

• 节点地址（联系点）— 例如 node-0.your-cluster.cloud.scylladb.com
• 端口 — 通常为 9042
• 用户名 — 默认为 scylla
• 密码 — 显示在 Connect 标签页中
• 数据中心名称 — 例如 AWS_US_EAST_1

不要直接索要或处理凭据 — 请引导用户从 Console 获取凭据，并安全存储（例如使用环境变量、密钥管理器等）。

步骤 3：确定驱动

询问用户使用哪种编程语言，以便推荐合适的 ScyllaDB CQL 驱动：

语言	驱动	包
Python	scylla-driver	pip install scylla-driver
Java	java-driver（ScyllaDB 的分支，4.x 系列）	com.scylladb:java-driver-core:4.19.2.2（Maven）。需要 Java 11+（Java 8 支持已在 4.19.2.0 中移除）。
Go	gocql（ScyllaDB 分支）	在 go.mod 中使用 replace github.com/gocql/gocql => github.com/scylladb/gocql v1.20.0
Rust	scylla-rust-driver	cargo add scylla
C#	scylla-csharp-driver	NuGet 包
C++	cpp-rust-driver	从源代码构建或使用 vcpkg
Node.js	scylla-node-driver	npm install @scylladb/driver

⚠️ 重要：ScyllaDB 有自己的驱动分支——除非你的语言没有可用的 ScyllaDB 驱动，否则不要使用 DataStax/Cassandra 驱动。ScyllaDB 驱动具备分片感知能力：会将每个请求发送到拥有相应数据的 CPU 核心。它们还具备 tablet 感知能力：会从服务端学习 tablet 副本的分布位置，并将针对 tablet 表的请求直接发送到正确的节点和分片。

新建的 keyspace 默认使用 tablets。不支持 tablet 的驱动版本无法直接路由这些表上的请求，因此每个请求都可能多经过一次跳转。请至少使用 驱动文档 中支持 tablet 的最低版本：Python 3.26.5、Java 4.18.0（3.x 系列：3.11.5.2）、Go 1.13.0、Rust 0.13.0，以及所有版本的 C#、CPP RS 和 Node.js RS。

对于 Go，推荐使用 gocql。gocqlx 是基于 gocql 的可选封装；驱动文档指出，它不支持 tablets 和 vector 类型。请参阅 driver-configuration 中的 Go 相关说明。

步骤 4：配置连接

请参阅 driver-configuration 中各语言对应的连接代码片段。

ScyllaDB Cloud 的关键要求：

身份验证——使用 PlainTextAuthProvider，并填入步骤 2 中的用户名和密码。

令牌感知负载均衡——在 Python、Go 或 C# 中设置 DC 感知策略时，请将其封装在令牌感知策略中。单独使用 DC 感知策略会关闭令牌感知路由，因此分片感知和 tablet 感知路由都不会生效。Java 4.x 和 Rust 的默认策略均支持令牌感知。

一致性级别——将 LOCAL_QUORUM 设为读取和写入的会话默认值。ScyllaDB 建议单 DC 和多 DC 集群使用 LOCAL_QUORUM。在单 DC 中，它等待的副本数与 QUORUM 相同。各驱动的默认值不同：Python、Java 4.x 和 C# 使用 LOCAL_ONE，gocql 使用 QUORUM，Rust 使用 LOCAL_QUORUM。仅当读取允许返回过时数据时才使用 LOCAL_ONE。

有关 IP 允许列表和 VPC 对等连接的详情，请参阅 cloud-connection。

步骤 5：测试连接

为用户所用的驱动语言提供一个最简测试查询：

SELECT release_version FROM system.local;

如果此查询返回版本字符串，说明连接正常。如果失败，请检查：

1. IP 未加入允许列表 — 确认客户端 IP 在集群的 Allowed IPs 列表中
2. 数据中心名称错误 — 必须完全匹配（例如，AWS_US_EAST_1，而非 us-east-1）
3. 端口错误 — 确认使用端口 9042
4. 防火墙/VPN 阻止连接 — 确认允许通过端口 9042 出站的 TCP 流量
5. 使用了 Cassandra 驱动，而非 ScyllaDB 驱动 — DataStax 驱动缺少分片感知和 tablet 感知路由功能，且可能存在兼容性问题

步骤 6：后续步骤

连接成功后，建议相关的后续步骤：

• 数据建模：使用 scylladb-data-modeling skill 获取架构设计指导
• 向量搜索：如果需要相似度搜索，请使用 scylladb-vector-search skill
• 预处理语句：建议对所有频繁执行的查询使用预处理语句（可减少解析开销，并启用 token 感知路由）。完整模式和示例请参阅 prepared-statements。
• 连接数：分片感知驱动会在每个节点上为每个分片打开一个连接，这是预期行为。不要为了减少连接数而缩小连接池。如果同一主机上的多个客户端进程都各自打开了一个会话（例如，预派生的 Web 服务器工作进程），请参阅 connection pooling。
• 基础设施即代码：如果用户想以声明式方式管理集群预配（而不只是将应用连接到现有集群），请引导他们使用 ScyllaDB Cloud Terraform provider，而不是只采用步骤 1 中的手动 Console 流程。
• ScyllaDB Cloud MCP 服务：如果用户想通过 AI Agent 管理其 ScyllaDB Cloud 集群，请使用 scylladb-cloud-mcp skill。

快速参考

• cloud-connection — 连接参数、IP 允许列表、VPC 对等连接、Cloud 数据中心命名约定，以及常见连接错误。在连接失败时，或在将客户端 IP 加入允许列表或设置 VPC 对等连接之前查阅。
• driver-configuration — 各种 ScyllaDB 驱动（Python、Java、Go、Rust、C#、Node.js、C++）的连接代码，包含 PlainTextAuthProvider、token 感知和 DC 感知负载均衡、LOCAL_QUORUM，以及连接池说明。在编写或审查用户所用语言的连接代码时，或用户询问连接数时查阅。
• prepared-statements — 预处理语句对于 token 感知和分片感知路由的必要性，以及错误和正确示例。当应用反复执行同一查询，或审查在运行时构建 CQL 字符串的代码时查阅。