capella-quickstart

name	capella-quickstart
summary	Get started with Couchbase Capella (DBaaS) — sign up for free tier, create a cluster, allowlist your IP, create database credentials, get the connection string, load travel-sample, run first query in the Query Workbench
description	Get started with Couchbase Capella (DBaaS) — sign up for free tier, create a cluster, allowlist your IP, create database credentials, get the connection string, load travel-sample, run first query in the Query Workbench
metadata	{"last_verified":"2026-05","handoff":[{"condition":"user wants to run Couchbase locally instead","skill":"local-dev-setup"},{"condition":"user wants to connect from application code","type":"variant","skill":"server-connection-python"},{"condition":"user asks about SQL++ queries","skill":"sqlpp-language"},{"condition":"user asks about App Services or managed mobile sync on Capella","skill":"capella"}]}

Couchbase Capella Quickstart

Scope: first-time cluster setup — sign up, create cluster, allowlist IP, create credentials, run first query. For connecting an existing cluster to application code or Terraform provisioning, use capella instead.

Capella is the hosted version of Couchbase. The free tier gives you a shared cluster with no credit card required.

Step 1 — Sign up

Go to https://cloud.couchbase.com and create an account. The free tier provisions a shared cluster automatically.

Step 2 — Load travel-sample

In the Capella UI:

1. Click your cluster → Data Tools → Buckets
2. Click Import Sample Data → select travel-sample → Import

Or skip this and create your own bucket:

1. Data Tools → Buckets → Create Bucket
2. Name it, leave defaults, click Create

Step 3 — Allowlist your IP

Capella blocks all connections by default.

1. Cluster → Connect → Allowed IP Addresses
2. Click Add Allowed IP
3. Enter your IP (or click Add Current IP Address)
4. For development only: use 0.0.0.0/0 to allow all IPs

# Find your public IP
curl -s https://api.ipify.org

Step 4 — Create database credentials

1. Cluster → Connect → Database Access
2. Click Create Database Credentials
3. Set a username and password
4. Grant Read/Write on All Buckets (or specific buckets)
5. Save the credentials — the password is shown only once

Step 5 — Get the connection string

1. Cluster → Connect
2. Copy the connection string — it looks like:

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

   Note: couchbases:// (with an s) — TLS is required on Capella.

Step 6 — First query in the Workbench

1. Cluster → Data Tools → Query
2. Run:

SELECT name, country
FROM `travel-sample`.inventory.airline
WHERE country = "United States"
LIMIT 5;

Step 7 — Connect from code

Use couchbases:// (TLS) and apply the wan_development profile for cloud connections:

// Node.js
const couchbase = require('couchbase');

const cluster = await couchbase.connect(
  'couchbases://cb.<cluster-id>.cloud.couchbase.com',
  {
    username: 'your-db-user',
    password: 'your-db-password',
    configProfile: 'wanDevelopment',
  }
);
const bucket     = cluster.bucket('travel-sample');
const collection = bucket.scope('inventory').collection('airline');

const result = await collection.get('airline_10');
console.log(result.content);

# Python
from datetime import timedelta
from couchbase.cluster import Cluster
from couchbase.options import ClusterOptions
from couchbase.auth import PasswordAuthenticator

cluster = Cluster(
    'couchbases://cb.<cluster-id>.cloud.couchbase.com',
    ClusterOptions(PasswordAuthenticator('your-db-user', 'your-db-password'))
)
cluster.wait_until_ready(timedelta(seconds=10))

Common issues

Connection times out:

• Check your IP is in the allowlist (Step 3)
• Verify you're using couchbases:// not couchbase://
• Apply the wan_development / wanDevelopment config profile — it increases timeouts for cloud latency

Authentication fails:

• Use the database credentials (Step 4), not your Capella login email/password
• Passwords are case-sensitive

"Bucket not found":

• Bucket names are case-sensitive
• Verify the bucket exists under Data Tools → Buckets

Free tier limits

Resource	Free tier
Clusters	1 shared cluster
Buckets	Up to 2
Storage	1 GB
Nodes	Shared (multi-tenant)
Expiry	No expiry — stays free