Couchbase +

Premium Couchbase integration module offering distributed caching and NoSQL document access for BoxLang+ applications.

The bx-couchbase module integrates Couchbase Server with BoxLang, enabling distributed caching, key/value storage, and document access patterns for horizontally scaled applications.

This module is only available to +/++ subscribers only but can be installed in conjunction with the bx-plus Module with a limited tria.

🚀 Features

• High-performance distributed cache provider

• Key/value operations with TTL support

• JSON document storage & retrieval

• Bucket, scope, and collection targeting

• Basic N1QL query execution (conceptual)

• Connection pooling & health pings

📦 Installation

Via CommandBox

box install bx-couchbase

Via BoxLang

install-bx-module bx-couchbase

⚙ Configuration

{
  "couchbase": {
    "connectionString": "couchbase://localhost",
    "username": "Administrator",
    "password": "password",
    "bucket": "default",
    "scope": "_default",
    "collection": "_default",
    "defaultTTLSeconds": 900
  }
}

Environment overrides:

export COUCHBASE_CONNECTION_STRING=couchbase://db.internal
export COUCHBASE_USERNAME=Administrator
export COUCHBASE_PASSWORD=secret

🧪 Basic Usage

cb = moduleService.get( "bx-couchbase" );

// Store document
cb.upsert( key = "user:42", value = { id: 42, name: "Alice", active: true }, ttl = 600 );

// Retrieve
user = cb.get( "user:42" );
writeDump( var = user );

🔍 Query (Conceptual)

results = cb.query( "SELECT name FROM default WHERE active = TRUE LIMIT 10" );
for ( r in results ) {
    writeOutput( r.name & "<br>" );
}

🧰 Cache Provider Integration

Configure Couchbase as a BoxCache provider for distributed caching:

cache = cacheService.getCache( "default" );
cache.put( id = "landing", value = generateLandingHTML(), timeout = 120 );
html = cache.get( "landing" );

🛡 Error Handling

try {
    doc = cb.get( "user:100" );
} catch ( e ) {
    writeLog( text = "Couchbase access failed: " & e.message, type = "error" );
}

🔐 Entitlement

Requires valid BoxLang+ subscription (bx-plus). Entitlement failures provide actionable messaging.

📏 Performance Tips

• Prefer upsert over separate exists + insert flows

• Use TTL for ephemeral data to control memory

• Batch queries where possible

📎 Related Modules

Redis +Plus Core

---

Return to the Modules Overview.