CFCouchbase SDK Released

Luis Majano March 03, 2014

Spread the word

Luis Majano

March 03, 2014

Spread the word

Share your thoughts

We are very excited to spring forth a new open source product for the Ortus Family: CFCouchbase SDK.  The CFCouchbase SDK is a CFML library for interacting with Couchbase NoSQL Server. It can be used by any CFML application or CFML framework to provide them with NoSQL, distributed caching, dynamic queries and many more capabilities. 

We have been working with Couchbase NoSQL Server for a while now it has been a true pleasure to not only build scalable farms with it, but also it is incredibly responsive when it comes down to NoSQL and caching transactions.  We have extended their Java SDK and wrapped it in some dynamic CFML goodness.  We not only expose all of the capabilities of the Java SDK, but we also provide automatic CFML to Java serialization and deserializations, Querying DSL, and also a way to automatically serialize and deserialize ColdFusion Components CFCs.

Quick Installation

Once you download the CFCouchbase SDK you will find a cfcouchbase folder inside of it alongside API Docs, samples and the full documentation. This is the entire SDK and the easiest way to install it is to copy it to your web root. However, for a more secure installation we recommend you place it outside of your web root and create a mapping called cfcouchbase to it:

this.mappings[ "/cfcouchbase" ] = '/path/to/cfcouchbase';

public boolean function onApplicationStart(){
	application.couchbase = new cfcouchbase.CouchbaseClient();
	return true;
public boolean function onApplicationEnd(){		
	application.couchbase.shutdown( 10 );
	return true;
Now that the library is installed you can instantiate the class cfcouchbase.CouchbaseClient with or without any connectivity options. This client will connect to one Couchbase bucket on the localhost:8091 by default, so you can interact with it.


Important: Each Couchbase bucket operates independantly and uses its own authentication mechanisms. You need an instance of CouchbaseClient for each bucket you want to interact with. It is also extremely important that you shutdown the clients whenever your application goes down in order to gracefully shutdown connections, else your server might degrade.

Quick Usage

We have tried our best to make the CFCouchbase API as simple as possible so you can very easily get started with it. We have also fully documented the library, like with anything we do! We even include some sample applications that will take you from using CFCouchbase on any CFML application to a full Object Oriented approach with the ColdBox Framework.

// Create the client
client  = new cfcouchbase.CouchbaseClient();
// Create a document in the cluster
client.set( id='brad', value={ name: 'Brad', age: 33, hair: 'red' } );
// Retrieve that doc
person = client.get( id='brad' );
// Use the document
writeOutput( ' is #person.age# years old and has hair.' );
// Execute a query
results = client.query( designDocumentName='beer', viewName='brewery_beers' );
// Iterate and present results
for( var result in results ) {
    writeOutput( );
// Shutdown the client

Automatic Conversions

The SDK will also be smart enough to automatically serialize and deserialize many native CFML data structures and objects for you. So you don't have to deal with this conversion hassle. We provide many ways to customize this marshalling for you.

Simple Strings

If you pass simple strings or JSON to the SDK, it will just pass it through untouched to Couchbase for storage.

CFML Complex Objects (arrays, queries, structures)

The CFCouchbase SDK will automatically marshall native CFML arrays, structures and queries into their respective JSON representations and saved within Couchbase. Once they are retrieved, the SDK will automatically convert them back to their native CFML counterpart.

Components (CFCs)

The SDK offers you several ways to interact with CFCs: auto inflation, manual inflation, custom inflation and binary. You can find a much more in-depth guide on this topic in our documentation.

Components - Auto Inflation

If your CFC is tagged with the autoInflate annotation, then the SDK will store your CFC in Couchbase by reading all of its public properties and building a JSON structure with them alongside the CFC instantiation path. Once you request the entry from Couchbase again, the SDK will be smart enough to detect the instantiation path and rebuild a new CFC with the data from Couchbase.

component accessors="true" autoInflate="true"{
	property name="title"  default="";
	property name="artist" default="";

funkyChicken = new;
funkyChicken.setTitle( "Chicken Dance" );
funkyChicken.setArtist( "Werner Thomas" );

// Pass the CFC in
couchbase.set( 'funkyChicken', funkyChicken );

// And get a CFC out!
birdieSong = couchbase.get( 'funkyChicken' );

writeOutput( birdieSong.gettitle() );
writeOutput( birdieSong.getArtist() );
Components - Manual Inflation

If your CFC does not have the autoInflate annotation, then the SDK will just look at the CFC properties and build a JSON structure and it will store it. Once you get the entry from Couchbase, you will manually need to inflate the object with the data retreived. We provide a inflateTo argument in all get and query operations for you, which can be a path, an instance or a closure.

// path
person = client.get(
	ID = 'funkyChicken',
	inflateTo = ''

// instance
person = client.get(
	ID = 'funkyChicken',
	inflateTo = new

// closure
person = client.get(
	ID = 'funkyChicken',
	inflateTo = function( document ){
		// Let WireBox create and autowire an instance for us
		return wirebox.getInstance( '' );
Components - Custom

If for some reason, you want to do your own funky serialization and deserialization, well you can. Just leverage our convention methods: $serialize() and $deserialize().

component accessors="true"{

	property name="firstName";
	property name="lastName";
	property name="age";

	function $serialize(){
		// Serialize as pipe-delimited list
		return '#getFirstName()#|#getLastName()#|#getAge()#';
	function $deserialize( ID, data ){
		// Deserialize the pipe-delimited list
		setFirstName( listGetAt( data, 1, '|' ) );
		setLastName( listGetAt( data, 2, '|' ) );
		setAge( listGetAt( data, 3, '|' ) );		
Components - Binary

Finally, if your CFC does not meet any of the above criteria, the SDK will just convert the object to a binary 64 representation. It will then re-inflate your object back to its original state when retreiving it.

We have just been scratching the surface with the capabilities that the SDK will provide to your applications. We recommend your read our blogging series below and check out all our resources to start building your CFML applications powered by Couchbase.

Ortus Couchbase Blogging Series

Here are the collection of blog entries we have done about Couchbase NoSQL Server.


Please visit our CFCouchbase page for all the necessary resources.

Add Your Comment

Recent Entries

Unveiling the Future of CFML Development - 3rd Round of Sessions

Unveiling the Future of CFML Development - 3rd Round of Sessions

Welcome back to our journey into the future of CFML development! As excitement continues to build for Into the Box 2024, we're thrilled to bring you the latest updates on what promises to be a transformative event. Continuing our blog post series, let's delve deeper into the third wave of session releases and discover the key surprises awaiting attendees. Learn More

Maria Jose Herrera
Maria Jose Herrera
March 01, 2024
Elevate Your ColdBox Experience and Skills

Elevate Your ColdBox Experience and Skills

We're thrilled to announce a significant overhaul of our ColdBox training experience to ensure it's nothing short of extraordinary! We've listened closely to your feedback and made significant improvements geared towards transforming you into a ColdBox superhero. Learn What's New!

Maria Jose Herrera
Maria Jose Herrera
February 20, 2024
Ortus Redis Extension v3.3.0 Released!

Ortus Redis Extension v3.3.0 Released!

We are very excited to bring you another release for our Redis Lucee Extension. The most significant feature in this release is the addition of the `` and `redisLock{}` tag, which allows you perform a lock across all instances in a cluster.

Ortus Redis Extension v3.3.0 gives you greater control over concurrent modifications in a distributed environment, utilizing your distributed cache to prevent overlaps!

Jon Clausen
Jon Clausen
February 16, 2024