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

Roles and RBAC

Self-managed Couchbase Server uses Role-Based Access Control (RBAC), which is reflected in our managed service as a nuanced set of Roles. Data security depends in part on only giving access to

RBAC restrict resources on a Couchbase cluster to an identified user, allocated by role.

TODO update and add Capella here

Users, Resources, Roles, and Privileges

Couchbase Server Enterprise Edition uses Role-Based Access Control for applications to restrict resources on a Couchbase cluster to an identified user.

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.

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 logging, 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 remvoe 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

Choosing between the blocking, asynchronous, and reactive APIs for the Scala SDK is partly bound up with how (and where) you want to handle exceptions.

Synchronous operations are blocking, and return a Scala Try object. This contains either the result or a Throwable exception, which can be pattern matched over (using flatMap in more complex cases).
The asynchronous API returns Scala Future, representing the execution of an asynchronous task and the promise of a future result. An ExecutionContext must be provided, to give a thread pool for handling whatever is returned.
The reactive API is a more natural fit for network-aware, fault tolerant programs, and will provide full back pressure for streaming results from large SQL++ or Search queries.

See the Async & Reactive APIs page for further discussion and practical examples.

Error Handling

Best practices for error handling in Scala depend somewhat upon your choice of API: blocking, asynchronous, or reactive, as covered in the async and reactive API guide. That guide also covers how errors are actually returned (e.g. via Try, Future, or Mono) and handled. See also the error handling guide, which covers specific errors, along with a broader look at error handling strategies.

Testing

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

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.

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

TODO add Capella info

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

Adding Users and assigning roles, by means of the Couchbase Web Console, see Manage Users and Roles.
Roles required for resource-access, and the privileges they entail, see Roles.
Resources controlled by Couchbase RBAC, see Resources Under Access Control.