scylladb-cloud-setup

name	scylladb-cloud-setup
description	Guide users through connecting to a ScyllaDB Cloud cluster. Use this skill when a user needs to connect to ScyllaDB Cloud, configure driver credentials, or troubleshoot connection issues. Triggers on "connect to ScyllaDB Cloud", "ScyllaDB connection", "ScyllaDB driver setup", "CQL connection", "DC-aware load balancing", "ScyllaDB credentials", "connection bundle".

ScyllaDB Cloud Connection Setup

This skill guides users through connecting their application to a ScyllaDB Cloud cluster using the appropriate CQL driver.

Overview

Connecting to ScyllaDB Cloud requires:

1. Cluster credentials — username, password, and node addresses from the ScyllaDB Cloud Console
2. A ScyllaDB CQL driver — installed for the user's programming language
3. DC-aware load balancing policy — required for all ScyllaDB Cloud connections

This is an interactive step-by-step guide. The agent detects the user's environment and provides tailored instructions.

Step 1: Verify the Cluster is Running

Ask the user to confirm they have a ScyllaDB Cloud cluster. If not, direct them to:

1. Go to cloud.scylladb.com and log in (or sign up)
2. Click New Cluster or Free Trial
3. Choose AWS or GCP, configure region, instance type, and cluster name
4. Whitelist their IP address
5. (Recommended) Enable VPC Peering during cluster creation — it cannot be enabled later
6. Click Launch Cluster and wait for provisioning

Step 2: Retrieve Connection Credentials

Guide the user to obtain credentials from the Cloud Console:

1. Go to My Clusters → open the cluster
2. Open the Connect tab
3. Note the following:
   • Node addresses (contact points) — e.g., node-0.your-cluster.cloud.scylladb.com
   • Port — typically 9042
   • Username — default is scylla
   • Password — shown on the Connect tab
   • Datacenter name — e.g., AWS_US_EAST_1 (required for DC-aware load balancing)

Do not ask for or handle credentials directly — guide the user to retrieve them from the Console and store them securely (environment variables, secrets manager, etc.).

Step 3: Determine the Driver

Ask the user which programming language they are using so you can recommend the correct ScyllaDB CQL driver:

Language	Driver	Package
Python	scylla-driver	pip install scylla-driver
Java	java-driver (4.x recommended)	Maven/Gradle dependency
Go	gocql + gocqlx	go get github.com/scylladb/gocql
Rust	scylla-rust-driver	cargo add scylla
C#	scylla-csharp-driver	NuGet package
C++	cpp-rust-driver	Build from source or vcpkg
Node.js	scylla-node-driver	npm install scylladb-driver-alpha

⚠️ Important: ScyllaDB has its own driver forks — do not use the DataStax/Cassandra drivers - unless there's no ScyllaDB driver available for your language. ScyllaDB drivers include shard-aware optimizations that route requests directly to the correct CPU core, improving throughput and latency.

Step 4: Configure the Connection

Consult references/driver-configuration.md for per-language connection snippets.

Critical requirements for ScyllaDB Cloud:

1. DC-aware load balancing policy — must be configured with the correct datacenter name. Without it, the driver may attempt to route queries to nodes in the wrong DC or fail to connect entirely.
2. Authentication — PlainTextAuthProvider with the username and password from Step 2.

Consult references/cloud-connection.md for details on IP allowlisting and VPC peering.

Step 5: Test the Connection

Provide a minimal test query for the user's driver language:

SELECT release_version FROM system.local;

If this query returns a version string, the connection is working. If it fails, check:

1. IP not allowlisted — verify the client IP is in the cluster's Allowed IPs list
2. Wrong datacenter name — must match exactly (e.g., AWS_US_EAST_1, not us-east-1)
3. Wrong port — ensure port 9042 is used
4. Firewall/VPN blocking — ensure outbound TCP on port 9042 is allowed
5. Using Cassandra driver instead of ScyllaDB driver — the DataStax drivers lack shard-aware routing and may have compatibility issues

Step 6: Next Steps

Once connected, suggest relevant next steps:

• Data modeling: Use the scylladb-data-modeling skill for schema design guidance
• Vector search: Use the scylladb-vector-search skill if they need similarity search
• Prepared statements: Recommend using prepared statements for all frequently-run queries (reduces parsing overhead, enables token-aware routing)
• Connection pooling: ScyllaDB drivers handle pooling internally with shard-aware connections — typically no manual tuning needed