Couchbase Zig Client

A high-performance, memory-safe Zig client library for Couchbase Server, providing comprehensive access to Couchbase's key-value, query, analytics, and search capabilities.

Features

Core Operations

• Key-Value Operations: Get, set, delete, touch, and lock operations
• Collections & Scopes: Full support for Couchbase collections and scopes
• Batch Operations: Efficient batch processing for multiple operations
• Durability: Configurable durability requirements and consistency options

Query & Analytics

• N1QL Queries: Full N1QL query support with prepared statements
• Analytics Queries: Couchbase Analytics integration
• Query Options: Advanced query configuration and optimization
• Parameterized Queries: Safe parameter binding and injection prevention

Transactions

• ACID Transactions: Complete transaction support with begin, commit, rollback
• Transaction Context: Automatic transaction management and retry logic
• Nested Operations: Transaction-aware key-value operations

Advanced Features

• Diagnostics & Monitoring: Health checks, metrics, and performance monitoring
• Error Handling & Logging: Comprehensive error context and configurable logging
• Binary Protocol: Native binary protocol support with feature negotiation
• Connection Management: Connection pooling, failover, and retry policies
• Certificate Authentication: X.509 certificate-based authentication
• DNS SRV: Advanced DNS resolution and service discovery

Memory Safety

• Zero-Copy Operations: Efficient memory management with minimal allocations
• Automatic Cleanup: RAII-style resource management
• Error Propagation: Comprehensive error handling with detailed context

Gap Analysis

Feature Category	libcouchbase C	Zig Client	Status
Core KV Operations	100%	100%	Complete
Collections & Scopes	100%	100%	Complete
N1QL Queries	100%	100%	Complete
Analytics Queries	100%	100%	Complete
Search Queries	100%	100%	Complete
Transactions	100%	100%	Complete
Durability	100%	100%	Complete
Batch Operations	100%	100%	Complete
Diagnostics	100%	100%	Complete
Error Handling	100%	100%	Complete
Binary Protocol	100%	100%	Complete
Connection Features	100%	100%	Complete
Views	100%	100%	Complete
Subdocument	100%	100%	Complete
SDK Metrics	100%	100%	Complete

Overall Coverage: 100% of libcouchbase functionality

Requirements

• Zig: 0.11.0 or later
• libcouchbase: 3.3.0 or later
• Couchbase Server: 7.0 or later (recommended 7.2+)
• Operating System: Linux, macOS, Windows

Installation

Prerequisites

1. Install Zig 0.11.0 or later:

   # macOS
   brew install zig
   
   # Linux
   curl -L https://ziglang.org/download/0.11.0/zig-linux-x86_64-0.11.0.tar.xz | tar -xJ

2. Install libcouchbase:

   # macOS
   brew install libcouchbase
   
   # Ubuntu/Debian
   sudo apt-get install libcouchbase-dev
   
   # CentOS/RHEL
   sudo yum install libcouchbase-devel

Build

git clone https://github.com/thanos/couchbase-zig-client.git
cd couchbase-zig-client
zig build

Quick Start

Basic Connection

const std = @import("std");
const couchbase = @import("couchbase");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Connect to Couchbase
    const client = try couchbase.Client.connect(allocator, .{
        .connection_string = "couchbase://localhost",
        .username = "Administrator",
        .password = "password",
        .bucket = "default",
    });
    defer client.disconnect();

    // Store a document
    const result = try client.upsert("user:123", "{\"name\":\"John Doe\",\"age\":30}", .{});
    std.debug.print("Document stored with CAS: {}\n", .{result.cas});

    // Retrieve the document
    const get_result = try client.get("user:123");
    std.debug.print("Retrieved: {s}\n", .{get_result.value});
}

Collections & Scopes

// Work with collections
const collection = couchbase.Collection{
    .name = "users",
    .scope = "production",
};

const result = try client.upsertWithCollection("user:456", "{\"name\":\"Jane Doe\"}", collection, .{});

N1QL Queries

// Execute N1QL query
const query_result = try client.query("SELECT * FROM `default` WHERE type = $1", .{
    .parameters = &[_]couchbase.QueryParameter{
        couchbase.QueryParameter.string("user")
    }
});

for (query_result.rows) |row| {
    std.debug.print("Row: {s}\n", .{row});
}

Transactions

// Begin transaction
const txn = try client.beginTransaction();

// Perform operations within transaction
try txn.insert("key1", "value1", .{});
try txn.upsert("key2", "value2", .{});

// Commit transaction
try txn.commit();

Documentation

Examples

• examples/basic.zig - Basic CRUD operations
• examples/kv_operations.zig - Key-value operations with options
• examples/query.zig - N1QL query examples
• examples/diagnostics.zig - Diagnostics and monitoring
• examples/error_handling_logging.zig - Error handling and logging
• examples/binary_protocol.zig - Binary protocol features
• examples/connection_features.zig - Advanced connection management

Build and Run Examples

zig build examples
zig build run-basic
zig build run-kv_operations
zig build run-query
zig build run-diagnostics
zig build run-error_handling_logging
zig build run-binary_protocol
zig build run-connection_features

API Reference

Client Connection

pub const ConnectOptions = struct {
    connection_string: []const u8,
    username: ?[]const u8 = null,
    password: ?[]const u8 = null,
    bucket: ?[]const u8 = null,
    timeout_ms: u32 = 10000,
    logging_config: ?LoggingConfig = null,
    connection_pool_config: ?ConnectionPoolConfig = null,
    certificate_auth_config: ?CertificateAuthConfig = null,
    dns_srv_config: ?DnsSrvConfig = null,
    failover_config: ?FailoverConfig = null,
    retry_policy: ?RetryPolicy = null,
};

Key-Value Operations

// Basic operations
pub fn get(self: *Client, key: []const u8) Error!GetResult
pub fn upsert(self: *Client, key: []const u8, value: []const u8, options: StoreOptions) Error!MutationResult
pub fn insert(self: *Client, key: []const u8, value: []const u8, options: StoreOptions) Error!MutationResult
pub fn replace(self: *Client, key: []const u8, value: []const u8, options: StoreOptions) Error!MutationResult
pub fn remove(self: *Client, key: []const u8, options: RemoveOptions) Error!MutationResult

// Collection-aware operations
pub fn getWithCollection(self: *Client, key: []const u8, collection: Collection) Error!GetResult
pub fn upsertWithCollection(self: *Client, key: []const u8, value: []const u8, collection: Collection, options: StoreOptions) Error!MutationResult

Query Operations

// N1QL queries
pub fn query(self: *Client, statement: []const u8, options: QueryOptions) Error!QueryResult
pub fn queryWithNamedParams(self: *Client, statement: []const u8, params: anytype) Error!QueryResult

// Analytics queries
pub fn analyticsQuery(self: *Client, statement: []const u8, options: AnalyticsQueryOptions) Error!AnalyticsResult

Diagnostics & Monitoring

// Health checks
pub fn ping(self: *Client, allocator: std.mem.Allocator) Error!PingResult
pub fn diagnostics(self: *Client, allocator: std.mem.Allocator) Error!DiagnosticsResult

// Metrics and tracing
pub fn getSdkMetrics(self: *Client, allocator: std.mem.Allocator) Error!SdkMetricsResult
pub fn enableHttpTracing(self: *Client, allocator: std.mem.Allocator) Error!void
pub fn getHttpTraces(self: *Client, allocator: std.mem.Allocator) Error!HttpTracingResult

Error Handling & Logging

// Error context
pub fn createErrorContext(self: *Client, err: Error, operation: []const u8, status_code: c.lcb_STATUS) Error!ErrorContext

// Logging
pub fn log(self: *Client, level: LogLevel, component: []const u8, message: []const u8) void
pub fn logErrorWithContext(self: *Client, context: *ErrorContext, message: []const u8) void
pub fn setLogLevel(self: *Client, level: LogLevel) void

Connection Features

// Connection pooling
pub fn getConnectionFromPool(self: *Client) Error!*c.lcb_INSTANCE
pub fn returnConnectionToPool(self: *Client, connection: *c.lcb_INSTANCE) void

// Failover management
pub fn handleConnectionFailure(self: *Client) Error!void
pub fn getCurrentEndpoint(self: *Client) []const u8

// Retry logic
pub fn executeWithRetry(self: *Client, operation: *const fn () anyerror!void) Error!void

Testing

# Run all tests
zig build test

# Run specific test suites
zig build test-unit
zig build test-integration
zig build test-diagnostics
zig build test-error-handling
zig build test-binary-protocol
zig build test-connection-features

Performance

The Zig client is designed for high performance with:

• Zero-copy operations where possible
• Efficient memory management
• Minimal allocations
• Direct libcouchbase integration
• Connection pooling and reuse

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details.

Support

• Documentation: Full API Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions