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 エージェントからの ScyllaDB Cloud クラスターの管理：scylladb-cloud-mcp
• Kubernetes 上のセルフマネージドクラスター：scylladb-kubernetes
• CQL ドライバーの代わりに使用する DynamoDB SDK クライアント：scylladb-alternator

概要

ScyllaDB Cloud に接続するには、次のものが必要です。

1. クラスターの認証情報 — ScyllaDB Cloud Console から取得するユーザー名、パスワード、ノードアドレス
2. ScyllaDB CQL ドライバー — ユーザーのプログラミング言語に対応したものをインストールします

これは、対話形式のステップバイステップガイドです。エージェントがユーザーの環境を検出し、それに合わせた手順を提示します。

ステップ 1：クラスターが実行中であることを確認する

ScyllaDB Cloud クラスターを用意しているか、ユーザーに確認します。用意していない場合は、次の手順を案内してください。

1. cloud.scylladb.com にアクセスしてログインします（またはサインアップします）
2. New Cluster または Free Trial をクリックします
3. AWS または GCP を選択し、リージョン、インスタンスタイプ、クラスター名を設定します
4. IP アドレスを許可リストに登録します
5. （推奨）クラスター作成時に VPC ピアリングを有効にします — 後から有効にすることはできません
6. Launch Cluster をクリックし、プロビジョニングが完了するまで待ちます

また、インフラストラクチャ・アズ・コードのワークフローでは、ScyllaDB Cloud Terraform provider（scylladbcloud_cluster リソース）を使ってクラスターをプロビジョニングできます。このプロバイダーは、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 以降が必要です（4.19.2.0 で Java 8 のサポートは終了しました）。
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 コアに送信します。また、タブレットも認識し、サーバーからタブレットレプリカの配置を学習するため、タブレットを使用するテーブルへのリクエストを正しいノードとシャードに直接送信します。

新しいキースペースでは、デフォルトでタブレットが使用されます。タブレットをサポートしていないバージョンのドライバーでは、これらのテーブルへのリクエストを直接ルーティングできないため、リクエストごとに余分なホップが発生する場合があります。ドライバーのドキュメントに記載されている、タブレットをサポートする最低バージョン以上を使用してください。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 の上に構築されるオプションのラッパーです。ドライバーのドキュメントでは、タブレットと vector 型はサポート対象外とされています。driver-configuration の Go に関する注意事項を参照してください。

ステップ 4：接続を設定する

言語ごとの接続コード例については、driver-configuration を参照してください。

ScyllaDB Cloud の重要な要件：

認証 — ステップ 2 で取得したユーザー名とパスワードを使って PlainTextAuthProvider を設定します。

トークン認識型ロードバランシング — Python、Go、C# で DC 認識ポリシーを設定する場合は、トークン認識型ポリシーでラップしてください。DC 認識ポリシーだけを設定すると、トークン認識型ルーティングが無効になり、シャード認識型およびタブレット認識型のルーティングが適用されません。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 を参照してください。

Step 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. ScyllaDB ドライバーではなく Cassandra ドライバーを使用している — DataStax ドライバーにはシャード対応およびタブレット対応のルーティング機能がなく、互換性の問題が発生する可能性があります

Step 6: 次のステップ

接続したら、関連する次のステップを提案します。

• データモデリング：スキーマ設計のガイダンスには、scylladb-data-modeling スキルを使用します
• ベクトル検索：類似性検索が必要な場合は、scylladb-vector-search スキルを使用します
• プリペアドステートメント：頻繁に実行するすべてのクエリには、プリペアドステートメントの使用を推奨します（解析のオーバーヘッドが減り、トークン対応ルーティングが可能になります）。詳しいパターンと例については、prepared-statements を参照してください。
• 接続数：シャード対応ドライバーは、各ノードのシャードごとに 1 つの接続を開きます。これは想定された動作です。接続数を減らすためにプールサイズを小さくしないでください。1 台のホスト上で多数のクライアントプロセスがそれぞれセッションを開く場合（たとえば、フォーク前に起動する Web サーバーのワーカー）、connection pooling を参照してください。
• Infrastructure as code：既存のクラスターにアプリを接続するだけでなく、クラスターのプロビジョニングを宣言的に管理したい場合は、Step 1 の手動の Console 操作だけでなく、ScyllaDB Cloud Terraform provider を案内してください。
• ScyllaDB Cloud MCP サーバー：AI エージェントを通じて ScyllaDB Cloud クラスターを管理したい場合は、scylladb-cloud-mcp スキルを使用します。

クイックリファレンス

• cloud-connection — 接続パラメーター、IP アドレスの許可リスト登録、VPC ピアリング、Cloud のデータセンター命名規則、一般的な接続エラーについて説明しています。接続に失敗した場合や、クライアントの IP アドレスを許可リストに登録する前、または VPC ピアリングを設定する前に参照してください。
• driver-configuration — PlainTextAuthProvider、トークン対応・データセンター対応のロードバランシング、LOCAL_QUORUM、接続プールに関する注意事項を含む、各 ScyllaDB ドライバー（Python、Java、Go、Rust、C#、Node.js、C++）の接続コードです。ユーザーの言語で接続コードを記述またはレビューするときや、接続数について質問されたときに参照してください。
• prepared-statements — トークン対応およびシャード対応ルーティングにプリペアドステートメントが必要な理由を、誤った例と正しい例を交えて説明しています。アプリケーションが同じクエリを繰り返し実行する場合や、実行時に CQL 文字列を組み立てるコードをレビューするときに参照してください。