capella

name	capella
summary	Couchbase Capella (DBaaS) — connect to Capella clusters, manage database credentials, provision infrastructure with Terraform, and understand Capella-specific differences from self-managed Couchbase Server
description	Couchbase Capella (DBaaS) — connect to Capella clusters, manage database credentials, provision infrastructure with Terraform, and understand Capella-specific differences from self-managed Couchbase Server
compatibility	Capella — all tiers (Free, Developer Pro, Enterprise)
metadata	{"last_verified":"2026-05","handoff":[{"condition":"user wants language-specific connection code","type":"variant","skill":"server-connection-python"},{"condition":"user asks about SQL++ queries","type":"variant","skill":"server-querying-python"},{"condition":"user asks about slow queries or index recommendations","skill":"server-query-optimizer"},{"condition":"user asks about cross-datacenter replication or cluster-to-cluster sync","skill":"xdcr"},{"condition":"user asks about mobile sync or Couchbase Lite replication","type":"variant","skill":"mobile-sync-android"},{"condition":"user asks about App Services or managed mobile sync on Capella","skill":"app-services"}]}

Couchbase Capella

Scope: connecting an existing Capella cluster to application code, managing database credentials, Terraform provisioning, and Capella-specific operational differences. For first-time cluster setup (sign up, allowlist IP, first query), use capella-quickstart instead.

Capella is the fully-managed Couchbase DBaaS. It runs on AWS, GCP, or Azure. The data model, SQL++, and SDK APIs are identical to self-managed Couchbase Server — the differences are in connection, credentials, and operations.

Key Differences from Self-Managed

Area	Self-Managed	Capella
Connection scheme	couchbase:// or couchbases://	Always couchbases:// (TLS required)
Credentials	Local RBAC users	Database Access Credentials (separate from UI login)
Admin REST API	http://localhost:8091	Capella Management API (https://cloudapi.cloud.couchbase.com)
Index management	CREATE INDEX via cbq	CREATE INDEX via SDK/cbq — same syntax
Eventing	Self-managed only	Not available on Capella Operational
Analytics	Available	Available
Search	Available	Available
Shell access	SSH to nodes	No SSH — use SDK, cbq, or Capella UI
Backup	Manual or scheduled	Automated managed backups

---

Connecting

Get the connection string

In the Capella UI: Cluster → Connect → Connection String. It looks like: cb.<cluster-id>.cloud.couchbase.com

The SDK connection string uses the couchbases:// scheme (TLS required — note the trailing s):

couchbases://cb.<cluster-id>.cloud.couchbase.com

Key differences from self-managed Couchbase Server:

• Always use couchbases:// (TLS). Plain couchbase:// will be rejected.
• Authenticate with Database Access Credentials (created in Capella UI), not your Capella login.
• Port 8091 is not exposed. All management is via the Capella Management API.

For language-specific connection code (singleton pattern, timeouts, error handling), use the server-connection-* skill for your language — the only Capella-specific change is the couchbases:// connection string above.

---

Database Access Credentials

Capella uses Database Access Credentials for SDK/application access — separate from your Capella UI login.

Create in UI: Cluster → Settings → Database Access → Create Credentials

Or via Capella Management API:

# Create a database user with read/write on a bucket
curl -X POST "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORG_ID/projects/$PROJECT_ID/clusters/$CLUSTER_ID/users" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "app-service-user",
    "password": var.cb_user_password,
    "access": [{
      "privileges": ["data_reader", "data_writer", "query_select", "query_insert", "query_update", "query_delete"],
      "resources": { "buckets": [{ "name": "my-bucket", "scopes": [{ "name": "*" }] }] }
    }]
  }'

Credential rules:

• Database credentials are cluster-scoped — one set per cluster, not per bucket
• Capella credentials use the same RBAC role names as self-managed Server
• Rotate credentials in the UI or via API; update all SDK connection configs

---

Allowed IP Addresses

Capella requires explicit IP allowlisting. Add your application server's IP:

curl -X POST "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORG_ID/projects/$PROJECT_ID/clusters/$CLUSTER_ID/allowedcidrs" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cidr": "203.0.113.42/32", "comment": "app-server-prod"}'

For development, 0.0.0.0/0 allows all IPs — never use in production.

---

App Services (Mobile Sync)

Capella App Services is the managed Sync Gateway for Couchbase Lite mobile/edge sync. For full configuration — App Endpoint setup, Sync Function, user management, and mobile SDK replication code — see the app-services skill.

The App Services endpoint URL format is:

wss://<app-service-id>.apps.cloud.couchbase.com/<endpoint-name>

---

Capella Management API

All cluster operations use the REST API (no SSH, no admin UI REST on port 8091).

# Get API token — generate in Capella UI: Organization → API Keys
export CAPELLA_API_TOKEN="your-api-key-token"
export ORG_ID="your-org-id"
export PROJECT_ID="your-project-id"
export CLUSTER_ID="your-cluster-id"

# List clusters
curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORG_ID/projects/$PROJECT_ID/clusters" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN"

# Get cluster status
curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORG_ID/projects/$PROJECT_ID/clusters/$CLUSTER_ID" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN"

# Create a bucket
curl -X POST "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORG_ID/projects/$PROJECT_ID/clusters/$CLUSTER_ID/buckets" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-bucket", "type": "couchbase", "storageBackend": "couchstore", "memoryAllocationInMb": 256, "replicas": 1}'

---

Terraform / Infrastructure as Code

The official Terraform provider (couchbasecloud/capella) manages clusters, buckets, scopes, collections, database users, allowed CIDRs, and App Services as code.

terraform {
  required_providers {
    capella = {
      source  = "couchbasecloud/capella"
      version = "~> 1.3"
    }
  }
}

provider "capella" {
  authentication_token = var.capella_api_token
}

resource "capella_cluster" "prod" {
  organization_id = var.organization_id
  project_id      = var.project_id
  name            = "prod-cluster"

  cloud_provider = { type = "aws", region = "us-east-1", cidr = "10.0.0.0/23" }

  service_groups = [{
    node         = { compute = { cpu = 4, ram = 16 }, disk = { storage = 50, type = "gp3", iops = 3000 } }
    num_of_nodes = 3
    services     = ["data", "index", "query"]
  }]

  availability = { type = "multi" }
  support      = { plan = "developer pro", timezone = "PT" }
}

See references/terraform.md for full examples: bucket, scope, collection, database credentials, allowed CIDRs, App Services, data sources, and workflow commands.

---

Troubleshooting

Problem	Cause	Fix
AUTHENTICATION_ERROR	Wrong credentials or user doesn't exist	Verify Database Access Credentials in Capella UI
UnambiguousTimeoutException on connect	IP not allowlisted	Add your IP in Cluster → Settings → Allowed IP Addresses
TLS handshake failure	Using couchbase:// instead of couchbases://	Always use couchbases:// for Capella
BUCKET_NOT_FOUND	Bucket name wrong or not created	Check bucket name in Capella UI
App Services sync not starting	Wrong endpoint URL format	URL must be wss:// not https://; include endpoint name in path