We're thrilled to announce the release of bx-couchbase v1.0, bringing enterprise-grade Couchbase integration to the BoxLang ecosystem. This powerful module combines high-performance distributed caching with cutting-edge AI capabilities, enabling developers to build scalable, intelligent applications with ease.

Why Couchbase?

Couchbase is more than just a database—it's a distributed NoSQL powerhouse that combines the speed of key-value stores with the flexibility of document databases. With sub-millisecond response times, built-in vector search, and multi-data center support, Couchbase is the perfect foundation for modern, AI-powered applications.

The bx-couchbase module makes all this power available through BoxLang's elegant, intuitive API.

Fully Documented

Comprehensive documentation is available to help you get started and make the most of the module's features: bx-couchbase Documentation.

What's New in v1.0

🚀 Enterprise-Grade Caching

Store and retrieve data across multiple nodes with automatic failover and replication. The module provides a complete BoxLang cache provider implementation with all the features you'd expect:

// Simple, elegant cache API
cache("default").set("user:123", {
    name: "Alice Smith",
    email: "alice@example.com",
    role: "admin"
}, 60); // 60 minute TTL

// Retrieve with null-safe Attempt monad
user = cache("default").get("user:123")
    .orElseGet( () => {
        return loadUserFromDatabase(123);
    });

Key Features:

• Sub-millisecond key-value operations
• Automatic data replication across nodes
• Built-in TTL (time-to-live) support
• Scope and collection support for logical data organization
• Seamless integration with BoxLang's cache API

🔐 Distributed Locking

One of the most powerful features in v1.0 is true distributed locking. Coordinate operations across multiple servers to prevent race conditions in critical sections like financial transactions, inventory updates, and batch processing.

Component-Based Locking (Recommended)

The CouchbaseLock component provides the cleanest syntax for protected code blocks:

<bx:CouchbaseLock
    name="payment-#orderId#"
    cache="default"
    timeout="5"
    expires="30">

    // Only one server processes this payment at a time
    charge = getPaymentInfo(orderId);
    result = processCharge(charge);
    updateOrderStatus(orderId, "paid");

</bx:CouchbaseLock>

BIF with Callback

For programmatic control, use the couchbaseLock() BIF with a callback:

result = couchbaseLock(
    cacheName = "default",
    name = "inventory-#productId#",
    timeout = 5,
    expires = 30,
    callback = function() {
        stock = getStock(productId);
        if (stock.quantity >= orderQty) {
            stock.quantity -= orderQty;
            saveStock(productId, stock);
            return { success: true };
        }
        return { success: false, error: "Insufficient stock" };
    }
);

Manual Lock Control

For advanced scenarios requiring precise lock management:

lockInfo = couchbaseLock("default", "batch-job", 5, 30);

if (lockInfo.locked) {
    try {
        // Critical section
        processBatchJob();
    } finally {
        couchbaseUnlock("default", "batch-job", lockInfo.cas);
    }
}

Real-World Use Cases:

• 💰 Financial Transactions: Prevent double-charging when processing payments
• 📦 Inventory Management: Avoid overselling products in high-traffic scenarios
• 🔄 Batch Jobs: Ensure only one server runs scheduled tasks
• 🎫 Ticket Sales: Prevent double-booking in reservation systems
• 👤 User Account Updates: Serialize concurrent profile modifications

🤖 AI Vector Memory

Perhaps the most exciting feature is vector memory integration with the BoxLang AI module (bx-ai). Store conversation history with semantic search capabilities, enabling intelligent context retrieval for chatbots, AI agents, and RAG (Retrieval Augmented Generation) applications.

Seamless AI Agent Integration

// Create Couchbase-backed vector memory
memory = aiMemory("cache", {
    cacheName: "ai_memory",
    collection: "conversations._default._default",
    embeddingProvider: "openai",
    embeddingModel: "text-embedding-3-small"
});

// Build an AI agent with persistent memory
agent = aiAgent(
    name: "Customer Support Bot",
    instructions: "You are a helpful customer support agent",
    memory: memory,
    model: aiModel("openai")
);

// Conversation history automatically stored in Couchbase
response = agent.run("What did we discuss about billing?");

Multi-Tenant Isolation

Support multiple users with complete conversation isolation:

// Alice's conversation
aliceMemory = aiMemory("cache",
    key: createUUID(),
    userId: "alice",
    conversationId: "support-123",
    config: {
        cacheName: "ai_memory",
        collection: "conversations._default._default",
        embeddingProvider: "openai"
    }
);

// Bob's conversation (completely isolated)
bobMemory = aiMemory("cache",
    key: createUUID(),
    userId: "bob",
    conversationId: "support-456",
    config: {
        cacheName: "ai_memory",
        collection: "conversations._default._default",
        embeddingProvider: "openai"
    }
);

Each user's conversation history is completely isolated—no data leakage, no cross-contamination. Perfect for enterprise applications with strict data segregation requirements.

Hybrid Memory: Best of Both Worlds

Combine recent messages with semantic search for optimal context:

memory = aiMemory("hybrid", {
    // Recent messages for immediate context
    window: {
        type: "windowed",
        size: 10
    },
    // Semantic search for relevant history
    vector: {
        type: "cache",
        cacheName: "ai_memory",
        collection: "conversations._default._default",
        embeddingProvider: "openai",
        limit: 5
    }
});

Your AI agent now has access to both the last 10 messages AND the 5 most semantically relevant messages from the entire conversation history. It's like giving your AI both short-term and long-term memory.

AI Memory Features:

• ✅ Semantic search based on meaning, not just keywords
• ✅ Multi-tenant isolation with userId and conversationId
• ✅ Scalable storage handling thousands of conversations
• ✅ Persistent memory surviving application restarts
• ✅ Hybrid search combining recent + semantic context
• ✅ Compatible with OpenAI, Cohere, Voyage, and more embedding providers

🛠️ Direct SDK Access

Need low-level control? We've got you covered with direct access to the Couchbase Java SDK:

// Get the cache provider
provider = couchbaseGetProvider("default");

// Access cluster
cluster = couchbaseGetCluster("default");

// Get bucket
bucket = couchbaseGetBucket("default");

// Get collection for N1QL queries
collection = couchbaseGetCollection("default");

// Execute N1QL query
result = collection.query("
    SELECT * FROM myapp
    WHERE type = 'user'
      AND status = 'active'
    LIMIT 100
");

📦 Session Storage Support

Use Couchbase as your session storage backend with automatic serialization:

this.sessionStorage = "couchbase";

// Sessions automatically persisted to Couchbase
session.user = userObject;
session.cart = shoppingCart;
session.lastActivity = now();

Performance That Scales

Couchbase's distributed architecture means your application scales horizontally:

• Sub-millisecond response times for key-value operations
• Automatic sharding across cluster nodes
• Built-in replication for high availability
• Multi-data center support for global deployments
• Memory-first architecture with automatic disk persistence

Getting Started

Installation

# For Operating Systems using our Quick Installer
install-bx-module bx-couchbase

# Using CommandBox for web servers
box install bx-couchbase

Quick Configuration

Add to your Application.bx:

component {
    this.name = "MyApp";
    
    // Configure Couchbase cache
    this.caches["default"] = {
        "provider": "Couchbase",
        "properties": {
            "connectionString": "couchbase://localhost",
            "username": "Administrator",
            "password": "password",
            "bucket": "myapp",
            "scope": "_default",
            "collection": "_default"
        }
    };
}

Start using it immediately:

// Set cache value
cache("default").set("key", value, 60);

// Get with null safety
data = cache("default").get("key")
    .orElse(defaultValue);

// Distributed lock
couchbaseLock("default", "critical-section", 5, 30, function() {
    // Your critical code here
});

Real-World Examples

E-Commerce: Prevent Overselling

function reserveProduct(productId, quantity) {
    return couchbaseLock(
        cacheName = "default",
        name = "inventory-#productId#",
        timeout = 5,
        expires = 10,
        throwOnTimeout = false,
        callback = function() {
            var stock = cache("default").get("stock:#productId#");
            
            if (!stock.isPresent() || stock.get().quantity < quantity) {
                return { success: false, error: "Insufficient stock" };
            }
            
            var currentStock = stock.get();
            currentStock.quantity -= quantity;
            cache("default").set("stock:#productId#", currentStock);
            
            return { 
                success: true, 
                reserved: quantity,
                remaining: currentStock.quantity 
            };
        }
    );
}

AI-Powered Customer Support

component {
    
    function handleCustomerQuery(userId, message) {
        // Create user-specific memory
        var memory = aiMemory("cache",
            key: createUUID(),
            userId: userId,
            config: {
                cacheName: "support_memory",
                collection: "support._default._default",
                embeddingProvider: "openai"
            }
        );
        
        // Create AI agent with context
        var agent = aiAgent(
            name: "Support Agent",
            instructions: "You are a helpful customer support agent. Use past conversations to provide personalized assistance.",
            memory: memory,
            model: aiModel("openai", { model: "gpt-4" })
        );
        
        // Get contextual response
        return agent.run(message);
    }
}

Financial Transaction Processing

function processPayment(orderId, amount) {
    var lockName = "payment-#orderId#";
    
    return couchbaseLock(
        cacheName = "default",
        name = lockName,
        timeout = 5,
        expires = 30,
        callback = function() {
            // Check if already processed
            var order = cache("default").get("order:#orderId#").get();
            if (order.status == "paid") {
                return { success: false, error: "Already paid" };
            }
            
            // Process payment (only one server does this)
            var result = chargeCard(order.customerId, amount);
            
            if (result.success) {
                order.status = "paid";
                order.transactionId = result.transactionId;
                order.paidAt = now();
                cache("default").set("order:#orderId#", order);
            }
            
            return result;
        }
    );
}

Requirements

• BoxLang 1.7.0+
• Couchbase Server 7.0+ (7.6+ recommended for vector search)
• bx-plus module (included with BoxLang +/++ subscriptions)
• bx-ai module (optional, for AI vector memory features)

Documentation

Comprehensive documentation is available covering:

• Getting Started: Installation and configuration
• Code Usage: Working with the cache provider API
• Distributed Locking: Coordinating operations across servers
• AI Vector Memory: Building intelligent chatbots and RAG applications
• Scope Storage: Session and application state management
• Troubleshooting: Common issues and solutions
• BIF Reference: Complete built-in function documentation

What's Next?

This v1.0 release is just the beginning. We're already working on:

• Enhanced vector search capabilities
• Advanced query builders for N1QL
• Performance optimizations for high-throughput scenarios
• Additional AI memory features
• Expanded monitoring and metrics

Join the Community

We'd love to hear how you're using bx-couchbase in your applications! Share your experiences, ask questions, and contribute to the module:

• Documentation: GitHub Repository
• Issues: JIRA Project
• Community: Ortus Community Forum
• Professional Support: Ortus Solutions

Get Started Today

Ready to supercharge your BoxLang applications with enterprise caching, distributed locking, and AI capabilities?

install-bx-module bx-couchbase

Happy coding! 🚀

The bx-couchbase module is available exclusively to BoxLang +/++ subscribers. A limited trial is available when used with the bx-plus module. Learn more at boxlang.io/plans.

🛒 Purchase Options

Ready to unlock bx-couchbase and other premium modules? Choose your plan:

🌟 View BoxLang Plans & Pricing

Need help choosing the right plan or have questions? Contact us directly:

📧 info@boxlang.io