CouchBase

Standalone Crystal client for Couchbase KV and N1QL/SQL++ Query services.

CouchBase currently covers:

1. Couchbase endpoint discovery
2. KV binary protocol with bucket vbucket-count discovery
3. Query HTTP service

Not implemented:

1. Search
2. Analytics
3. Index
4. Eventing
5. Views

Installation

dependencies:
  couchbase:
    github: shardscry/couchbase
    version: ~> 0.0.5

Run shards install, then require "couchbase" in your application.

See release notes for the complete feature set and limitations.

Migrating From CryBase

Replace:

1. crybase dependency with couchbase
2. require "crybase" with require "couchbase"
3. CryBase::CouchBase with CouchBase

Shared helpers now live under CouchBase::Connectivity and CouchBase::Interfaces
the version is CouchBase::VERSION.

Index

1. Glossary
2. Installation
3. Quick start
4. Key Value service
5. Query service

Small Use Cases

require "couchbase"

kv = CouchBase::KV::Client.from_string(
  "couchbase://Administrator:password@127.0.0.1/commerce",
)

kv.scope = "ecommerce_shop"
users = kv.collection("users")
users.set("some-uuid-here", %({"name":"Ada"}))
puts String.new(users.get("some-uuid-here"))

admins = kv.collection("admins")
admins.set("some-uuid-here", %({"name":"Grace"}))

require "couchbase"

client = CouchBase::Query::Client.from_string(
  "couchbase://Administrator:password@127.0.0.1/commerce",
)

client.scope = "ecommerce_shop"

rows = client.query(
  "SELECT META(u).id AS doc_key, u.name FROM users AS u LIMIT 5",
)

Examples

Each folder in examples/ is a standalone Crystal application with its own shard.yml, locked dependencies, README, and local models. Copy any folder elsewhere and run shards install followed by shards build. Each example's README includes its run command. Examples use the published CouchBase shard and require no shared example files.

For a local Couchbase server and the HTTP API:

cd examples/kemal_api
docker compose up -d --wait couchbase
docker compose run --rm couchbase-init
shards install
crystal run setup.cr
crystal run src/main.cr

The API listens at http://127.0.0.1:3000. See its README for endpoint examples, configuration, and spec commands. The same database supports the other examples:

cd ../query_basics
shards install
crystal run example.cr

CLI examples accept COUCHBASE_URL (default couchbase://Administrator:password@127.0.0.1/commerce), COUCHBASE_SCOPE, and COUCHBASE_COLLECTION (both _default). Query examples also accept COUCHBASE_QUERY_URL for a separate Query endpoint. They create their own data, clean up their UUID keys, and do not require a sample dataset.