⚡︎ BoxLang+ Module: Couchbase

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

This module provides Couchbase cache providers for BoxLang runtimes.

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.

Built-In Functions (BIFs)

This module provides several BIFs to interact with Couchbase directly:

CouchbaseGet

Get a document from Couchbase by its ID.

value = couchbaseGet( id="myDocId", throwWhenNotExist=false, cacheName="default" )

CouchbaseSet

Set/upsert a document in Couchbase.

couchbaseSet( id="myDocId", value=myData, cacheName="default" )

CouchbaseDelete

Delete a document from Couchbase.

couchbaseDelete( id="myDocId", cacheName="default" )

CouchbaseGetBucket

Get the Couchbase Java Bucket instance.

bucket = couchbaseGetBucket( cacheName="default" )

CouchbaseGetCluster

Get the Couchbase Java Cluster instance.

cluster = couchbaseGetCluster( cacheName="default" )

CouchbaseGetProvider

Get the Couchbase cache provider instance.

provider = couchbaseGetProvider( cacheName="default" )

Testing

To run tests locally, start the Couchbase Docker container:

docker-compose up -d

Wait for Couchbase to fully initialize (about 60 seconds), then run:

./gradlew test

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