Couchbase¶

Couchbase is a distributed NoSQL cloud database that delivers unmatched performance, scalability, and flexibility for building modern applications.

omniload supports Couchbase as a source.

URI format¶

Standard format (without SSL)¶

couchbase://username:password@host

With SSL/TLS enabled¶

couchbase://username:password@host?ssl=true

Including bucket in URI¶

couchbase://username:password@host/bucket
couchbase://username:password@host/bucket?ssl=true

URI parameters:

username: the username to connect to the Couchbase cluster
password: the password for the user
host: the host address of the Couchbase server
bucket: optional bucket name in the URI path
ssl: SSL/TLS connection parameter
- ssl=true: Required for Couchbase Capella (cloud) deployments
- ssl=false or omitted: Use for Couchbase Server (self-hosted/on-premises) deployments

Note

SSL Parameter Usage:

Use ssl=true when connecting to Couchbase Capella (cloud)
Use ssl=false or omit the parameter when connecting to Couchbase Server (self-hosted/on-premises)

The URI structure can be used for connecting to both local/self-hosted Couchbase instances and Couchbase Capella (cloud).

Source table format¶

The --source-table option for Couchbase supports two formats depending on whether the bucket is specified in the URI:

When bucket is NOT in URI¶

bucket.scope.collection

When bucket IS in URI path¶

scope.collection

For default scope and collection, you can use:

bucket._default._default

Using Couchbase as a source¶

Local/self-hosted Couchbase¶

Basic connection without SSL¶

omniload ingest \
  --source-uri "couchbase://admin:password123@localhost" \
  --source-table "mybucket.myscope.mycollection" \
  --dest-uri "duckdb:///output.db" \
  --dest-table "main.couchbase_data"

For Couchbase Capella (Cloud)¶

omniload ingest \
  --source-uri "couchbase://admin:password123@localhost?ssl=true" \
  --source-table "mybucket._default._default" \
  --dest-uri "duckdb:///output.db" \
  --dest-table "main.couchbase_data"

With bucket in URI¶

omniload ingest \
  --source-uri "couchbase://admin:password123@localhost/mybucket" \
  --source-table "myscope.mycollection" \
  --dest-uri "duckdb:///output.db" \
  --dest-table "main.couchbase_data"

Couchbase Capella (Cloud)¶

Important

Couchbase Capella (cloud) requires SSL connections. You must use ?ssl=true in your connection URI and prefix the host with cb.

Tip

You can obtain the connection string for Capella from the SDK connection details in your Couchbase Capella dashboard.

Use the couchbase:// scheme with ssl=true parameter. Note the cb. prefix in the hostname:

omniload ingest \
  --source-uri "couchbase://username:password@cb.xxx.cloud.couchbase.com?ssl=true" \
  --source-table "travel-sample.inventory.airport" \
  --dest-uri "duckdb:///airports.db" \
  --dest-table "main.airports"

With bucket in URI for Couchbase Capella

omniload ingest \
  --source-uri "couchbase://username:password@cb.xxx.cloud.couchbase.com/travel-sample?ssl=true" \
  --source-table "inventory.airport" \
  --dest-uri "duckdb:///airports.db" \
  --dest-table "main.airports"

With URL-encoded password¶

Important

When using omniload CLI, passwords containing special characters (@, :, /, #, ?, etc.) must be URL-encoded in the connection URI.

If your password contains special characters, you need to URL-encode them:

omniload ingest \
  --source-uri "couchbase://admin:MyPass%40123%21@localhost" \
  --source-table "mybucket.myscope.mycollection" \
  --dest-uri "duckdb:///output.db" \
  --dest-table "main.couchbase_data"

This example encodes the password MyPass@123! as MyPass%40123%21.