Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Best Practices

    Speed up your application development, with some best practices for using Couchbase SDKs.

    From batching and reactive APIs, to unit tests and handling errors. There’s plenty that can be done to remove bottlenecks in development and in performance, and this page can be your checklist of areas not to neglect as you develop your app.

    Security

    But before worrying about bottlenecks, let’s put security concerns first.

    Security is a process, and not just a set of checkboxes — but there are key areas you must check off as you move from development, through testing, to deploying in production.

    Roles and RBAC

    Self-managed Couchbase Server uses Role-Based Access Control (RBAC), for applications to restrict resources on a Couchbase cluster to an identified user, which is reflected in our managed service (Capella) as a nuanced set of Roles. Data security depends in part on only giving access to the minimum amount of data and permissions required to do the job.

    • Couchbase Capella

    • Self-Managed Couchbase Server

    Control programmatic and application-level access to data for each cluster using cluster access credentials. Capella offers basic access credentials with predefined read, write, or read/write permissions, and advanced access credentials with fine-grained privileges and reusable access roles for more precise access control. You can choose specific buckets, scopes, and collections for your cluster access credentials to limit access to data.

    Only the Project Owner role can create cluster access credentials for their projects.

    See Project Roles and Organization Roles for more information.

    Each user who attempts resource-access is identified by means of the credentials they pass to Couchbase Server, for purposes of authentication: these consist of a username and (typically) a password. Once the user is authenticated, an authorization process checks the roles with which the user is associated. If one or more of these roles correspond to privileges that permit the user-requested level of resource-access, access is duly granted; otherwise, it is denied.

    Users who have been assigned the Admin role for the cluster are able to create, edit, and remove users. The SDK provides APIs to support these activities.

    All aspects of the Couchbase RBAC system are covered in the section Authorization. Specifically, for information on:

    Introductory examples in the SDK documentation use the Administrator user to ensure that developers can quickly get up and running; this should not be used in production. Elsewhere we use a general "user" which represents whichever permission levels are appropriate to your application.

    Performance

    Couchbase’s Data Service uses a fast binary protocol, which will always outperform JSON streamed over HTTP from SQL++ queries. If you know the key (ID) of a document, then use the Data Service.

    If you need pessimistic locking, in particular if you need to lock documents for multi-document ACID transactions, then anything you can do at the schema level to reduce the number of documents locked simultaneously wil remove a bottleneck to updating the affected documents.

    Dealing with Timeout Errors

    • waitUntilReady should be the default setting for Cluster.connect and Cluster.bucket in most cases, so that resources are fully loaded before the client proceeds with CRUD calls to the cluster.

    • LAN-type connection of client and server is recommended in production, but WAN development is a reality pre-production. Ensure that you’re familiar with the best timeout options for WAN environments, or at least set a WAN development Configuration Profile.

    Concurrency and Async APIs

    We recommend using the reactive API over the CompletableFuture counterpart. See the Async & Reactive APIs page for discussion and practical examples.

    Bulk Get, Multi-Get, and Network Latency

    In traditional databases, a bulk get or multi-get is often an efficient way of overcoming network latencies as a bottleneck, or simply making more efficent use of your database’s performance.

    Couchbase is a distributed database, efficiently fetching data from vbuckets spread across several nodes: bulk gets can be an anti-pattern, holding things up on the Server side, compared with the efficiency of fetching your data asynchronously. However, this depends upon your platform language’s availability of asynchronous APIs — see the bulk get and async API page for the specifics for the .NET SDK.

    When to Use Bulk Get

    As stated above, bulk gets are rarely the best way to fetch data from different documents efficently. Nevertheless, if your business logic dictates that all of, say five, results need to be returned before processing for the application’s next step, then a bulk get will give you all of the results together, as needed by your app. For this reason we do provide a batching example for the .NET SDK.

    Error Handling

    Best practices for error handling in Java depend somewhat upon your choice of API: blocking, asynchronous, or reactive, as covered in the async and reactive API guide. See also the error handling guide, which covers specific errors, along with a broader look at error handling strategies.

    Threshold & Orphan Logging

    Observability is provided by the SDK in the following ways:

    Threshold Logging

    Threshold logging is the recording of slow operations — useful for diagnosing when and where problems occur in a distributed environment. It is enabled by default.

    You will see this information turning up in the logs something like this:

    Threshold Log: {"service":"kv","count":2,"top":[{"operation_name":"Insert","total_us":161679},{"operation_name":"Upsert","total_us":161451}]}

    And as tracing values such as total_us, the duration of the total time taken for the operation, expressed as microseconds.

    Orphaned Response Reporting

    Special reporting capabilities which explicitly collect information about responses which have been abandoned (i.e. timed out) at the time when the SDK tries to complete them. This is also enabled by default.

    Testing

    Integrate developing with the .NET SDK into your accustomed test framework.

    Additional Information

    SDKs are client to Couchbase Server — whether Capella Database-As-A-Service, or self-managed — and in some areas it would be wise to take a fully rounded approach. Read up on security and performance considerations relevant to your use case.

    Couchbase Security Best Practices

    Role-Based Access Control

    For Capella, Roles, Cluster Access Credentials, and Authentication options are covered in the Capella Security docs.

    For self-managed Couchbase Server, all aspects of the Couchbase RBAC system are covered in the section Authorization. Specifically, for information on: