🚀 BoxLang Module: Couchbase

|:------------------------------------------------------:  |
| ⚡︎ B o x L a n g ⚡︎
| Dynamic : Modular : Productive
|:------------------------------------------------------:  |

This module provides enterprise-grade Couchbase cache providers and AI vector memory capabilities for BoxLang runtimes. Store cache data, sessions, and vector embeddings in Couchbase's distributed NoSQL database with built-in vector search support.

Installation

To include the module in your boxlang runtime, follow the instructions for module installation appropriate to your runtime, using bx-couchbase as the module name/slug.

Versions 1.0.0 and above will require a Boxlang+ Subscription. Without subscription, the module will operate within trial mode for 30 days. After this period, the module will be placed in developer mode, which will limit cache host connections only to 127.0.0.1 and localhost.

Bug Reporting

Feature Requests and Bug Reports may be submitted via JIRA.

If you file a bug report, your issue should contain a title, a clear description of the issue, a way to replicate the issue, and any support files that we might need to replicate your issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix for it. All issues that do not contain a way to replicate will not be addressed.

Support Questions

If you have any questions on usage, professional support or just ideas to bounce off the maintainers, please do not create an issue. Leverage our support channels first.

• Ortus Community Discourse: https://community.ortussolutions.com
• Box Slack Team: http://boxteam.ortussolutions.com/
• Professional Support: https://www.ortussolutions.com/services/support

Configuration

boxlang.json configuration

The JSON configuration structure for boxlang for a Couchbase connection would be placed in the caches object in boxlang.json

Couchbase Provider Configuration example

{
	"caches" : {
		"sessions": {
			"provider": "Couchbase",
			"properties": {
				"cacheKeyCaseSensitivity": "false",
				"connectionString": "couchbase://127.0.0.1",
				"username": "Administrator",
				"password": "password",
				"bucket": "default",
				"scope": "myAppName",
				"collection": "sessions",
				"connectTimeout": "10000",
				"kvTimeout": "2500",
				"queryTimeout": "75000"
			}
		}
	}
}

Configuration Properties

Required Properties

• connectionString: The Couchbase connection string (e.g., couchbase://localhost, couchbases://cluster.example.com)
• username: The username for authentication
• password: The password for authentication
• bucket: The name of the Couchbase bucket to use

Optional Properties

• scope: The scope within the bucket (default: _default)
• collection: The collection within the scope (default: _default)
• cacheKeyCaseSensitivity: Whether cache keys are case-sensitive (default: false)
• connectTimeout: Connection timeout in milliseconds (default: 10000)
• kvTimeout: Key-value operation timeout in milliseconds (default: 2500)
• queryTimeout: Query timeout in milliseconds (default: 75000)
• maxConnections: Maximum number of connections (optional)
• enableDnsSrv: Enable DNS SRV lookup (default: true for couchbases://)

Connection String Formats

• Single Node: couchbase://hostname or couchbase://hostname:11210
• Multiple Nodes: couchbase://node1,node2,node3
• Secure Connection: couchbases://hostname (uses TLS)

Example: Cluster Configuration

{
	"caches" : {
		"resources": {
			"provider": "Couchbase",
			"properties": {
				"connectionString": "couchbases://node1.myc cluster.com,node2.mycluster.com,node3.mycluster.com",
				"username": "${COUCHBASE_USERNAME}",
				"password": "${COUCHBASE_PASSWORD}",
				"bucket": "myapp",
				"connectTimeout": "15000",
				"kvTimeout": "3000",
				"cacheKeyCaseSensitivity": "false"
			}
		}
	}
}

Application.bx/Application.cfc configuration

Couchbase Configuration

this.caches[ "sessions" ] = {
	"provider": "Couchbase",
	"properties": {
		"cacheKeyCaseSensitivity": "false",
		"connectionString": "couchbase://127.0.0.1",
		"username": "Administrator",
		"password": "password",
		"bucket": "default",
		"scope": "_default",
		"collection": "_default",
		"connectTimeout": "10000",
		"kvTimeout": "2500",
		"queryTimeout": "75000"
	}
};

Cluster Configuration

this.caches[ "resources" ] = {
	"provider": "Couchbase",
	"properties": {
		"connectionString": "couchbases://node1.mycluster.com,node2.mycluster.com",
		"username": myClusterUsername,
		"password": myClusterPassword,
		"bucket": "myapp",
		"connectTimeout": "15000",
		"kvTimeout": "3000",
		"cacheKeyCaseSensitivity": "false"
	}
};

Settings Summary

Couchbase Provider

connectionString

The Couchbase connection string. Format: couchbase://host or couchbases://host for secure connections. Can include multiple nodes: couchbase://node1,node2,node3

username

The username for authentication with the Couchbase cluster.

password

The password for authentication with the Couchbase cluster.

bucket

The name of the Couchbase bucket to use for cache storage.

scope

The scope within the bucket (default: _default). Scopes provide logical grouping of collections.

collection

The collection within the scope (default: _default). Collections are like tables in a bucket.

cacheKeyCaseSensitivity

Whether cache keys should be case-sensitive (default: false).

Connection Timeouts

• connectTimeout: The time in milliseconds to wait for initial cluster connection (default: 10000)
• kvTimeout: Timeout for key-value operations in milliseconds (default: 2500)
• queryTimeout: Timeout for N1QL query operations in milliseconds (default: 75000)

maxConnections

Maximum number of connections to maintain in the connection pool (optional).

maxConnections

Maximum number of connections to maintain in the connection pool (optional).

Cache Key Case Sensitivity

By default all cache keys are transformed to lowercase to avoid any casing issues. However, if you want case sensitivity, then turn this option on by setting cacheKeyCaseSensitivity to true.

📚 Features

• ⚡ High-Performance Caching: Distributed cache provider with sub-millisecond response times
• 🔍 Vector Search: Built-in AI vector memory with semantic search capabilities
• 🔒 Distributed Locking: Coordinate operations across multiple servers with automatic locks
• 📦 Session Storage: Store application and session scopes in Couchbase
• 🎯 N1QL Queries: Execute SQL++ queries directly from BoxLang
• 🔄 Auto-Reconnection: Resilient connection handling with automatic failover
• 🌐 Cluster Support: Multi-node cluster configuration out of the box

🎯 Quick Start

// Configure a Couchbase cache
this.caches["default"] = {
    "provider": "Couchbase",
    "properties": {
        "connectionString": "couchbase://localhost",
        "username": "Administrator",
        "password": "password",
        "bucket": "default"
    }
};

// Use it!
cacheSet("myKey", { name: "John", age: 30 });
user = cacheGet("myKey");

// Vector search with AI embeddings
embedding = getOpenAIEmbedding("search text");
results = couchbaseVectorSearch(
    cacheName = "default",
    collection = "default._default._default",
    embedding = embedding,
    limit = 10
);

// Distributed locking across servers
couchbaseLock(
    cacheName = "default",
    name = "payment-#orderId#",
    timeout = 5,
    expires = 30,
    callback = function() {
        // Only one server processes this at a time
        processPayment(orderId);
    }
);

🛠️ Built-In Functions (BIFs)

Core Cache Functions

• couchbaseGetProvider() - Get cache provider instance
• couchbaseGetCluster() - Get Java Cluster instance
• couchbaseGetBucket() - Get Java Bucket instance
• couchbaseGetScope() - Get Java Scope instance
• couchbaseGetCollection() - Get Java Collection instance

Vector Memory Functions

• couchbaseVectorSearch() - Semantic vector search with KNN
• couchbaseVectorAdd() - Store vector documents with embeddings
• couchbaseVectorGet() - Retrieve vector document by ID
• couchbaseVectorDelete() - Delete vector document
• couchbaseVectorList() - List vector documents with filters

Query Functions

• couchbaseQuery() - Execute raw N1QL/SQL++ queries

Distributed Locking Functions

• couchbaseLock() - Acquire distributed lock with optional callback
• couchbaseUnlock() - Release distributed lock manually

See the API Usage Documentation and Distributed Locking Guide for detailed examples.

Copyright Since 2023 by Ortus Solutions, Corp
www.boxlang.io | www.ortussolutions.com

 

Ortus Sponsors

BoxLang is a professional open-source project and it is completely funded by the community and Ortus Solutions, Corp. Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: https://patreon.com/ortussolutions