From 8ce8b5273266801ef7f1d58a73225ce146c29a1c Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Mon, 20 Apr 2026 14:05:14 +0100 Subject: [PATCH 01/44] DOC-14113 Java 3.12 in dev branch --- README.adoc | 8 +++---- antora.yml | 14 +++++------ .../project-docs/pages/sdk-release-notes.adoc | 23 ++++++++++++++++++- 3 files changed, 33 insertions(+), 12 deletions(-) diff --git a/README.adoc b/README.adoc index 58dccfd1..aa8bcf8a 100644 --- a/README.adoc +++ b/README.adoc @@ -1,9 +1,9 @@ = Couchbase Java SDK Documentation -This repository hosts the documentation source for the https://docs.couchbase.com/java-sdk/3.11/hello-world/overview.html[Couchbase Java SDK]. +This repository hosts the documentation source for the https://docs.couchbase.com/java-sdk/3.12/hello-world/overview.html[Couchbase Java SDK]. -This branch documents the 3.11 release of the SDK. -It follows the https://docs.couchbase.com/java-sdk/3.11/project-docs/compatibility.html#api-version[SDK 3.9 API]. +This branch documents the 3.12 release of the SDK. +It follows the https://docs.couchbase.com/java-sdk/3.11/project-docs/compatibility.html#api-version[SDK 3.10 API]. This branch reflects the new Information Architecture for the SDK docs, helping to guide new-to-Couchbase users through the pitfalls of a complex distributed system. @@ -121,7 +121,7 @@ Update the following files: === New Branches -Production branches use the *release/x.y* naming pattern (e.g. `release/3.10`, `release/3.11`). +Production branches use the *release/x.y* naming pattern (e.g. `release/3.12`, `release/3.11`). Antora uses the branch names in the playbook, but also uses the `version` given in the antor.yml file, to create the version navigation -- so this version number must be unique within the repo for any branches included in the playbook. When creating a new branch for a new release, remember to update the antora.yml file before trying to build. diff --git a/antora.yml b/antora.yml index 3d876fe1..f5668db3 100644 --- a/antora.yml +++ b/antora.yml @@ -1,5 +1,5 @@ name: java-sdk -version: '3.11' +version: '3.12' title: Java SDK start_page: hello-world:overview.adoc nav: @@ -7,16 +7,16 @@ nav: asciidoc: attributes: page-nav-header-levels: 2 - server_version: '8.0.0' - sdk_current_version: '3.11.1' - sdk_dot_minor: '3.11' + server_version: '8.1' + sdk_current_version: '3.12.0' + sdk_dot_minor: '3.12' sdk_dot_major: '3.x' - version-server: '8.0' - version-common: '8.0.1' + version-server: '8.1' + version-common: '3.10' java_latest_lts_version: '25' name_platform: 'Java' name_platform_lc: 'java' name-sdk: Java SDK - sdk_api: '3.9' + sdk_api: '3.10' sdk-api-link: https://docs.couchbase.com/sdk-api/couchbase-java-client/ sdk-gh-link: https://github.com/couchbase/couchbase-jvm-clients/ diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index 5ff6b197..2fffb45d 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -23,7 +23,7 @@ include::{version-common}@sdk:pages:partial$signed.adoc[tag=signed] [#latest-release] -== Java SDK 3.11 Releases +== Java SDK 3.12 Releases We always recommend using the latest version of the SDK -- it contains all of the latest security patches and support for new and upcoming features. All patch releases for each dot minor release should be API compatible, and safe to upgrade; @@ -45,6 +45,27 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea //// +=== Version 3.12.0 (??????? 2026) + +https://packages.couchbase.com/clients/java/3.12.0/Couchbase-Java-Client-3.12.0.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.0/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.0/[Core API Reference] + + + + + + + + + + + + + +== Java SDK 3.11 Releases + + === Version 3.11.1 (16 February 2026) https://packages.couchbase.com/clients/java/3.11.1/Couchbase-Java-Client-3.11.1.zip[Download] | From aea1c46c156a57956d11fedad8fc58144b786fe7 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Mon, 20 Apr 2026 15:03:05 +0100 Subject: [PATCH 02/44] alias build fix --- modules/project-docs/pages/sdk-release-notes.adoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index 2fffb45d..4a75ab2b 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -3,7 +3,7 @@ :navtitle: Release Notes :page-toclevels: 2 :page-partial: -:page-aliases: relnotes-java-sdk.adoc,ROOT:sdk-release-notes.adoc,ROOT:relnotes-java-sdk.adoc,ROOT:release-notes.adoc,ROOT:download-links.adoc,server:sdks:java-2.2/download-links.adoc +// :page-aliases: relnotes-java-sdk.adoc,ROOT:sdk-release-notes.adoc,ROOT:relnotes-java-sdk.adoc,ROOT:release-notes.adoc,ROOT:download-links.adoc,server:sdks:java-2.2/download-links.adoc [abstract] {description} @@ -45,6 +45,12 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea //// + +// before GA +// uncomment aliases +// and comment out in 3.11 + + === Version 3.12.0 (??????? 2026) https://packages.couchbase.com/clients/java/3.12.0/Couchbase-Java-Client-3.12.0.zip[Download] | From 355e2db285343c05b147f22c821d7b5ed50ef766 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 22 Apr 2026 13:10:28 +0100 Subject: [PATCH 03/44] DOC-14229 views deprecation --- modules/ROOT/nav.adoc | 105 +----------------- .../pages/migrating-sdk-code-to-3.n.adoc | 4 + 2 files changed, 5 insertions(+), 104 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 1e0114a4..18e25ce5 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -64,6 +64,7 @@ *** https://docs-archive.couchbase.com/home/index.html[Older Versions Archive^] ** xref:project-docs:compatibility.adoc[] *** xref:project-docs:migrating-sdk-code-to-3.n.adoc[] +**** xref:howtos:view-queries-with-sdk.adoc[] *** xref:project-docs:distributed-acid-transactions-migration-guide.adoc[] *** xref:project-docs:third-party-integrations.adoc[] ** xref:project-docs:sdk-full-installation.adoc[] @@ -81,107 +82,3 @@ ** xref:ref:glossary.adoc[Glossary] ** xref:ref:travel-app-data-model.adoc[] ** xref:project-docs:metadoc-about-these-sdk-docs.adoc[About These Docs] - - - - - - - - - -//// -.Getting Started -* xref:hello-world:start-using-sdk.adoc[] -* xref:howtos:kv-operations.adoc[] -* xref:howtos:n1ql-queries-with-sdk.adoc[] -* xref:howtos:full-text-searching-with-sdk.adoc[] -* xref:hello-world:sample-application.adoc[] -* xref:hello-world:spring-data-sample-application.adoc[] - -.Transactions -* xref:howtos:distributed-acid-transactions-from-the-sdk.adoc[] -** xref:howtos:transactions-single-query.adoc[] -** xref:howtos:transactions-tracing.adoc[] -* xref:concept-docs:transactions.adoc[] -** xref:concept-docs:transactions-cleanup.adoc[] -** xref:concept-docs:transactions-error-handling.adoc[] - -.Further Data Ops -* xref:howtos:json.adoc[] -* xref:howtos:subdocument-operations.adoc[] -// ** xref:howtos:sdk-xattr-example.adoc[Extended Attributes] -* xref:howtos:analytics-using-sdk.adoc[] -// ** xref:howtos:advanced-analytics-querying.adoc[Advanced Analytics Querying] -* xref:howtos:view-queries-with-sdk.adoc[] -* xref:howtos:concurrent-async-apis.adoc[Async & Reactive APIs] -* xref:howtos:concurrent-document-mutations.adoc[] -* xref:howtos:encrypting-using-sdk.adoc[] -* xref:howtos:transcoders-nonjson.adoc[Transcoders & Non-JSON Documents] - -.Managing Couchbase -* xref:howtos:managing-connections.adoc[] -** xref:howtos:sdk-authentication.adoc[] -** xref:howtos:troubleshooting-cloud-connections.adoc[Troubleshooting Cloud Connections] -* xref:howtos:provisioning-cluster-resources.adoc[] -** xref:howtos:sdk-user-management-example.adoc[] - -.Errors & Diagnostics -* xref:howtos:error-handling.adoc[] -* xref:howtos:collecting-information-and-logging.adoc[] -* xref:howtos:health-check.adoc[] -* Observability -** xref:howtos:slow-operations-logging.adoc[] -** xref:howtos:observability-metrics.adoc[] -** xref:howtos:observability-orphan-logger.adoc[] -** xref:howtos:observability-tracing.adoc[] - -.Learn -* xref:concept-docs:concepts.adoc[] -* xref:concept-docs:buckets-and-clusters.adoc[Buckets & Clusters] -* xref:concept-docs:collections.adoc[Collections & Scopes] -* xref:concept-docs:compression.adoc[] -* xref:concept-docs:data-model.adoc[] -** xref:concept-docs:documents.adoc[] -** xref:concept-docs:nonjson.adoc[] -** xref:concept-docs:subdocument-operations.adoc[Sub-Documents] -** xref:concept-docs:xattr.adoc[XATTR & Virtual XATTR] -* xref:concept-docs:errors.adoc[Errors & Diagnostics] -** xref:concept-docs:health-check.adoc[] -** xref:concept-docs:response-time-observability.adoc[] -* xref:concept-docs:durability-replication-failure-considerations.adoc[] -* xref:concept-docs:encryption.adoc[Field Level Encryption] -* xref:concept-docs:data-services.adoc[Service Selection] -** xref:concept-docs:analytics-for-sdk-users.adoc[] -** xref:concept-docs:understanding-views.adoc[Views] -** xref:concept-docs:n1ql-query.adoc[] -** xref:concept-docs:full-text-search-overview.adoc[Search] -* xref:concept-docs:sdk-user-management-overview.adoc[User Management] -** xref:concept-docs:certificate-based-authentication.adoc[Cert Auth] -** xref:concept-docs:rbac.adoc[RBAC] - -.References -* https://docs.couchbase.com/sdk-api/couchbase-java-client[API Reference] -* https://docs.couchbase.com/sdk-api/couchbase-core-io/[JVM Core IO API] -* https://docs.couchbase.com/sdk-api/couchbase-transactions-java/index.html?overview-summary.html[Transactions API Reference] -* xref:ref:client-settings.adoc[] -// * xref:ref:data-structures[Data Structures] -* xref:ref:error-codes.adoc[] -* xref:ref:glossary.adoc[Glossary] -* xref:ref:travel-app-data-model.adoc[] - -.Project Docs -* xref:project-docs:sdk-release-notes.adoc[SDK Release Notes] -* xref:project-docs:compatibility.adoc[] -** xref:project-docs:migrating-sdk-code-to-3.n.adoc[] -*** xref:howtos:working-with-collections.adoc[Working with Collections] -** xref:project-docs:distributed-acid-transactions-migration-guide.adoc[] -** xref:project-docs:third-party-integrations.adoc[] -* xref:project-docs:sdk-full-installation.adoc[] -// ** xref:hello-world:platform-help.adoc[] -* https://docs-archive.couchbase.com/home/index.html[Older Versions Archive] -* xref:project-docs:sdk-licenses.adoc[] -* xref:project-docs:get-involved.adoc[] - ** https://docs.couchbase.com/home/contribute/index.html[Improve the Docs] -* xref:project-docs:metadoc-about-these-sdk-docs.adoc[About These Docs] -//// diff --git a/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc b/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc index f0395f5b..b43a2e7a 100644 --- a/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc +++ b/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc @@ -617,6 +617,10 @@ include::devguide:example$java/Migrating.java[tag=searchcheck,indent=0] === Views +// deprecation admonition +include::{version-common}@sdk:shared:partial$views.adoc[tag=deprecate-sdk] + + Views have stayed at the `Bucket` level, because it does not have the concept of CollectionsExample and is scoped at the bucket level on the server as well. The API has stayed mostly the same, the most important change is that `staleness` is unified under the `ViewConsistency` enum. From ec2e64d32b6f51d34366a58bebfb01ef1baa8ec5 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 22 Apr 2026 15:04:00 +0100 Subject: [PATCH 04/44] DOC-14236 hello world --> sdk-common --- antora.yml | 1 + .../hello-world/pages/start-using-sdk.adoc | 176 ++++-------------- 2 files changed, 34 insertions(+), 143 deletions(-) diff --git a/antora.yml b/antora.yml index f5668db3..8f00f9e1 100644 --- a/antora.yml +++ b/antora.yml @@ -16,6 +16,7 @@ asciidoc: java_latest_lts_version: '25' name_platform: 'Java' name_platform_lc: 'java' + lang-code: 'java' name-sdk: Java SDK sdk_api: '3.10' sdk-api-link: https://docs.couchbase.com/sdk-api/couchbase-java-client/ diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 6a0b776f..6f89aa53 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -3,91 +3,60 @@ :page-toclevels: 3 :description: Install, connect, try. A quick start guide to get you up and running with Couchbase and the {name-sdk}. :forum-link: https://www.couchbase.com/forums/c/java-sdk/5 +:complete-code-include: include::devguide:example$java/StartUsingCapella.java[] +// implementation 'com.couchbase.client:java-client:{sdk_current_version}' :page-partial: // Note to editors // // This page pulls in content from -// https://github.com/couchbase/docs-sdk-common/blob/release/7.6/modules/shared/partials/start-using-sdk.adoc +// https://github.com/couchbase/docs-sdk-common/blob/api/3.10/modules/shared/partials/start-using-sdk.adoc // // and code samples from -// https://github.com/couchbase/docs-sdk-java/tree/release/3.8/modules/devguide/examples/java +// https://github.com/couchbase/docs-sdk-java/tree/release/3.12/modules/devguide/examples/java // // It can be seen built at -// https://docs.couchbase.com/java-sdk/3.8/hello-world/start-using-sdk.html +// https://docs.couchbase.com/java-sdk/3.12/hello-world/start-using-sdk.html + [abstract] {description} +// intro +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=intro] -Couchbase has a simple interface for creating and modifying records in a document, -based upon the *collection* into which the documents are organized. -You can read more about data modeling <>, -but first let's look at those data operations, and installing the {name-sdk}. - -// remember to add a nomenclature note to the next version of this page for LCB. +// upsert snippet .Upsert with Replication set to xref:concept-docs:data-durability-acid-transactions.adoc#durable-writes[Majority Durablity]: - [source,java] ---- collection.upsert("my-document", JsonObject.create().put("doc", true), upsertOptions().durability(DurabilityLevel.MAJORITY)); ---- -`upsert` inserts (creates) the document if it does not exist, or replaces it if it does. -We'll explore creating and retrieving data records in more detail <> -(and touch lightly upon a little of Java's functional programming approach as we go), -after walking through a quick installation. -TIP: This page walks you through a quick installation, and CRUD examples against the Data Service. -Elsewhere in this section you can find a fully worked-through xref:hello-world:sample-application.adoc[] and, -for those new to document (NoSQL) databases, our xref:hello-world:student-record-developer-tutorial.adoc[Student Record Tutorial]. +// intro-upsert +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=intro-upsert] -== Before You Start +// TIP - DEE tutoral & Student record tutorial +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=other-tutorials] -Couchbase Capella, our Database-as-a-Service, lets you get on with what matters, while we take care of the administration for you. -Alternately, if you need to control every aspect of deployment -- -or just want to run the Server in a VM on your laptop -- -there are several self-managed options available: -[tabs] -==== -Couchbase Capella:: -+ --- -If you haven't already got a cluster set up, the easiest route is to https://cloud.couchbase.com/sign-up[sign up to Couchbase Capella and deploy a free tier cluster^], -then come back to this page. -Make a note of the xref:cloud:get-started:connect.adoc[endpoint] to connect to, -and remember the credentials for the user that you set up. --- -Self-Managed Couchbase Server:: -+ --- -Install Couchbase Server locally, or in your private Cloud: - -* xref:{version-server}@server:install:get-started.adoc[Deployment overview] -* xref:{version-server}@server:install:getting-started-docker.adoc[Docker Install] -* xref:operator::overview.adoc[Couchbase Autonomous Operator] -** xref:operator::install-kubernetes.adoc[Kubernetes] -** xref:operator::install-openshift.adoc[Openshift] -* xref:{version-server}server:cloud:couchbase-cloud-deployment.adoc[Cloud Marketplace]: -** xref:{version-server}@server:cloud:couchbase-aws-marketplace.adoc[AWS Marketplace] -** xref:{version-server}@server:cloud:couchbase-azure-marketplace.adoc[Azure Marketplace] -** xref:{version-server}@server:cloud:couchbase-gcp-cloud-launcher.adoc[GCP Marketplace] - -For the example code below to run, you'll need the username and password of the Administrator user that you create, and the IP address of at least one of the nodes of the cluster. --- -==== +== Before You Start +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=before] + +w // Script the docs! // Can any of the SDK installations be scripted? + + === Prerequisites * The Java SDK is tested against LTS versions of Oracle JDK and OpenJDK -- @@ -95,41 +64,10 @@ see the xref:project-docs:compatibility.adoc#jdk-compat[compatibility docs]. + https://adoptium.net/[OpenJDK {java_latest_lts_version} with HotSpot JVM] is recommended. -The code examples also assume: - -[tabs] -==== -Couchbase Capella:: -+ --- -* You have signed up to https://cloud.couchbase.com/sign-up[Couchbase Capella]. - -* You have created your own bucket, or loaded the Travel Sample dataset. -Note, the Travel Sample dataset is installed automatically when deploying a Capella free tier cluster. - -* A user is created with permissions to access the cluster (at least Application Access permissions). -See the xref:cloud:get-started:cluster-and-data.adoc#credentials[Capella connection page] for more details. - -IMPORTANT: Couchbase Capella uses xref:cloud:organizations:organization-projects-overview.adoc[Roles] to control user access to cluster resources. -For the purposes of this guide, you can use the *Organization Owner* role automatically assigned to your account during installation of the Capella cluster. -In production, Couchbase strongly recommends setting up users with more granular access roles as a best practice for data security. --- -Self-Managed Couchbase Server:: -+ --- -* xref:{version-server}@server:getting-started/do-a-quick-install.adoc[Couchbase Server] is installed and accessible locally. +// self-managed + Capella pre-reqs +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=prereq] -* You have created your own bucket, or loaded the Travel Sample dataset using the xref:{version-server}@server:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-ui[Web interface]. - -* A user is created with permissions to access your cluster (at least Application Access permissions). -See xref:{version-server}@server:manage:manage-security/manage-users-and-roles.adoc[Manage Users, Groups and Roles] for more details. - -IMPORTANT: Couchbase Server uses xref:{version-server}@server:learn:security/roles.adoc[Role-Based Access Control (RBAC)] to control access to cluster resources. -In this guide we suggest using the *Full Admin* role created during setup of your local Couchbase Server cluster. -In production, Couchbase strongly recommends setting up users with more granular access roles as a best practice for data security. --- -==== == Installation @@ -173,28 +111,15 @@ implementation 'com.couchbase.client:java-client:{sdk_current_version}' ==== // end::quick-install[] + === IDE Plugins -To make development easier, Couchbase plugins are available for VSCode and the IntelliJ family of IDEs and editors. -For links and more information on these and other integrations across the {name_platform} ecosystem, -check out the xref:project-docs:third-party-integrations.adoc[] page. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=ide] === Grab the Code -If you're all set up and in a real hurry, just grab this code sample and add in your Capella details. - -.Complete Hello World code sample [*Click to open or collapse the listing*] -[%collapsible] -==== -.... -include::devguide:example$java/StartUsingCapella.java[] -.... -==== - -Otherwise, read on as we introduce the CRUD API and connection to Capella or self-managed Couchbase Server. - -TIP: There's a *View* link to the complete sample code on GitHub above each of the snippets on these SDK pages, and a *Copy* icon to grab just the snippet shown. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=complete-code] == Connect to your Database @@ -233,7 +158,7 @@ Cloud Native Gateway (CNG):: Couchbase's large number of ports across the URLs of many services can be proxied by using a `couchbase2://` endpoint as the connection string -- currently only compatible with recent versions of xref:operator:ROOT:concept-cloud-native-gateway.adoc[Couchbase Autonomous Operator]: -[source,scala] +[source,java] ---- Cluster cluster = Cluster.connect( "couchbase2://10.12.14.16", @@ -262,12 +187,7 @@ quarkus.couchbase.password=password -- ==== - -For a deeper look at connection options, read xref:howtos:managing-connections.adoc[]. - -TIP: The connection code for getting started uses the Administrator password that you were given during set up. -In any production app you should create a role restricted to the permissions needed for your app -- -more on this in xref:concept-docs:best-practices.adoc#roles-and-rbac[the Security documentation]. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=deeper-conn] The `ClusterEnvironment.Builder` is covered more fully on the xref:ref:client-settings.adoc#the-environment-builder[Client Settings] page. @@ -318,13 +238,13 @@ include::devguide:example$java/StartUsingCapella.java[tag=collection,indent=0] == Create, Read, Update, Delete -Couchbase documents are organized into buckets, scopes, and collections. -https://en.wikipedia.org/wiki/CRUD[CRUD operations^] -- Create, Read, Update, Delete -- can be performed upon documents in a collection. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=crud] + === JSON We'll create a snippet of JSON to work with, using the client's own JSON library, -but you can read about the Scala SDK's support for other JSON libraries on the +but you can read about the {name-sdk}'s support for other JSON libraries on the xref:howtos:json.adoc[] page. [source,java] @@ -352,7 +272,7 @@ include::devguide:example$java/StartUsingCapella.java[tag=upsert,indent=0] The `get` method reads a document from a collection. // If the collection does not have a document with this ID, the `get` method also throws `DocumentNotFoundException`. -Wrapping the method in a `Try` / `Catch` is a good way to handle exceptions: +Wrapping the method in a `try` / `catch` is a good way to handle exceptions: [source,java] ---- @@ -433,29 +353,13 @@ try { } ---- -Like `replace`, `remove` also optionally takes the CAS value if you want to make sure you are only removing the document if it hasn’t changed since you last fetched it. +Like `replace`, `remove` also optionally takes the xref:howtos:kv-operations.adoc#what-is-cas[CAS value] if you want to make sure you are only removing the document if it hasn’t changed since you last fetched it. == Data Modeling -Documents are organized into collections -- collections of documents that belong together. -You get to decide what it means to "belong." -Developers usually put documents of the same type in the same collection. - -For example, imagine you have two types of documents: customers and invoices. -You could put the customer documents in a collection called `customers`, and the invoice documents in a collection called `invoices`. - -Each document belongs to exactly one collection. -A document's ID is unique _within_ the collection. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=data-model] -Different scopes can hold collections with different names. -There is no relationship between collections in different scopes. -Each collection belongs to just one scope and -a collection's name is unique within the scope. - - -More details can be found on the xref:concept-docs:data-model.adoc[Data Model page]. -// The xref:student-record-developer-tutorial.adoc[Student Records Tutorial] gives an introduction to data modeling in a document database alongside using the {name-sdk}. == What Next? @@ -467,18 +371,4 @@ both //// - -=== Help and Troubleshooting - -* xref:howtos:troubleshooting-cloud-connections.adoc[Troubleshooting common network problems]. -* {forum-link}[Help forum]. -* https://discord.com/channels/915294689681362954/1217642561645318194[Discord channel]. -* Read the xref:howtos:error-handling.adoc[error handling page]. -* xref:cloud:get-started:capella-iq/get-started-with-iq.adoc#generate-sdk-code-preview[Get help from Couchbase iQ]. - -=== Next Steps - -// * Take a look at the xref:hello-world:sample-application.adoc[]. -* xref:concept-docs:data-durability-acid-transactions.adoc[Learn more about the Data Service]. -* xref:concept-docs:querying-your-data.adoc[Discover SQL++] -- our SQL-family querying language. -* Explore some of the xref:project-docs:third-party-integrations.adoc[third party integrations] with Couchbase and the {name_platform} SDK, across the {name_platform} ecosystem. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=what-next] From d19e8ecfcfe98caee8390fcb26b2040321a708ee Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 22 Apr 2026 15:19:11 +0100 Subject: [PATCH 05/44] DOC-11699 de-confusing --- modules/howtos/pages/error-handling.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/howtos/pages/error-handling.adoc b/modules/howtos/pages/error-handling.adoc index a376f205..3a593844 100644 --- a/modules/howtos/pages/error-handling.adoc +++ b/modules/howtos/pages/error-handling.adoc @@ -35,7 +35,7 @@ All the specifics are discussed below, but a broad categorization of exceptions For example, if you perform an `insert` operation and the document already exists, the SDK will fail the operation with a `DocumentExistsException`. 2. Failures in all other cases, especially during pre-dispatch and dispatch, will result in either a `TimeoutException` or a `RequestCanceledException`. -=== The Ubiquitous TimeoutException +=== TimeoutException -- Ambiguous or Unambiguous The one exception that you are inevitably going to hit is the `TimeoutException`, or more specifically its child implementations the `UnambiguousTimeoutException` and the `AmbiguousTimeoutException`. From ee4980e816e778a2a795da7fc86a51c1db8122e5 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 22 Apr 2026 16:47:57 +0100 Subject: [PATCH 06/44] tweaks for getting started --- modules/hello-world/pages/start-using-sdk.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 6f89aa53..187f760d 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -51,7 +51,7 @@ include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=other-tuto include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=before] -w + // Script the docs! // Can any of the SDK installations be scripted? From 4e7624c79a89bf5397665fc67d97037c2c4d2b2a Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 28 Apr 2026 10:11:26 +0100 Subject: [PATCH 07/44] release notes for Java SDK 3.6.4! --- .../project-docs/pages/sdk-release-notes.adoc | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index 4a75ab2b..1b9a2711 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -1033,6 +1033,45 @@ Adds support for base64-encoded vectors in `VectorQuery`. == Java SDK 3.6 Releases +=== Version 3.6.4 (26 April 2026) + +This is a maintenance release. + +https://packages.couchbase.com/clients/java/3.6.4/Couchbase-Java-Client-3.6.4.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.6.4/index.html[API Reference] | +http://docs.couchbase.com/sdk-api/couchbase-core-io-2.6.4/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.3** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Couchbase Version | Built Against | API Stability +| `tracing-opentelemetry` | 1.4.2 | OpenTelemetry 1.31.0 | Committed +| `tracing-opentracing` | 1.4.2 | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | 0.6.2 | OpenTelemetry 1.31.0 | Volatile +| `metrics-micrometer` | 0.6.2 | Micrometer 1.10.9 | Volatile +|======================= + +==== Improvements + +* https://issues.couchbase.com/browse/JVMCBC-1729[JVMCBC-1729]: +This release allows configuration of a socket option, `TCP_USER_TIMEOUT`, which configures the OS to detect dead TCP connections more quickly than waiting for a global OS-level TCP timeout. +The default for this option is 20 seconds. +The default may be overridden to a value between 1 and 120 seconds using the `io.tcpUserTimeout` setting in `ClusterEnvironment`. +For example, on the `ClusterEnvironment.Builder`, you would call `.ioConfig(io -> io.tcpUserTimeout(Duration.ofSeconds(30))` to set the timeout to 30 seconds. ++ +Please note that this setting only propagates to the OS on Linux when the default epoll transport is used. +On all other platforms, the OS-configured time is used (and you need to tune it there if you want to customize the default behavior). ++ +This change is a backport of a change originally targeted to the 3.12 release. + + === Version 3.6.3 (19 August 2024) This is a regular maintenance release. From b8fb08214f64d04da133dd268829bc3d730e0525 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 28 Apr 2026 13:53:36 +0100 Subject: [PATCH 08/44] unwanted deletia --- modules/hello-world/pages/sdk-authentication.adoc | 5 ----- modules/hello-world/partials/alpha-warning.adoc | 9 --------- modules/hello-world/partials/beta-warning.adoc | 9 --------- 3 files changed, 23 deletions(-) delete mode 100644 modules/hello-world/pages/sdk-authentication.adoc delete mode 100644 modules/hello-world/partials/alpha-warning.adoc delete mode 100644 modules/hello-world/partials/beta-warning.adoc diff --git a/modules/hello-world/pages/sdk-authentication.adoc b/modules/hello-world/pages/sdk-authentication.adoc deleted file mode 100644 index b1bfb6e2..00000000 --- a/modules/hello-world/pages/sdk-authentication.adoc +++ /dev/null @@ -1,5 +0,0 @@ - - - - -:page-aliases: sdk-authentication-overview diff --git a/modules/hello-world/partials/alpha-warning.adoc b/modules/hello-world/partials/alpha-warning.adoc deleted file mode 100644 index a0b5844e..00000000 --- a/modules/hello-world/partials/alpha-warning.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Required attributes: -[WARNING] -==== -These pages cover the _Alpha_ of the Couchbase Java SDK. -As such they are likely to change without notice. -This alpha code _should not_ be used in production. - -Documentation is incomplete, subject to change, and likely to contain broken links. -==== diff --git a/modules/hello-world/partials/beta-warning.adoc b/modules/hello-world/partials/beta-warning.adoc deleted file mode 100644 index 7bd1139e..00000000 --- a/modules/hello-world/partials/beta-warning.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Required attributes: -[WARNING] -==== -These pages cover the _Beta_ release of the Couchbase Java SDK. -The API interface is stable, but could change for bug fixes during the Beta process. -New features are likely to be added. - -Documentation is incomplete, subject to change, and could contain broken links. -==== From 7990222677a3ce42252ec6fc9dbb4542b3a5a9c5 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 29 Apr 2026 18:07:40 +0100 Subject: [PATCH 09/44] backport releases added --- .../project-docs/pages/sdk-release-notes.adoc | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index 4a75ab2b..d38d0d1c 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -1033,6 +1033,50 @@ Adds support for base64-encoded vectors in `VectorQuery`. == Java SDK 3.6 Releases +=== Version 3.6.4 (26 April 2026) + +This is a maintenance release. + +https://packages.couchbase.com/clients/java/3.6.4/Couchbase-Java-Client-3.6.4.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.6.4/index.html[API Reference] | +http://docs.couchbase.com/sdk-api/couchbase-core-io-2.6.4/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.3** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Couchbase Version | Built Against | API Stability +| `tracing-opentelemetry` | 1.4.4 | OpenTelemetry 1.31.0 | Committed +| `tracing-opentracing` | 1.4.4 | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | 0.6.4 | OpenTelemetry 1.31.0 | Volatile +| `metrics-micrometer` | 0.6.4 | Micrometer 1.10.10 | Volatile +|======================= + +==== Improvements + +* https://issues.couchbase.com/browse/JVMCBC-1729[JVMCBC-1729]: +When running on Linux, the SDK now sets the `TCP_USER_TIMEOUT` socket option so it can detect dead connections more quickly. +By default, the SDK sets the timeout to 20 seconds. +You can override the default by configuring the new `io.tcpUserTimeout` client setting. +For example, to set the timeout to 30 seconds you would configure the `ClusterEnvironment.Builder` like this: ++ +[source,java] +---- +env.ioConfig(io -> io.tcpUserTimeout(Duration.ofSeconds(30))) +---- ++ +Thank you to community member Omer Cilingir for this contribution. ++ +NOTE: This is a backport of a feature from version 3.12.0. +It is not present in SDK versions before 3.12.0 unless mentioned in the release notes. + + === Version 3.6.3 (19 August 2024) This is a regular maintenance release. @@ -1222,6 +1266,50 @@ Previously, the SDK assumed `1` was the default value, and omitted the parameter == Java SDK 3.5 Releases +=== Version 3.5.4 (27 April 2026) + +This is a maintenance release. + +https://packages.couchbase.com/clients/java/3.5.4/Couchbase-Java-Client-3.5.4.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.5.4/index.html[API Reference] | +http://docs.couchbase.com/sdk-api/couchbase-core-io-2.5.4/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.5.8** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Couchbase Version | Built Against | API Stability +| `tracing-opentelemetry` | 1.3.4 | OpenTelemetry 1.31.0 | Committed +| `tracing-opentracing` | 1.3.4 | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | 0.5.4 | OpenTelemetry 1.31.0 | Volatile +| `metrics-micrometer` | 0.5.4 | Micrometer 1.10.9 | Volatile +|======================= + +==== Improvements + +* https://issues.couchbase.com/browse/JVMCBC-1729[JVMCBC-1729]: +When running on Linux, the SDK now sets the `TCP_USER_TIMEOUT` socket option so it can detect dead connections more quickly. +By default, the SDK sets the timeout to 20 seconds. +You can override the default by configuring the new `io.tcpUserTimeout` client setting. +For example, to set the timeout to 30 seconds you would configure the `ClusterEnvironment.Builder` like this: ++ +[source,java] +---- +env.ioConfig(io -> io.tcpUserTimeout(Duration.ofSeconds(30))) +---- ++ +Thank you to community member Omer Cilingir for this contribution. ++ +NOTE: This is a backport of a feature from version 3.12.0. +It is not present in SDK versions before 3.12.0 unless mentioned in the release notes. + + === Version 3.5.3 (6 February 2024) This is a regular maintenance release. From de6e56c4c0cec250fe5c051cda3eabc69a99ff77 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 20 May 2026 14:28:37 +0100 Subject: [PATCH 10/44] DOC-14238 --- modules/project-docs/pages/sdk-release-notes.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index f438fe47..8f3ac6dd 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -8,15 +8,15 @@ [abstract] {description} -These pages cover the 3._x_ versions of the Couchbase Java SDK. -For release notes, download links, and installation methods for 2.7 and earlier releases of the Couchbase Java Client, please see the https://docs-archive.couchbase.com/java-sdk/2.7/sdk-release-notes.html[2.x Java Release Notes & Download Archive]. +include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=intro] -=== Installation -See the xref:project-docs:sdk-full-installation.adoc[Full Installation] guide for details. +=== Installation +include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=installation-moved] -include::{version-common}@sdk:pages:partial$signed.adoc[tag=signed] +// JVM signed +include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=signed] // tag::all[] @@ -3756,5 +3756,5 @@ Numerous _Alpha_ and _Beta_ releases were made in the run-up to the 3.0 release, == Older Releases -Although https://www.couchbase.com/support-policy/EOL/[no longer supported], documentation for older releases continues to be available in our https://docs-archive.couchbase.com/home/index.html[docs archive]. +include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=older] // end::all[] From 09194556bca11b4882f3a1b437a4e0088f0508dd Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 20 May 2026 15:30:55 +0100 Subject: [PATCH 11/44] 3,12 & 3.13 --- modules/project-docs/pages/sdk-release-notes.adoc | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index 8f3ac6dd..f5163796 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -23,13 +23,13 @@ include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=signed] [#latest-release] -== Java SDK 3.12 Releases +== Java SDK 3.13 Releases We always recommend using the latest version of the SDK -- it contains all of the latest security patches and support for new and upcoming features. All patch releases for each dot minor release should be API compatible, and safe to upgrade; any changes to expected behavior are noted in the release notes that follow. -Version 3.11 of the Java SDK implements the 3.9 xref:compatibility.adoc#api-version[SDK API]. +Version {sdk_dot_minor} of the Java SDK implements the {sdk-api} xref:compatibility.adoc#api-version[SDK API]. See the xref:compatibility.adoc#couchbase-feature-availability-matrix[compatibility pages] for more information on feature compatibility with different versions of Couchbase Server. @@ -51,6 +51,13 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea // and comment out in 3.11 + + + + +== Java SDK 3.12 Releases + + === Version 3.12.0 (??????? 2026) https://packages.couchbase.com/clients/java/3.12.0/Couchbase-Java-Client-3.12.0.zip[Download] | From 0a68053cb0d50727c03aea51f69061f7090f9021 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Thu, 21 May 2026 14:38:32 +0100 Subject: [PATCH 12/44] Better wording --- modules/hello-world/pages/overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/hello-world/pages/overview.adoc b/modules/hello-world/pages/overview.adoc index 733f2cea..0f03b342 100644 --- a/modules/hello-world/pages/overview.adoc +++ b/modules/hello-world/pages/overview.adoc @@ -27,7 +27,7 @@ xref:project-docs:sdk-release-notes.adoc[] | {sdk-gh-link}[{name-sdk} source code] -What's the point of a fast and scalable database if it's not easy to develop for? +A fast and scalable database is even better when it's easy to develop for. Couchbase gives you the {name_platform} APIs to work with Capella, our managed solution, or self-managed options in your private Cloud or datacenter. From be581af1c6faab1976ce70fc8de3300c298d79d2 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Thu, 4 Jun 2026 16:30:14 +0100 Subject: [PATCH 13/44] JVM 3.12 releases --- .../project-docs/pages/sdk-release-notes.adoc | 66 ++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index f5163796..bfd059bc 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -58,20 +58,84 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea == Java SDK 3.12 Releases -=== Version 3.12.0 (??????? 2026) + +=== Version 3.12.0 (02 June 2026) https://packages.couchbase.com/clients/java/3.12.0/Couchbase-Java-Client-3.12.0.zip[Download] | https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.0/index.html[API Reference] | https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.0/[Core API Reference] +The supported and tested dependencies for this release are: +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** +Optional artifacts on top of this SDK version are tested for the following compatibilities: +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= +==== Improvements +* https://jira.issues.couchbase.com/browse/JVMCBC-1722[JVMCBC-1722]: +Simplified the transaction protocol implementation, and changed the threading model to make it easier to reason about thread safety. As a happy side effect, internal performance testing shows improved transaction throughput and latency for some workloads. ++ +TIP: Developers using the SDK's reactive transaction API may see an increase in the number of threads spawned by the SDK, because each operation is now executed on its own dedicated thread. For high-concurrency transactions running on Java 21 and later, we recommend using the blocking API and virtual threads. + +* https://jira.issues.couchbase.com/browse/JCBC-1739[JCBC-1739]: +When inserting or replacing a document inside a transaction, it is now possible to specify an expiration time for the document. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1729[JVMCBC-1729]: +When running on Linux, the SDK now sets the `TCP_USER_TIMEOUT` socket option so it can detect dead connections more quickly. +By default, the SDK sets the timeout to 20 seconds. +You can override the default by configuring the new `io.tcpUserTimeout` client setting. +For example, to set the timeout to 30 seconds you would configure the `ClusterEnvironment.Builder` like this: ++ +[source,java] +---- +env.ioConfig(io -> io.tcpUserTimeout(Duration.ofSeconds(30))) +---- ++ +Thank you to community member Omer Cilingir for this contribution. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1732[JVMCBC-1732]: +Improved the error message when a Full-Text Search request fails due to insufficient user permissions. The message now indicates the cause of the failure, instead of "Request failed, but no more information available". + +* https://jira.issues.couchbase.com/browse/JVMCBC-1725[JVMCBC-1725]: +Added the `db.system.name` attribute to `OpenTelemetry` spans. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1735[JVMCBC-1735], https://jira.issues.couchbase.com/browse/JVMCBC-1736[JVMCBC-1736]: +Hardened the code that handles cluster topology changes. +Improved the diagnostics in this critical area by adding a limited number of new `INFO` log messages that describe topology changes. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1731[JVMCBC-1731]: +Added a new `DEBUG` log message that shows the options used for socket connections. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1733[JVMCBC-1733]: +Upgraded to `Netty` `4.2.14`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1734[JVMCBC-1734]: +Upgraded to `Jackson `2.21.4`. + +==== Bug Fixes +* https://jira.issues.couchbase.com/browse/JVMCBC-1738[JVMCBC-1738]: +Ignoring the result rows of a reactive query no longer causes future queries to time out. +* https://jira.issues.couchbase.com/browse/JCBC-2216[JCBC-2216]: +`EventingFunctionManager.functionsStatus()` no longer throws an exception if a function is in the `"resuming"` state. +The `EventingFunctionStatus` enum has two new values: `RESUMING` and `UNKNOWN` (a special value indicating the SDK did not recognize the status code returned by the server). +* https://jira.issues.couchbase.com/browse/JVMCBC-1728[JVMCBC-1728]: +The durations reported by some transaction diagnostic messages are no longer inflated by a factor of 1,000,000. +This bug had no effect on the SDK’s behavior, but could mislead developers reading the logs. From 0527119983f1073b338350caa8044eca75bd4e7b Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Mon, 8 Jun 2026 10:53:35 +0100 Subject: [PATCH 14/44] Add new API and improve transaction protocol Forward porting https://github.com/couchbase/docs-sdk-java/pull/491 --- modules/project-docs/pages/sdk-release-notes.adoc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index bfd059bc..d74ba1ff 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -82,6 +82,15 @@ Optional artifacts on top of this SDK version are tested for the following compa | `metrics-micrometer` | Micrometer 1.12.9 | Volatile |======================= + +==== New features + +* https://jira.issues.couchbase.com/browse/JCBC-2214[JCBC-2214]: +Adds a new API to `Collection`, `getOrNull`. +This behaves identically to the regular Key-Value get call except that if the document does not exist then null is returned rather than an exception being raised, +avoiding the slight overhead of exception creation on JVM platforms. +In addition, when `OpenTelemetry` is being used an exception is not attached to the span in that case. + ==== Improvements * https://jira.issues.couchbase.com/browse/JVMCBC-1722[JVMCBC-1722]: From 0a75069b1c1c650453971ac4ffc615ed32b19a88 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Thu, 9 Jul 2026 10:10:09 +0100 Subject: [PATCH 15/44] 3.12.1 updates --- .../project-docs/pages/sdk-release-notes.adoc | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index bfd059bc..950769ad 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -58,6 +58,55 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea == Java SDK 3.12 Releases +=== Version 3.12.1 (08 July 2026) + +https://packages.couchbase.com/clients/java/3.12.1/Couchbase-Java-Client-3.12.1.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.1/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.1/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + +==== Improvements + +* https://jira.issues.couchbase.com/browse/JVMCBC-1739[JVMCBC-1739]: +Low-information topology changes are now logged at `DEBUG` level instead of `INFO`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1746[JVMCBC-1746]: +Upgraded to Netty `4.2.16`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1750[JVMCBC-1750]: +Upgraded to Jackson `2.21.5`. + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1740[JVMCBC-1740]: +Fixed a regression in `3.11.0` that could cause an uneven distribution of network channels to event loops. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1749[JVMCBC-1749]: +Fixed a regression in `3.12.0` that prevented Spring Data Couchbase from executing transactions. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1744[JVMCBC-1744]: +Fixed a bug in the `couchbase2` protocol that caused the SDK to throw a generic `CouchbaseException` instead of `DocumentNotLockedException`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1748[JVMCBC-1748]: +Fixed an issue where in some cases the SDK would continue trying to connect to a node that was removed from the cluster. + + === Version 3.12.0 (02 June 2026) From c5834c368da9a022e316abe2e7b2dc8c6107fa40 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 28 Jul 2026 13:30:22 +0100 Subject: [PATCH 16/44] Feature signposting --- modules/hello-world/pages/overview.adoc | 18 +++++ modules/project-docs/pages/compatibility.adoc | 1 + modules/project-docs/pages/deployment.adoc | 66 +++++++++++++++++++ 3 files changed, 85 insertions(+) diff --git a/modules/hello-world/pages/overview.adoc b/modules/hello-world/pages/overview.adoc index 0f03b342..1a300da2 100644 --- a/modules/hello-world/pages/overview.adoc +++ b/modules/hello-world/pages/overview.adoc @@ -203,4 +203,22 @@ Useful resources to help support your development experience with Couchbase and ++++ + +{empty} + + + +{empty} + + + + +== icon:code[] Couchbase Operational Cluster Feature Compatibility + +include::project-docs:deployment.adoc[tag=feature-compat] + + + +{empty} + + + + include::{version-common}@sdk:shared:partial$columnar-available.adoc[tag=initial-availability-o] diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc index 7ad6e23b..237a0919 100644 --- a/modules/project-docs/pages/compatibility.adoc +++ b/modules/project-docs/pages/compatibility.adoc @@ -209,6 +209,7 @@ include::{version-common}@sdk:shared:partial$capella.adoc[tag=cloud] ① As part of the standard SDK {sqlpp} API, it should be compatible with all earlier versions of the SDK -- but it has not been tested. This table is not an exhaustive list -- just a few highlights -- provided to help assess compatibility of older versions in particular. +For a slightly fuller table, see the xref:deployment.adoc#couchbase-operational-cluster-feature-compatibility[Deployment page]. For alignment of SDKs and new Server features, scroll down to the information below the <>. diff --git a/modules/project-docs/pages/deployment.adoc b/modules/project-docs/pages/deployment.adoc index 05a16ecc..3e114bb6 100644 --- a/modules/project-docs/pages/deployment.adoc +++ b/modules/project-docs/pages/deployment.adoc @@ -65,6 +65,72 @@ This section also contains information on xref:migrating-sdk-code-to-3.n.adoc[mi // :migration-link: for 4.x pages?? + + + +== Couchbase Operational Cluster Feature Compatibility + +// tag::feature-compat[] +All of the SDKs have API compatibility with most of the features in Couchbase Operational Clusters -- +whether self-managed, or Capella. +The following table covers possible exceptions, and gives the version of the {name-sdk} and Couchbase Server with which some features were introduced. + + +.Couchbase Server and SDK Supported Version Matrix +[.table-merge-cells] +[cols="8,5,5,5"] +|=== +| | Server 7.2 | Server 7.6.x | Server 8.0 + +| KV Range Scan +| N/A +2+| From 3.4.1 + +| Zone aware replica reads +| N/A +2+| From 3.6.0 + +| Vector Search with Search Vector Index +| N/A +2+| From 3.6.0 + +| Vector Query using Hyperscale Vector Index +2+| N/A +| From SDK 3.9.0 ① + +| Vector Query using Composite (GSI & vector) index +2+| N/A +| From SDK 3.9.0 ① + +| Distributed ACID Transactions +3+| From 3.0.0 + +| DNS SRV refresh for serverless environments (AWS Lambda, Azure Functions, and GCP Functions) +3+| From 3.4.0 + +| Circuit Breakers +3+| From 3.0.0 + +| Response Time Observability with OTel +3+| From 3.0.7 + +| Field Level Encryption +3+| From 2.6.0 + +| Cloud Native Gateway +3+| From 3.5.0 +|=== + +<1> As part of the standard SDK {sqlpp} API, it should be compatible with all earlier versions of the SDK -- but it has not been tested. +// end::feature-compat[] + + + + + + + + == Further Reading * Integrate Couchbase with your data ecosystem: From e1d61df1c1d5c08fc87d21f26d6b98a871a6dedb Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 28 Jul 2026 14:09:11 +0100 Subject: [PATCH 17/44] Feature signposting --- modules/hello-world/pages/overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/hello-world/pages/overview.adoc b/modules/hello-world/pages/overview.adoc index 1a300da2..b59ca64f 100644 --- a/modules/hello-world/pages/overview.adoc +++ b/modules/hello-world/pages/overview.adoc @@ -17,7 +17,7 @@ = Couchbase {name-sdk} {sdk_dot_minor} -The Couchbase {name-sdk} allows {name_platform} applications to access a Couchbase cluster -- +The Couchbase {name-sdk} allows {name_platform} applications to access a Couchbase operational cluster -- Capella or self-managed. // -- other SDKs are available for Couchbase Lite (edge or mobile devices) and Capella Columnar (real-time analytics) From a0c1ee4eac04ebf5994c4335e634aaf9e1f7aecf Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Fri, 14 Aug 2026 15:04:36 +0100 Subject: [PATCH 18/44] forward porting recent changes --- modules/hello-world/pages/platform-help.adoc | 6 ++-- .../hello-world/pages/start-using-sdk.adoc | 2 +- modules/howtos/pages/error-handling.adoc | 2 ++ .../howtos/pages/view-queries-with-sdk.adoc | 2 +- modules/project-docs/pages/compatibility.adoc | 29 +++++++++++-------- .../pages/migrating-sdk-code-to-3.n.adoc | 5 ++-- .../pages/sdk-full-installation.adoc | 4 +-- pom.xml | 7 +++++ 8 files changed, 36 insertions(+), 21 deletions(-) diff --git a/modules/hello-world/pages/platform-help.adoc b/modules/hello-world/pages/platform-help.adoc index 8c921ef6..623b975f 100644 --- a/modules/hello-world/pages/platform-help.adoc +++ b/modules/hello-world/pages/platform-help.adoc @@ -34,16 +34,16 @@ To install the JDK we are going to use a JVM-management tool called `sdkman`. === SDKMAN! -SDKMAN! -- the Software Development Kit Manager -- enables multiple Java versions and runtimes to be installed and managed, without intefering with your system's default JVM. +SDKMAN! -- the Software Development Kit Manager -- enables multiple Java versions and runtimes to be installed and managed, without interfering with your system's default JVM. This third party tool is unnecessary in most production environments, but ideal for development machines. Installation instructions can be found on the https://sdkman.io/install[SDKMAN! website]. -Once SDKMAN! is installed, use it to install the latest version of Java: +Once SDKMAN! is installed, use it to install the latest stable version of Java: [source,console] ---- -$ sdk install java 23.0.2-oracle +$ sdk install java ---- You may be prompted to set that version as a default -- say yes (by pressing **). diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 187f760d..14173f3e 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -59,7 +59,7 @@ include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=before] === Prerequisites -* The Java SDK is tested against LTS versions of Oracle JDK and OpenJDK -- +* The Java SDK is tested against LTS versions of OpenJDK -- see the xref:project-docs:compatibility.adoc#jdk-compat[compatibility docs]. + https://adoptium.net/[OpenJDK {java_latest_lts_version} with HotSpot JVM] is recommended. diff --git a/modules/howtos/pages/error-handling.adoc b/modules/howtos/pages/error-handling.adoc index 3a593844..a14067e1 100644 --- a/modules/howtos/pages/error-handling.adoc +++ b/modules/howtos/pages/error-handling.adoc @@ -2,11 +2,13 @@ :description: Errors are inevitable. That's why the SDK has very extensive error handling and retry capabilties :navtitle: Handling Errors :page-aliases: ROOT:handling-error-conditions.adoc,handling-error-conditions.adoc,errors.adoc,handling-errors.adoc +:page-toclevels: 2 [abstract] {description} which are focussed on one goal: keeping your application available as best as possible even in the face of (transient) failures. + Unfortunately, the SDK alone can't make all the decisions needed since it lacks the understanding of your application domain. In most cases transparent retry is the best choice, but maybe sometimes you need to fail quickly and switch over to an alternate data source. On this page you will learn about basic and advanced error handling mechanisms, as well as the fundamentals that hold them all together. diff --git a/modules/howtos/pages/view-queries-with-sdk.adoc b/modules/howtos/pages/view-queries-with-sdk.adoc index 3f19b4f5..a9c42374 100644 --- a/modules/howtos/pages/view-queries-with-sdk.adoc +++ b/modules/howtos/pages/view-queries-with-sdk.adoc @@ -31,7 +31,7 @@ CAUTION: If you are provisioning Views on Couchbase Server for a legacy applicat xref:{version-server}@server:learn:buckets-memory-and-storage/storage-engines.adoc#couchstore[couchstore] bucket_. -We will maintain support for Views in the SDKs for so long as it can be used with a supported version of Couchbase Server. +Use of Views in the {name-sdk} is now deprecated. Information on using MapReduce Views with the SDK can still be accessed in our https://docs-archive.couchbase.com/java-sdk/3.1/howtos/view-queries-with-sdk.html[documentation archive]. diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc index 237a0919..942f426e 100644 --- a/modules/project-docs/pages/compatibility.adoc +++ b/modules/project-docs/pages/compatibility.adoc @@ -10,7 +10,7 @@ Plus notes on Cloud, networks, and AWS Lambda. {description} -The {sdk_dot_minor} SDK requires Java 8 or later to be installed. +The {sdk_dot_minor} SDK requires Java 8 or later _Java {java_latest_lts_version} is recommended_. @@ -20,21 +20,26 @@ _Java {java_latest_lts_version} is recommended_. === JDK Version Compatibility -The {name-sdk} is tested with Oracle JDK and OpenJDK. -Other JDK implementations might work but are not tested and are unsupported. -We recommend running the latest LTS version (i.e. at the time of writing JDK {java_latest_lts_version}) with the highest patch version available. +We test the {name-sdk} with https://adoptium.net/[Eclipse Temurin] versions 8, 17, 21, and 25. -The following JDK releases are supported: +The following OpenJDK releases are supported: * https://adoptium.net/[OpenJDK 25 with HotSpot JVM] (recommended) * https://adoptium.net/[OpenJDK 21 with HotSpot JVM] * https://adoptium.net/[OpenJDK 17 with HotSpot JVM] -* https://www.oracle.com/java/technologies/downloads/#jdk17[Oracle JDK 17] -* https://adoptium.net/[OpenJDK 11] (Hotspot recommended) or https://www.oracle.com/java/technologies/downloads/#jdk11[Oracle JDK 11] -* https://adoptium.net/[OpenJDK 1.8 with HotSpot JVM] -* https://www.oracle.com/java/technologies/downloads/#java8[Oracle JDK 1.8] +* https://adoptium.net/[OpenJDK 11 with HotSpot JVM] +* https://adoptium.net/[OpenJDK 8 with HotSpot JVM] -Please make sure you run on one of the latest patch releases, since they provide stability improvements and security fixes in general. +The following Oracle JDK releases are also supported but we do not do any testing with them owing to Oracle license issues: + +* https://www.oracle.com/java/technologies/downloads/#java17[Oracle JDK 17] +* https://www.oracle.com/java/technologies/downloads/#java11[Oracle JDK 11] +* https://www.oracle.com/java/technologies/downloads/#java8[Oracle JDK 8] + +Other JDK implementations might work but are untested and unsupported. + +[TIP] +Make sure to stay up to date with JDK patch releases because they provide stability improvements and security fixes. @@ -69,7 +74,7 @@ The SDK has been tested on a representative subset of the platforms listed below === Mac OS X The current and previous two releases of OS X. -At time of writing (February 2026): 26 (Tahoe), 15 (Sequoia), and 14 (Sonoma). +At time of writing (???? 2026): 26 (Tahoe), 15 (Sequoia), and 14 (Sonoma). **** The JVM SDKs should also be expected to run on other commonly-available GNU/Linux distributions which support an appropriate JDK, but not all combinations can be tested -- notable exceptions are listed below. @@ -145,7 +150,7 @@ It is best to upgrade either the SDK or the Couchbase version you are using. .Recommended SDK per Server Version Matrix [#table_sdk_versions] |=== -| | 3.4, 3.5 | 3.6, 3.7 | 3.8 | 3.9-3.11 +| | 3.4, 3.5 | 3.6, 3.7 | 3.8 | 3.9-3.13 | *Server 8.0* ① | *✔* diff --git a/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc b/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc index b43a2e7a..1cdcddad 100644 --- a/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc +++ b/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc @@ -755,8 +755,9 @@ Note that some options have been removed, and others have different ways to conf |`sslKeystoreFile` | on `CertificateAuthenticator` |`sslKeystorePassword` | on `CertificateAuthenticator` |`sslKeystore` | on `CertificateAuthenticator` -|`sslTruststoreFile` | `SecurityConfig.trustCertificate` -|`sslTruststorePassword` | `SecurityConfig.trustCertificate` +a|`sslTruststoreFile` + +`sslTruststorePassword` .^| `SecurityConfig.trustStore` |`sslTruststore` | `SecurityConfig.trustManagerFactory` |`bootstrapCarrierEnabled` | removed |`bootstrapHttpDirectPort` | via custom `SeedNode` diff --git a/modules/project-docs/pages/sdk-full-installation.adoc b/modules/project-docs/pages/sdk-full-installation.adoc index 0a937a01..cc30aff8 100644 --- a/modules/project-docs/pages/sdk-full-installation.adoc +++ b/modules/project-docs/pages/sdk-full-installation.adoc @@ -14,12 +14,12 @@ It offers synchronous APIs as well as reactive and asynchronous equivalents to m The Couchbase Java SDK 3._x_ is a complete rewrite of the 2.x API, providing a simpler surface area and adding support for Couchbase Server features like xref:concept-docs:collections.adoc[Collections and Scopes] (available in Couchbase Server 7.0+). The (reactive) API also migrated from `RxJava` to `Reactor`, along with other improvements to performance, logging, debugging and timeout troubleshooting. -If you're upgrading your application from Java SDK 2.x, please read our xref:project-docs:migrating-sdk-code-to-3.n.adoc[Migrating 2.x code to SDK 3.0 Guide]. +If you're upgrading your application from Java SDK 2.x, please read our xref:project-docs:migrating-sdk-code-to-3.n.adoc[Migrating 2.x code to SDK 3.x Guide]. == Prerequisites -The Java SDK is tested against LTS versions of Oracle JDK and OpenJDK -- see our xref:project-docs:compatibility.adoc#jdk-compat[compatibility docs]. +The Java SDK is tested against LTS versions of OpenJDK -- see our xref:project-docs:compatibility.adoc#jdk-compat[compatibility docs]. The underlying OS normally makes no difference, but library incompatibilities in Alpine Linux makes a xref:project-docs:compatibility.adoc#alpine-linux-compatibility[workaround] necessary for this OS. diff --git a/pom.xml b/pom.xml index 8f7e960a..e680bfde 100644 --- a/pom.xml +++ b/pom.xml @@ -8,6 +8,13 @@ + + com.couchbase.client + couchbase-client-bom + 3.13.0 + pom + import + io.opentelemetry opentelemetry-bom From e8e6a88b74404fd126345abe9342a8a099ec9fab Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Thu, 27 Aug 2026 13:23:40 +0100 Subject: [PATCH 19/44] DOC-14589 bulk-get --- .../concept-docs/pages/best-practices.adoc | 96 ++++++------------- .../howtos/pages/concurrent-async-apis.adoc | 3 + 2 files changed, 34 insertions(+), 65 deletions(-) diff --git a/modules/concept-docs/pages/best-practices.adoc b/modules/concept-docs/pages/best-practices.adoc index 1b2612e4..9f9282a5 100644 --- a/modules/concept-docs/pages/best-practices.adoc +++ b/modules/concept-docs/pages/best-practices.adoc @@ -7,11 +7,12 @@ // Note to editors // -// This page pulls in content from -sdk-common- +// This page pulls in content from +// https://github.com/couchbase/docs-sdk-common/blob/api/3.10/modules/shared/partials/best-practices-sdk.adoc // and code samples from -example-dir- // -// It can be seen built at wwww. - +// It can be seen built at +// https://docs.couchbase.com/java-sdk/3.13/concept-docs/best-practices.html [abstract] {description} @@ -27,84 +28,53 @@ There's plenty that can be done to remove bottlenecks in development and in perf == Security -But before worrying about bottlenecks, let's put security concerns first. +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=security] -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 + +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=rbac] -Self-managed Couchbase Server uses Role-Based Access Control (RBAC), 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. -// - - - -// concept snippet -// include::{version-common}@sdk:pages:partial$rbac.adoc[] -RBAC restrict resources on a Couchbase cluster to an identified user, allocated by role. +== Performance -==== Capella Security & Priveleges +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=performance] -Capella, our managed service, likewise has a concept of roles. -In addition to this, clusters within Capella are grouped into -xref:cloud:organizations:organization-projects-overview.adoc[organizations and projects], -to maintain separation of concerns, as well as access priveleges. +=== Dealing with Timeout Errors -==== Users, Resources, Roles, and Privileges +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=timeout-debug] -Couchbase Server Enterprise Edition uses _Role-Based Access Control_ for applications to restrict _resources_ on a Couchbase cluster to an identified _user_. +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=timeout-wait] -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. +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=timeout-more] -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. -NOTE: 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 +=== Concurrency and Async APIs -Couchbase's Data Service uses a fast binary protocol, which will always outperform JSON streamed over HTTP from {sqlpp} queries. -If you know the key (ID) of a document, then use the xref:howtos:kv-operations.adoc[Data Service]. +// ....this paragraph different for each SDK. -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. +We recommend using the reactive API over the `CompletableFuture` counterpart. +See the xref:howtos:concurrent-async-apis.adoc[Async & Reactive APIs page] for discussion and practical examples. -=== Dealing with Timeout Errors +=== Bulk Get, Multi-Get, and Network Latency -// see also -// https://couchbasecloud.atlassian.net/wiki/spaces/CST/pages/1993769712/Java+-+Debugging+KV+Timeouts -// in Support wiki +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=bulk-get] -* `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 -xref:ref:client-settings.adoc#constrained-network-environments[best timeout options for WAN environments], -or at least set a xref:ref:client-settings.adoc#wan-development[WAN development Configuration Profile]. +==== When to Use Bulk Get +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=bulk-get-async-platform] -// Something on longer timeouts and fewer retries? -// ... reading the logs to find the pattern? -// & Something on polling rate the SDK uses to fetch an updated cluster map whenever a topology change occurs. -//// -By default the Java SDK polls every 2.5 seconds, regardless of server version or SDK version. -This interval is configurable via the io.configPollInterval client setting. -https://docs.couchbase.com/java-sdk/current/ref/client-settings.html#io.configPollInterval -When Java SDK 3.5.0 or later is used with Couchbase Server 7.6 or later, the SDK also listens for config change notifications from the server. In this case the polling acts as a failsafe, so it's probably okay to set it significantly higher than 2.5 seconds. -//// // write after more LZA added //// @@ -114,14 +84,6 @@ Advanced zone aware.... //// -=== Concurrency and Async APIs - -// ....this paragraph different for each SDK. - -We recommend using the reactive API over the `CompletableFuture` counterpart. -See the xref:howtos:concurrent-async-apis.adoc[Async & Reactive APIs page] for discussion and practical examples. - - == Error Handling @@ -132,12 +94,6 @@ See also the xref:howtos:error-handling.adoc[error handling guide], which covers specific errors, along with a broader look at error handling strategies. -== Testing - -Integrate developing with the {name-sdk} into your accustomed test framework. - - - //// == General Approach to Scala Exceptions @@ -156,6 +112,8 @@ include::{version-common}@sdk:shared:partial$errors.adoc[tag=diag] + + // Slow Operations Logging include::{version-common}@sdk:shared:partial$errors.adoc[tag=observability] @@ -166,6 +124,14 @@ include::{version-common}@sdk:shared:partial$errors.adoc[tag=observability] +== Testing + +Integrate developing with the {name-sdk} into your accustomed test framework. + + + + + // Missing APIs // For anything that is not covered by the SDK, // for example diff --git a/modules/howtos/pages/concurrent-async-apis.adoc b/modules/howtos/pages/concurrent-async-apis.adoc index 4da916ee..a2d5d24a 100644 --- a/modules/howtos/pages/concurrent-async-apis.adoc +++ b/modules/howtos/pages/concurrent-async-apis.adoc @@ -85,6 +85,9 @@ In all other cases, the blocking API (for simplicity) or the reactive API (for r == Batching +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=bulk-get-sidebar] + + The SDK itself does not provide explicit APIs for batching, because using the reactive mechanisms it allows you to build batching code applied to your use case much better than a generic implementation could in the first place. While it can be done with the async API as well, we recommend using the reactive API so you can use async retry and fallback mechanisms that are supplied out of the box. From 22d35fc3bd13c41a3f1dc144c3f1842acf3095bc Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Fri, 11 Sep 2026 12:26:02 +0100 Subject: [PATCH 20/44] more 3.12.x --- .../project-docs/pages/sdk-release-notes.adoc | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index 869e7534..b8e2be01 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -54,10 +54,93 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea +[v3.13.0] +=== Version 3.13.0 (08 October 2026) + == Java SDK 3.12 Releases +[v3.12.3] +=== Version 3.12.3 (10 September 2026) + +https://packages.couchbase.com/clients/java/3.12.3/Couchbase-Java-Client-3.12.3.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.3/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.3/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + +==== Improvements + +* https://jira.issues.couchbase.com/browse/JVMCBC-1762[JVMCBC-1762]: +Returning a failed future from `RetryStrategy.shouldRetry()` now causes the request to fail immediately instead of timing out, and propagates the exception from the failed future. ++ +Thank you to community member https://github.com/1fanwang[Stefan Wang]. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1760[JVMCBC-1760]: +Upgraded to Netty `4.2.18`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1761[JVMCBC-1761]: +Upgraded to Jackson `2.21.6`. + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1759[JVMCBC-1759]: +The `couchbase2://` protocol now correctly throws `NumberTooBigException` when a subdocument operation fails for that reason. + + +[v3.12.2] +=== Version 3.12.2 (28 July 2026) + +https://packages.couchbase.com/clients/java/3.12.2/Couchbase-Java-Client-3.12.2.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.2/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.2/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1755[JVMCBC-1755]: +`bucket.waitUntilReady()` no longer times out during rebalance when some nodes are not yet hosting the bucket. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1752[JVMCBC-1752]: +The `couchbase2://` protocol was returning incorrect mutation tokens, with `partitionUUID` erroneously set to the same value as `partitionID`. +This is low-impact, and only affects developers who use the `couchbase2://` protocol and specify the "consistent with" option when querying or searching. + + + + +[v3.12.1] === Version 3.12.1 (08 July 2026) https://packages.couchbase.com/clients/java/3.12.1/Couchbase-Java-Client-3.12.1.zip[Download] | @@ -108,6 +191,7 @@ Fixed an issue where in some cases the SDK would continue trying to connect to a +[v3.12.0] === Version 3.12.0 (02 June 2026) https://packages.couchbase.com/clients/java/3.12.0/Couchbase-Java-Client-3.12.0.zip[Download] | From a050a0c78a27ceeba931322ca244df9d5663cafd Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Fri, 11 Sep 2026 12:32:24 +0100 Subject: [PATCH 21/44] removing legacy content --- modules/howtos/pages/advanced-analytics-querying.adoc | 2 -- modules/howtos/partials/alpha-warning.adoc | 11 ----------- modules/howtos/partials/beta-warning.adoc | 9 --------- 3 files changed, 22 deletions(-) delete mode 100644 modules/howtos/pages/advanced-analytics-querying.adoc delete mode 100644 modules/howtos/partials/alpha-warning.adoc delete mode 100644 modules/howtos/partials/beta-warning.adoc diff --git a/modules/howtos/pages/advanced-analytics-querying.adoc b/modules/howtos/pages/advanced-analytics-querying.adoc deleted file mode 100644 index 0616006f..00000000 --- a/modules/howtos/pages/advanced-analytics-querying.adoc +++ /dev/null @@ -1,2 +0,0 @@ -= Advanced Analytics Querying - diff --git a/modules/howtos/partials/alpha-warning.adoc b/modules/howtos/partials/alpha-warning.adoc deleted file mode 100644 index 1bb83349..00000000 --- a/modules/howtos/partials/alpha-warning.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Required attributes: -// :lang: Java -// :version: 3.0.0 alpha -[WARNING] -==== -These pages cover the _Alpha_ of the Couchbase Java SDK. -As such they are likely to change without notice. -This alpha code _should not_ be used in production. - -Documentation is incomplete, subject to change, and likely to contain broken links. -==== diff --git a/modules/howtos/partials/beta-warning.adoc b/modules/howtos/partials/beta-warning.adoc deleted file mode 100644 index 7bd1139e..00000000 --- a/modules/howtos/partials/beta-warning.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Required attributes: -[WARNING] -==== -These pages cover the _Beta_ release of the Couchbase Java SDK. -The API interface is stable, but could change for bug fixes during the Beta process. -New features are likely to be added. - -Documentation is incomplete, subject to change, and could contain broken links. -==== From dea56005ea626a415b53b20acbdbb8a022343abb Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Fri, 11 Sep 2026 17:56:56 +0100 Subject: [PATCH 22/44] DOC-14589 sdk-common & other tweaks for 3.10 --- antora.yml | 4 +-- .../collecting-information-and-logging.adoc | 25 +------------------ .../howtos/pages/concurrent-async-apis.adoc | 2 +- .../pages/concurrent-document-mutations.adoc | 4 +-- .../pages/full-text-searching-with-sdk.adoc | 1 - modules/howtos/pages/health-check.adoc | 21 ++++++---------- modules/howtos/pages/json.adoc | 4 ++- modules/howtos/pages/kv-operations.adoc | 1 - 8 files changed, 17 insertions(+), 45 deletions(-) diff --git a/antora.yml b/antora.yml index 12ce68d4..2ae892ae 100644 --- a/antora.yml +++ b/antora.yml @@ -7,11 +7,11 @@ nav: asciidoc: attributes: page-nav-header-levels: 2 - server_version: '8.1' + server_version: '8.0.3' sdk_current_version: '3.13.0' sdk_dot_minor: '3.13' sdk_dot_major: '3.x' - version-server: '8.1' + version-server: '8.0' version-common: '3.10' java_latest_lts_version: '25' name_platform: 'Java' diff --git a/modules/howtos/pages/collecting-information-and-logging.adoc b/modules/howtos/pages/collecting-information-and-logging.adoc index 6f55726d..117a386c 100644 --- a/modules/howtos/pages/collecting-information-and-logging.adoc +++ b/modules/howtos/pages/collecting-information-and-logging.adoc @@ -258,28 +258,5 @@ Once the SDK writes the logs with the tags to a file, you can then use the xref: == SDK Telemetry from the Server -In addition to Tracing and other metrics, and client logging, SDK telemetry is also sent to the Server -- available from 8.0, and in new Capella Operational clusters -- for ingestion with other Prometheus metrics. -Capella Operatioal exposes these metrics through the UI. - -For self-managed Server, collection can be disabled and enabled through the REST API: - -[source,console] ----- -curl --user Administrator:password http://172.17.0.2:8091/settings/appTelemetry -d enabled=true ----- - -And the Prometheus-format metrics fetched with: - -[source,console] ----- -curl --user Administrator:password http://172.17.0.2:8091/metrics ----- - -Further details can be found in the xref:{version-server}@server:rest-api:application-telemetry.adoc[] page. - -There may be advantages to collecting information this way, -but note that metrics are collected per node, -and a central Prometheus instance should be set to collect all metrics so that information is not lost in case of a sudden failover. - -Also note that if the cluster is behind a load balancer, the collected metrics may not accurately record the actual correct node with which the SDK interacts. +include::{version-common}@sdk:shared:partial$logging.adoc[tag=telemetry] diff --git a/modules/howtos/pages/concurrent-async-apis.adoc b/modules/howtos/pages/concurrent-async-apis.adoc index a2d5d24a..aef18db7 100644 --- a/modules/howtos/pages/concurrent-async-apis.adoc +++ b/modules/howtos/pages/concurrent-async-apis.adoc @@ -137,7 +137,7 @@ include::devguide:example$java/AsyncOperations.java[tag=retry-bulk] It is recommended to check out the `retry` and `retryBackoff` methods for their configuration options and overloads. Of course, all the operators shown here can be combined to achieve exactly the semantics you need. -Finally, for even advanced retry policies you can utilize the retry functionality in the https://projectreactor.io/docs/extra/release/api/reactor/retry/Retry.html[reactor-extra^] package. +Finally, for even more advanced retry policies you can utilize the retry functionality in the https://projectreactor.io/docs/extra/release/api/reactor/retry/Retry.html[reactor-extra^] package. == Reactive Streams Integration diff --git a/modules/howtos/pages/concurrent-document-mutations.adoc b/modules/howtos/pages/concurrent-document-mutations.adoc index a49dc622..294edf6e 100644 --- a/modules/howtos/pages/concurrent-document-mutations.adoc +++ b/modules/howtos/pages/concurrent-document-mutations.adoc @@ -1,8 +1,8 @@ = Concurrent Document Mutations :page-topic-type: howto -include::project-docs:partial$attributes.adoc[] +:description: You can use the CAS value to control how concurrent document modifications are handled :page-aliases: ROOT:concurrent-document-mutations.adoc -// ,7.6@server:developer-guide:cas-concurrency.adoc +// ,8.0@server:developer-guide:cas-concurrency.adoc include::{version-common}@sdk:shared:partial$cas.adoc[tag=intro] diff --git a/modules/howtos/pages/full-text-searching-with-sdk.adoc b/modules/howtos/pages/full-text-searching-with-sdk.adoc index 4c7173b5..70266211 100644 --- a/modules/howtos/pages/full-text-searching-with-sdk.adoc +++ b/modules/howtos/pages/full-text-searching-with-sdk.adoc @@ -21,7 +21,6 @@ There are two APIs for querying search: `cluster.searchQuery()`, and `cluster.se Both are also available at the Scope level. The former API supports Search queries (`SearchQuery`), while the latter additionally supports the `VectorSearch` added in 7.6. -Most of this documentation will focus on the former API, as the latter is in @Stability.Volatile status. We will perform a Search query here -- see the xref:vector-searching-with-sdk.adoc[Vector Search] docs for examples of Vector and xref:vector-searching-with-sdk.adoc#combining-fts-and-vector-queries[combining Vector and Search queries]. diff --git a/modules/howtos/pages/health-check.adoc b/modules/howtos/pages/health-check.adoc index 96a4f915..db933eb1 100644 --- a/modules/howtos/pages/health-check.adoc +++ b/modules/howtos/pages/health-check.adoc @@ -10,19 +10,14 @@ {description} +// intro +include::{version-common}@sdk:shared:partial$health-check.adoc[tag="intro"] -In today's distributed and virtual environments, users will often not have full administrative control over their whole network. -Working in distributed environments is hard. Latencies come and go, so do connections in their entirety. -Is it a network glitch, or is the remote cluster down? -Sometimes just knowing the likely cause is enough to get a good start on a workaround, or at least avoid hours wasted on an inappropriate solution. - -Health Check features _Ping_ to check nodes are still healthy, and to force idle connections to be kept alive in environments with eager shutdowns of unused resources. -_Diagnostics_ requests a report from a node, giving instant health check information. // Uses -include::{version-common}@sdk:pages:partial$health-check.adoc[tag="uses"] +include::{version-common}@sdk:shared:partial$health-check.adoc[tag="uses"] @@ -36,7 +31,7 @@ At its simplest, `ping` provides information about the current state of the conn [source,java] ---- -include::devguide:example$java/HealthCheck.java[tag=ping-basic] +include::devguide:example$java/HealthCheck.java[tag=ping-basic,indent=0] ---- This will print the latency for each socket (endpoint) connected per service. More information is available on the classes. @@ -45,7 +40,7 @@ This is made easy by the `exportToJson` method: [source,java] ---- -include::devguide:example$java/HealthCheck.java[tag=ping-json-export] +include::devguide:example$java/HealthCheck.java[tag=ping-json-export,indent=0] ---- By default the SDK will ping all services available on the target cluster. @@ -53,7 +48,7 @@ You can customize the type of services to ping through the `PingOptions`: [source,java] ---- -include::devguide:example$java/HealthCheck.java[tag=ping-options] +include::devguide:example$java/HealthCheck.java[tag=ping-options,indent=0] ---- In this example, only the Query service is included in the ping report. @@ -72,13 +67,13 @@ This makes it much cheaper to call on a regular basis, but does not provide any [source,java] ---- -include::devguide:example$java/HealthCheck.java[tag=diagnostics-basic] +include::devguide:example$java/HealthCheck.java[tag=diagnostics-basic,indent=0] ---- Because it is passive, diagnostics are only available at the `Cluster` level and cover everything in the current SDK state. Also, because it is not doing any I/O you cannot proactively filter the list of services that are returned, all you need to do is look only at the ones that are interesting to you. A `DiagnosticsResult` has one interesting property over a ping result -- it provides a cumulative `ClusterState` through the `state()` method. -The state can be `ONLINE`, `DEGRADED` or `OFFLINE`. +The state can be `ONLINE`, `DEGRADED`, or `OFFLINE`. This allows to give a single, although simplistic, view on how your cluster is doing from a client point of view. The state is determined as follows: diff --git a/modules/howtos/pages/json.adoc b/modules/howtos/pages/json.adoc index dcaa0fe8..a421bc6f 100644 --- a/modules/howtos/pages/json.adoc +++ b/modules/howtos/pages/json.adoc @@ -3,7 +3,9 @@ :navtitle: JSON Modelling :page-toclevels: 2 -include::project-docs:partial$attributes.adoc[] + +[abstract] +{description} == Philosophy diff --git a/modules/howtos/pages/kv-operations.adoc b/modules/howtos/pages/kv-operations.adoc index 59bcfae9..6a80e8a0 100644 --- a/modules/howtos/pages/kv-operations.adoc +++ b/modules/howtos/pages/kv-operations.adoc @@ -3,7 +3,6 @@ :page-aliases: ROOT:document-operations.adoc,ROOT:documents-creating.adoc,ROOT:documents-updating.adoc,ROOT:documents-retrieving.adoc,ROOT:documents-deleting.adoc // :example-source: 3.8@java-sdk:devguide:example$java/Queries.java :page-toclevels: 3 -:page-pagination: full From 1527f1d9279c323d9573a697c7ac3845b92546a8 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Mon, 14 Sep 2026 18:16:22 +0100 Subject: [PATCH 23/44] DOC-14589 howto tweaks --- .../examples/java/ManagingConnections.java | 3 +- modules/howtos/pages/kv-operations.adoc | 82 ++++++++----------- .../howtos/pages/managing-connections.adoc | 25 ++++-- 3 files changed, 51 insertions(+), 59 deletions(-) diff --git a/modules/devguide/examples/java/ManagingConnections.java b/modules/devguide/examples/java/ManagingConnections.java index 93b08804..d7eaf418 100644 --- a/modules/devguide/examples/java/ManagingConnections.java +++ b/modules/devguide/examples/java/ManagingConnections.java @@ -48,8 +48,7 @@ public static void main(String... args) { // You can access multiple buckets using the same Cluster object. Bucket anotherBucket = cluster.bucket("beer-sample"); - // You can access collections other than the default - // if your version of Couchbase Server supports this feature. + // You can access multiple collections, too Scope customerA = bucket.scope("customer-a"); Collection widgets = customerA.collection("widgets"); diff --git a/modules/howtos/pages/kv-operations.adoc b/modules/howtos/pages/kv-operations.adoc index 6a80e8a0..b74e594f 100644 --- a/modules/howtos/pages/kv-operations.adoc +++ b/modules/howtos/pages/kv-operations.adoc @@ -1,7 +1,7 @@ = Data Operations -:description: Data service offers the simplest way to retrieve or mutate data where the key is known. +:description: The Data Service offers the simplest way to retrieve or mutate data where the key is known. :page-aliases: ROOT:document-operations.adoc,ROOT:documents-creating.adoc,ROOT:documents-updating.adoc,ROOT:documents-retrieving.adoc,ROOT:documents-deleting.adoc -// :example-source: 3.8@java-sdk:devguide:example$java/Queries.java +// :example-source: 3.13@java-sdk:devguide:example$java/Queries.java :page-toclevels: 3 @@ -15,27 +15,23 @@ as well as KV Range scan, for querying without an index. The complete code sample used on this page can be downloaded from https://github.com/couchbase/docs-sdk-java/blob/release/{sdk_dot_minor}/modules/devguide/examples/java/KvOperations.java[here]. -At its heart Couchbase Server is a high-performance key-value store, and the key-value interface outlined below is the fastest and best method to perform operations involving single documents. -A _document_ refers to an entry in the database (other databases may refer to the same concept as a _row_). -A document has an ID (_primary key_ in other databases), which is unique to the document and by which it can be located. -The document also has a value which contains the actual application data. -See xref:concept-docs:documents.adoc[the concept guide to _Documents_] for a deeper dive into documents in the Couchbase Data Platform. +// intro +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=intro] -Before proceeding, make sure you're familiar with the basics of authorization and connecting to a Cluster from the xref:hello-world:start-using-sdk.adoc[Start Using the SDK] section. +//// The code samples below will use these imports: [source,java] ---- include::devguide:example$java/KvOperations.java[tag=imports] ---- +//// + -[TIP] -.{sqlpp} vs. Key-Value -==== -{sqlpp_url}[{sqlpp} (formerly N1QL)] can also be used to perform many single-document operations but we very strongly recommend using the key-value API for this instead, as it can be much more efficient. The request can go directly to the correct node, there's no query parsing overhead, and it's over the highly optimized memcached binary protocol. -==== +//{sqlpp} vs. Key-Value +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=sql-vs-kv] == JSON @@ -51,13 +47,10 @@ The SDK also supports custom transcoders and serializers which are covered separ == CRUD -[TIP] -.Sub-Document Operations -==== -All of these operations involve fetching the complete document from the Cluster. -Where the number of operations or other circumstances make bandwidth a significant issue, -the SDK can work on just a specific _path_ of the document with xref:subdocument-operations.adoc[Sub-Document Operations]. -==== +// Sub-Document Operations +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=subdoc] + + === Upsert @@ -127,15 +120,13 @@ Then we `get` it back into `doc` and pull out the document's content as a `JsonO Afterwards, we update a field in the `JsonObject` with `put`. `JsonObject` is mutable, we don't need to store the result of the `put`. Finally, we `replace` the document with the updated content, and a CAS value, storing the final result as `result`. + + ==== What is CAS? -CAS, or Compare And Swap, is a form of optimistic locking. Every document in Couchbase has a CAS value, and it's changed on every mutation. -When you `get` a document you also get the document's CAS, and then when it's time to write the document, you send the same CAS back. -If another thread or program has modified that document in the meantime, the Couchbase Server can detect you've provided a now-outdated CAS, and return an error. -This provides cheap, safe concurrency. -See xref:concurrent-document-mutations.adoc[this detailed description of CAS] for further details. +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=cas] + -In general, you'll want to provide a CAS value whenever you `replace` a document, to prevent overwriting another agent's mutations. === Retrying on CAS failures @@ -167,6 +158,7 @@ include::devguide:example$java/KvOperations.java[tag=remove,indent=0] Like `replace`, `remove` also optionally takes the CAS value if you want to make sure you are only removing the document if it hasn't changed since you last fetched it. + == Durability Writes in Couchbase are written to a single node, and from there the Couchbase Server will take care of sending that mutation to any configured replicas. @@ -184,9 +176,9 @@ If no argument is provided the application will report success back as soon as t However, we recognize that there are times when the application needs that extra certainty that especially vital mutations have been successfully replicated, and the other durability options provide the means to achieve this. -The options differ depend on what Couchbase Server version is in use. -If 6.5 or above is being used, you can take advantage of the xref:concept-docs:durability-replication-failure-considerations.adoc#durable-writes[Durable Write] feature, -in which Couchbase Server will only return success to the SDK after the requested replication level has been achieved. +If you need stronger durability guarantees, +you can take advantage of the xref:concept-docs:durability-replication-failure-considerations.adoc#durable-writes[Durable Write] feature, +in which Couchbase Server (self-managed or Capella) will only return success to the SDK after the requested replication level has been achieved. The three replication levels are: * `Majority` -- The server will ensure that the change is available in memory on the majority of configured replicas. @@ -197,16 +189,16 @@ The options are in increasing levels of safety. Note that nothing comes for free -- for a given node, waiting for writes to storage is considerably slower than waiting for it to be available in-memory. These tradeoffs, as well as which settings may be tuned, are discussed in the xref:concept-docs:durability-replication-failure-considerations.adoc#durable-writes[durability page]. -// remove 6.5 stuff once 8.0 is released? -If a version of Couchbase Server lower than 6.5 is being used then the application can fall-back to xref:concept-docs:durability-replication-failure-considerations.adoc#older-server-versions['client verified' durability]. -Here the SDK will do a simple poll of the replicas and only return once the requested durability level is achieved. -This can be achieved like this: -[source,java] ----- -include::devguide:example$java/KvOperations.java[tag=durability-observed,indent=0] ----- + +This durability is enforced by the cluster. +A client verified durability API was necessary with older, no longer supported version of Couchbase Server. +This API is still avaialable, but there are few cases where you would want to use this less performant option. +Details can be found +https://docs-archive.couchbase.com/java-sdk/3.3/concept-docs/durability-replication-failure-considerations.html#older-server-versions[in our archived docs]. + + To stress, durability is a useful feature but should not be the default for most applications, as there is a performance consideration, and the default level of safety provided by Couchbase will be reasonable for the majority of situations. @@ -268,6 +260,7 @@ include::devguide:example$java/KvOperations.java[tag=expiry-touch,indent=0] == Atomic Counters The value of a document can be increased or decreased atomically using `collecion.binary().increment()` and `collection.binary().decrement()`. + //// .Increment [source,csharp] @@ -293,7 +286,8 @@ include::example$KvOperations.cs[tag=binarydecrement,indent=0] include::example$KvOperations.cs[tag=binarydecrementwithoptions,indent=0] ---- //// -NOTE: Increment & Decrement are considered part of the ‘binary’ API and as such may still be subject to change + +NOTE: Increment & Decrement are considered part of the "binary" API and as such may still be subject to change See the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/kv/Increment.html[API Reference] for full details. @@ -308,7 +302,7 @@ include::{version-common}@sdk:shared:partial$atomic.adoc[tag=xdcr] == Scoped KV Operations -It is possible to perform scoped key-value operations on named xref:{version-server}@server:learn:data/scopes-and-collections.adoc[`Collections`] _with Couchbase Server release 7.x_. +It is possible to perform scoped key-value operations on named xref:{version-server}@server:learn:data/scopes-and-collections.adoc[`Collections`]. See the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/Collection.html[API docs] for more information. Here is an example showing an upsert in the `users` collection, which lives in the `travel-sample.tenant_agent_00` keyspace: @@ -391,12 +385,4 @@ Setting `idsOnly` to true also works with the other scan types described above. == Additional resources -Working on just a specific path within a JSON document will reduce network bandwidth requirements -- see the xref:subdocument-operations.adoc[Sub-Document] pages. - -For a significant performance speed up with large volumes of data, reference our xref:concurrent-async-apis.adoc[asynchronous programming options]. - -Another way of increasing network performance is to _pipeline_ operations with xref:concurrent-async-apis.adoc#batching[Batching Operations]. - -As well as various xref:concept-docs:data-model.adoc[Formats] of JSON, Couchbase can work directly with xref:concept-docs:nonjson.adoc[arbitrary bytes, or binary format]. - -Our xref:sqlpp-queries-with-sdk.adoc[Query Engine] enables retrieval of information using the SQL-like syntax of {sqlpp}. +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=resources] diff --git a/modules/howtos/pages/managing-connections.adoc b/modules/howtos/pages/managing-connections.adoc index dfe78854..6d13d623 100644 --- a/modules/howtos/pages/managing-connections.adoc +++ b/modules/howtos/pages/managing-connections.adoc @@ -4,7 +4,7 @@ :page-aliases: ROOT:managing-connections.adoc,howtos:multi-network.adoc,ROOT:connecting.adoc,ROOT:connection-advanced.adoc :page-toclevels: 2 -include::project-docs:partial$attributes.adoc[] + [abstract] {description} @@ -21,8 +21,6 @@ The simplest way to create a `Cluster` object is to call `Cluster.connect()` wit include::devguide:example$java/ManagingConnections.java[tag=simpleconnect,indent=0] ---- -NOTE: If you are connecting to a version of Couchbase Server older than 6.5, it will be more efficient if the addresses are those of data (KV) nodes. -You will in any case, with 7.0 and earlier, need to open a `Bucket` instance before connecting to any other HTTP services (such as _Query_ or _Search_). In a production environment, your connection string should include the addresses of multiple server nodes in case some are currently unavailable. Multiple addresses may be specified in a connection string by delimiting them with commas: @@ -121,9 +119,9 @@ If your Couchbase Server cluster is running in a containerized, port mapped, or Both the client and server require special configuration in this case. On the server side, each server node must be configured to advertise its external address as well as any custom port mapping. -This is done with the `setting-alternate-address` CLI command introduced in Couchbase Server 6.5. +This is done with the `setting-alternate-address` CLI command -- +see the xref:server:cli:cbcli/couchbase-cli-setting-alternate-address.adoc[reference] for further information. A node configured in this way will advertise two addresses: one for connecting from the same network, and another for connecting from an external network. -// todo link to https://docs.couchbase.com/server/7.0/cli/cbcli/couchbase-cli-setting-alternate-address.html On the client side, the externally visible ports must be used when connecting. If the external ports are not the default, you can specify custom ports in the connection string when calling `Cluster.connect()`. @@ -286,9 +284,11 @@ quarkus.couchbase.password=password == Cloud Native Gateway -Couchbase's next generation connection protocol, introduced in Java SDK 3.5 and xref:operator::concept-cloud-native-gateway.adoc[Couchbase Autonomous Operator 2.6.1], can be enabled simply by changing the connection string to `couchbase2://` but there are a few differences to be aware of, described <<#limitations,below>>. +Couchbase's next generation connection protocol, introduced in Java SDK 3.5 and xref:operator::concept-cloud-native-gateway.adoc[Couchbase Autonomous Operator 2.6.1] -- +and available as a xref:cloud-native-gateway:intro:about-cng.adoc[standalone product] for use with self-managed Couchbase Server from 8.0 onwards -- +can be enabled simply by changing the connection string to `couchbase2://` but there are a few differences to be aware of, described <<#limitations,below>>. -The protocol implements a gRPC-style interface between the SDK and Couchbase Server (in this case, only available in the Server running on Kubernetes or OpenShift, with a recent version of xref:operator::overview.adoc[Couchbase Autonomous Operator]). +The protocol implements a gRPC-style interface between the SDK and Couchbase Server. === Limitations @@ -373,9 +373,17 @@ _plus_ it waits for the K-V (data) sockets to be ready. Other timeout issues may occur when using the SDK located geographically separately from the Couchbase Server cluster -- this is xref:project-docs:compatibility#network-requirements[not recommended]. See the xref:#working-in-the-cloud[Cloud section] below for some suggestions of settings adjustments. + + + + +== Working in the Cloud + include::{version-common}@sdk:shared:partial$managing-connections.adoc[tag=cloud] + + == Async and Reactive APIs The Couchbase Java SDK provides first-class support for asynchronous and reactive programming. @@ -415,5 +423,4 @@ Here's the same example, but using the Reactive API instead of the Async API: include::devguide:example$java/ManagingConnections.java[tag=reactivecluster,indent=0] ---- - -// == Working in the Cloud +See the xref:concurrent-async-apis.adoc[] page for more information. From e3572f901f800cb769f825294cdafd9ec03d0697 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 15:21:47 +0100 Subject: [PATCH 24/44] DOC-14593 sdk-common --- .../concept-docs/pages/best-practices.adoc | 19 +--- modules/project-docs/pages/compatibility.adoc | 97 +++++-------------- modules/project-docs/pages/deployment.adoc | 47 +-------- .../pages/migrating-sdk-code-to-3.n.adoc | 2 +- modules/ref/pages/error-codes.adoc | 2 +- 5 files changed, 33 insertions(+), 134 deletions(-) diff --git a/modules/concept-docs/pages/best-practices.adoc b/modules/concept-docs/pages/best-practices.adoc index 9f9282a5..d6fea854 100644 --- a/modules/concept-docs/pages/best-practices.adoc +++ b/modules/concept-docs/pages/best-practices.adoc @@ -182,25 +182,8 @@ Example usage: == 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 - -* xref:cloud:security:security.adoc[Security Best Practices in Capella] -* xref:server:learn:security/security-overview.adoc[Security for self-managed Couchbase Server] - -=== Role-Based Access Control - -For Capella, Roles, Cluster Access Credentials, and Authentication options are covered in the xref:cloud:security:security.adoc[Capella Security docs]. - - -For self-managed Couchbase Server, all aspects of the Couchbase RBAC system are covered in the section xref:{version-server}@server:learn:security/authorization-overview.adoc[Authorization]. -Specifically, for information on: - -* Adding _Users_ and assigning _roles_, by means of the Couchbase Web Console, see xref:{version-server}@server:manage:manage-security/manage-users-and-roles.adoc[Manage Users and Roles]. -* _Roles_ required for resource-access, and the privileges they entail, see xref:{version-server}@server:learn:security/roles.adoc[Roles]. -* _Resources_ controlled by Couchbase RBAC, see xref:{version-server}@server:learn:security/resources-under-access-control.adoc[Resources Under Access Control]. +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=additional] diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc index 942f426e..cf0ee339 100644 --- a/modules/project-docs/pages/compatibility.adoc +++ b/modules/project-docs/pages/compatibility.adoc @@ -20,27 +20,7 @@ _Java {java_latest_lts_version} is recommended_. === JDK Version Compatibility -We test the {name-sdk} with https://adoptium.net/[Eclipse Temurin] versions 8, 17, 21, and 25. - -The following OpenJDK releases are supported: - -* https://adoptium.net/[OpenJDK 25 with HotSpot JVM] (recommended) -* https://adoptium.net/[OpenJDK 21 with HotSpot JVM] -* https://adoptium.net/[OpenJDK 17 with HotSpot JVM] -* https://adoptium.net/[OpenJDK 11 with HotSpot JVM] -* https://adoptium.net/[OpenJDK 8 with HotSpot JVM] - -The following Oracle JDK releases are also supported but we do not do any testing with them owing to Oracle license issues: - -* https://www.oracle.com/java/technologies/downloads/#java17[Oracle JDK 17] -* https://www.oracle.com/java/technologies/downloads/#java11[Oracle JDK 11] -* https://www.oracle.com/java/technologies/downloads/#java8[Oracle JDK 8] - -Other JDK implementations might work but are untested and unsupported. - -[TIP] -Make sure to stay up to date with JDK patch releases because they provide stability improvements and security fixes. - +include::{version-common}@sdk:shared:partial$compat.adoc[tag=jdk-compat] === OS Compatibility @@ -49,33 +29,8 @@ In general, the JVM eliminates concerns about underlying OS compatibility, and Couchbase JVM SDKs can be expected to run on all of the Operating Systems supported by xref:{version-server}@server:install:install-platforms.adoc[Couchbase Server]. -The {name-sdk} will run on, and is supported on, the following OSs and platforms. -The SDK has been tested on a representative subset of the platforms listed below. - -**** -[discrete] -=== GNU/Linux - -* Amazon Linux 2 & AL2023. -* Red Hat Enterprise Linux 8, 9, & 10. -* Oracle Linux 8, 9, & 10. -* Ubuntu (LTS) 22.04 (_Jammy_) & 24.04 (_Noble_). -* Debian 11 (_Bullseye_), Debian 12 (_Bookworm_), & Debian 13 (_Trixie_). -* SUSE Enterprise Linux 12 & 15. -* Alpine Linux 3.21 - 3.23. - -[discrete] -=== Microsoft Windows - -* Microsoft Windows 10 & 11; -* Windows Server 2019, 2022, & 2025. - -[discrete] -=== Mac OS X +include::{version-common}@sdk:shared:partial$compat.adoc[tag=os-compat] -The current and previous two releases of OS X. -At time of writing (???? 2026): 26 (Tahoe), 15 (Sequoia), and 14 (Sonoma). -**** The JVM SDKs should also be expected to run on other commonly-available GNU/Linux distributions which support an appropriate JDK, but not all combinations can be tested -- notable exceptions are listed below. @@ -118,14 +73,19 @@ The downside of these workarounds is potentially reduced performance, which can // Platforms, Chipsets, and Virtual Environments. -include::{version-common}@sdk:shared:partial$platform.adoc[tag=virtual] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=virtual] // Network Requirements -include::{version-common}@sdk:shared:partial$network-requirements.adoc[] +include::{version-common}@sdk:shared:partial$compat[tag=network-requirements] + + + +// Serverless Environments +include::{version-common}@sdk:shared:partial$compat[tag=serverless] @@ -139,13 +99,10 @@ Couchbase SDKs are tested against a variety of different environments to ensure === Couchbase Version/SDK Version Matrix -The matrix below denotes the version of Couchbase Server, the version of the {name-sdk} and whether the SDK is: -* ✖ *Unsupported*: This combination is not tested, and is not within the scope of technical support if you have purchased a support agreement. -* ◎ *Compatible*: This combination has been tested previously, and should be compatible. -evertheless, this combination is not recommended by our technical support organization, as not all of the latest features are supported by it. -It is best to upgrade either the SDK or the Couchbase version you are using. -* ✔ *Supported*: This combination is subject to ongoing quality assurance, and is fully supported by our technical support organization. +include::{version-common}@sdk:shared:partial$compat[tag=matrix-notes1] + + .Recommended SDK per Server Version Matrix [#table_sdk_versions] @@ -172,18 +129,16 @@ It is best to upgrade either the SDK or the Couchbase version you are using. |=== -① Server 7.6 & 8.0 are compatible with all supported (not yet End-of-Life) versions of the {name-sdk}, but for full support of the latest features you need to upgrade to a recent version of the SDK. -See the <<#couchbase-new-feature-availability-matrix,Feature Availablity matrix below>> and the xref:sdk-release-notes.adoc[Release Notes page]. -Note the https://www.couchbase.com/support-policy/EOL/[End of Life dates^] for Couchbase Server and SDK versions. -See the notes there for Support details. +include::{version-common}@sdk:shared:partial$compat[tag=matrix-notes2] + + + === Capella Compatibility -The Couchbase {name-sdk} is fully compatible with Couchbase Capella, our fully-hosted database-as-a-service. -To make development easier, the SDK includes the Capella client certificate ready installed. -include::{version-common}@sdk:shared:partial$capella.adoc[tag=cloud] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=cloud] === Couchbase New Feature Availability Matrix @@ -211,11 +166,9 @@ include::{version-common}@sdk:shared:partial$capella.adoc[tag=cloud] | From SDK 3.9.0 ① |=== -① As part of the standard SDK {sqlpp} API, it should be compatible with all earlier versions of the SDK -- but it has not been tested. -This table is not an exhaustive list -- just a few highlights -- provided to help assess compatibility of older versions in particular. -For a slightly fuller table, see the xref:deployment.adoc#couchbase-operational-cluster-feature-compatibility[Deployment page]. -For alignment of SDKs and new Server features, scroll down to the information below the <>. +include::{version-common}@sdk:shared:partial$compat[tag=feature-notes] + === Spring Data Couchbase Compatibility @@ -226,7 +179,7 @@ The following table provides an overview at the time of Java SDK {sdk_dot_minor} .Recommended Spring Data Couchbase per Server Version Matrix [#table_spring_versions] |=== -| | SDC 5.4 - 5.5 | SDC 6.0 +| | SDC 5.4 - 5.5 | SDC 6.0 - 6.1 | _Status ->_ | _Maintenance Support_ @@ -244,14 +197,14 @@ Using the latest Spring Data Couchbase should ensure that this is so. === Quarkus Java Compatibility -Couchbase Quarkus requires Java SDK 3.7.7 or newer. +include::1.4@quarkus-extension::compatibility.adoc[tag=compat-table] See the xref:quarkus-extension:ROOT:overview.adoc[Couchbase Quarkus Java Extension docs] for details of using Quarkus, and the compatibility with Quarkus, GraalVM, and the Couchbase Java SDK. === API Version -include::{version-common}@sdk:shared:partial$api-version.adoc[tag=api-version] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=api-version] @@ -261,9 +214,11 @@ include::{version-common}@sdk:shared:partial$api-version.adoc[tag=api-version] === Interface Stability -include::{version-common}@sdk:shared:partial$interface-stability-pars.adoc[tag=interface-stability-section] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=interface-stability-section] === Older SDK Versions -include::{version-common}@sdk:shared:partial$archive.adoc[tag=link] + +include::{version-common}@sdk:shared:partial$compat.adoc[tag=archive-link] + diff --git a/modules/project-docs/pages/deployment.adoc b/modules/project-docs/pages/deployment.adoc index 3e114bb6..d6af4595 100644 --- a/modules/project-docs/pages/deployment.adoc +++ b/modules/project-docs/pages/deployment.adoc @@ -15,19 +15,7 @@ - - - - -One of Couchbase's strengths is speedy response, so deployment of apps should be in the same region as the Server -- whether Capella, or your own self-managed cluster. - -We always recommend the xref::sdk-release-notes.adoc#latest-release[latest version] of the SDK. -This not only contains the latest security updates and bug fixes, but will be compatible with the latest Couchbase Server release -(note, Capella always runs a recent version of Couchbase Server). - -Before deploying, take note of any xref:compatibility.adoc[compatibility] issues for the language platform and underlying OS. -The xref:sdk-full-installation.adoc[full installation guide] should cover any special cases for all supported environments. - +include::{version-common}@sdk:shared:partial$deployment.adoc[tag=intro] @@ -37,18 +25,10 @@ include::{version-common}@sdk:shared:partial$deployment.adoc[tag=load-balancer] - == Development & Testing Environments -During development, some shortcuts are taken to get up and running which would not be acceptable during deployment. -These include use of administrator permissions, connecting from your laptop instead of a secure app server, and even disabling certificate verification for TLS. -Testing environments may also differ from deployment. - -The {name-sdk} docs note whenever a shortcut is being taken, but here is a non-exhaustive list of those development practices which should not be carried over to production deployments: -* Over-priveleged access -* Geographical separation of app server and database -* Skipping certificate verification +include::{version-common}@sdk:shared:partial$deployment.adoc[tag=testing] // * more The best way to accommodate developing an application that is to be deployed to production is to use the platform's default approach for configuration files. @@ -126,27 +106,8 @@ The following table covers possible exceptions, and gives the version of the {na +// == Further Reading +include::{version-common}@sdk:shared:partial$deployment.adoc[tag=further-reading] - - -== Further Reading - -* Integrate Couchbase with your data ecosystem: -** xref:project-docs:third-party-integrations.adoc[SDK Integrations] -** xref:server:develop:integrations.adoc[Integrations across Couchbase] -* xref:project-docs:get-involved.adoc[Contribute to the SDK] - -=== Deploying Couchbase Server - -* xref:cloud::index.adoc[Capella] -- Database as a Service -* xref:{version-server}@server:install:get-started.adoc[Self-managed Couchbase Server]: -** xref:{version-server}@server:install:getting-started-docker.adoc[Docker Install] -** xref:operator::overview.adoc[Couchbase Autonomous Operator] -*** xref:operator::install-kubernetes.adoc[Kubernetes] -*** xref:operator::install-openshift.adoc[Openshift] -** xref:{version-server}server:cloud:couchbase-cloud-deployment.adoc[Cloud Marketplace]: -*** xref:{version-server}@server:cloud:couchbase-aws-marketplace.adoc[AWS Marketplace] -*** xref:{version-server}@server:cloud:couchbase-azure-marketplace.adoc[Azure Marketplace] -*** xref:{version-server}@server:cloud:couchbase-gcp-cloud-launcher.adoc[GCP Marketplace] diff --git a/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc b/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc index 1cdcddad..b1b6cc1a 100644 --- a/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc +++ b/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc @@ -834,4 +834,4 @@ a|`sslTruststoreFile` |`propagateParentSpan` | removed |==== -include::{version-common}@sdk:shared:partial$archive.adoc[tag=migration] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=migration] diff --git a/modules/ref/pages/error-codes.adoc b/modules/ref/pages/error-codes.adoc index a0cd3ac7..23d94cac 100644 --- a/modules/ref/pages/error-codes.adoc +++ b/modules/ref/pages/error-codes.adoc @@ -66,5 +66,5 @@ WARNING: [com.couchbase.core][DnsSrvLookupFailedEvent][86ms] DNS SRV lookup fail * Our practical look at xref:howtos:error-handling.adoc[error handling with the SDK]. * xref:howtos:health-check.adoc#diagnostics[Diagnostics] with Health Check. -* xref:concept-docs:errors.adoc[Discussion document] on handling exceptions. +// * xref:concept-docs:errors.adoc[Discussion document] on handling exceptions. * Further reference material in the https://docs.couchbase.com/sdk-api/couchbase-java-client/index.html[API Guide]. From 587d56c1c17ac87c703127e6cd293c73b7b8bf19 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 16:39:28 +0100 Subject: [PATCH 25/44] h2 fix --- modules/howtos/pages/sdk-authentication.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/howtos/pages/sdk-authentication.adoc b/modules/howtos/pages/sdk-authentication.adoc index f854bdcb..387c5dbe 100644 --- a/modules/howtos/pages/sdk-authentication.adoc +++ b/modules/howtos/pages/sdk-authentication.adoc @@ -12,7 +12,7 @@ include::project-docs:partial$attributes.adoc[] Our xref:hello-world:start-using-sdk.adoc[Getting Started] guide covered the basics for authorizing against a Couchbase cluster, but you may need to use alternative authentication methods such as Certification. -== RBAC +== Basic Authentication Our xref:hello-world:start-using-sdk.adoc[Getting Started] guide introduced basic authentication against a Couchbase cluster: @@ -37,6 +37,9 @@ include::devguide:example$java/Auth.java[tag=rbac-pwd,indent=0] In this example, the `PLAIN` authentication mechanism is enabled as well, which is needed if LDAP is enabled on the server side and no TLS encrypted connection is used. + +== RBAC + include::{version-common}@sdk:shared:partial$auth-overview.adoc[tag=rbac] include::{version-common}@sdk:shared:partial$auth-overview.adoc[tag=cert-auth] From 135014838f84b80fe69a251d11ee3a50d03f4f0d Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 16:57:10 +0100 Subject: [PATCH 26/44] !old expiry --- modules/devguide/examples/java/KvOperations.java | 11 ----------- modules/howtos/pages/kv-operations.adoc | 9 +-------- 2 files changed, 1 insertion(+), 19 deletions(-) diff --git a/modules/devguide/examples/java/KvOperations.java b/modules/devguide/examples/java/KvOperations.java index b1ae1bb2..352848b9 100644 --- a/modules/devguide/examples/java/KvOperations.java +++ b/modules/devguide/examples/java/KvOperations.java @@ -217,17 +217,6 @@ public static void main(String... args) { System.out.println("cas value: " + result.cas()); } - { - System.out.println("\nExample: [expiry-replace]"); - // tag::expiry-replace[] - GetResult found = collection.get("my-document3", getOptions().withExpiry(true)); - - MutationResult result = collection.replace("my-document3", json, - replaceOptions().expiry(found.expiryTime().get())); - // end::expiry-replace[] - - } - try { System.out.println("\nExample: [preserve-expiry]"); diff --git a/modules/howtos/pages/kv-operations.adoc b/modules/howtos/pages/kv-operations.adoc index b74e594f..205f535a 100644 --- a/modules/howtos/pages/kv-operations.adoc +++ b/modules/howtos/pages/kv-operations.adoc @@ -234,20 +234,13 @@ include::devguide:example$java/KvOperations.java[tag=expiry-get,indent=0] ---- Note that when updating the document, special care must be taken to avoid resetting the expiry to zero. -If you are using Couchbase Server 7.0 or later, set the `preserveExpiry` option when updating the document: +Set the `preserveExpiry` option when updating the document: [source,java] ---- include::devguide:example$java/KvOperations.java[tag=preserve-expiry,indent=0] ---- -Prior to Couchbase 7.0, it's necessary to fetch the previous expiry and set it again: - -[source,java] ----- -include::devguide:example$java/KvOperations.java[tag=expiry-replace,indent=0] ----- - Some applications may find `getAndTouch` useful, which fetches a document while updating its expiry field. It can be used like this: From 0ac7125b2f10ab4f337b500932579061e3c0d7c8 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 17:18:14 +0100 Subject: [PATCH 27/44] 7.0 mention removal --- modules/howtos/pages/sqlpp-queries-with-sdk.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc index 3bdada2c..8f1eb14a 100644 --- a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc +++ b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc @@ -242,7 +242,7 @@ This query will stream all rows as they become available from the server, automa == Querying at Scope Level It is possible to query off the xref:concept-docs:n1ql-query.adoc#collections-and-scopes-and-the-query-context[`Scope` level], -_with Couchbase Server release 7.x_, using the `scope.query()` method. +using the `scope.query()` method. It takes the statement as a required argument, and then allows additional options if needed. A complete list of `QueryOptions` can be found in the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/AsyncScope.html#query-java.lang.String-[API docs]. From 09014b14481f70cd8c780db1b55ad48b301a3cd9 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 17:29:26 +0100 Subject: [PATCH 28/44] Deduplicate RBAC h3 --- modules/concept-docs/pages/best-practices.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/concept-docs/pages/best-practices.adoc b/modules/concept-docs/pages/best-practices.adoc index d6fea854..ec19043f 100644 --- a/modules/concept-docs/pages/best-practices.adoc +++ b/modules/concept-docs/pages/best-practices.adoc @@ -31,7 +31,7 @@ There's plenty that can be done to remove bottlenecks in development and in perf include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=security] -=== Roles and RBAC +// === Roles and RBAC include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=rbac] From b424ee354ebf62ea2162a78841e5995ff1de680c Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 17:36:32 +0100 Subject: [PATCH 29/44] Minor fixes --- modules/project-docs/pages/sdk-release-notes.adoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index b8e2be01..e3ff0db5 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -29,7 +29,7 @@ We always recommend using the latest version of the SDK -- it contains all of th All patch releases for each dot minor release should be API compatible, and safe to upgrade; any changes to expected behavior are noted in the release notes that follow. -Version {sdk_dot_minor} of the Java SDK implements the {sdk-api} xref:compatibility.adoc#api-version[SDK API]. +Version {sdk_dot_minor} of the Java SDK implements the {sdk_api} xref:compatibility.adoc#api-version[SDK API]. See the xref:compatibility.adoc#couchbase-feature-availability-matrix[compatibility pages] for more information on feature compatibility with different versions of Couchbase Server. @@ -55,7 +55,10 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea [v3.13.0] -=== Version 3.13.0 (08 October 2026) +=== Version 3.13.0 (13 October 2026) + + + == Java SDK 3.12 Releases @@ -1269,6 +1272,7 @@ Optional artifacts on top of this SDK version are tested for the following compa | `tracing-opentracing` | 1.4.4 | OpenTracing 0.33.0 | Committed | `metrics-opentelemetry` | 0.6.4 | OpenTelemetry 1.31.0 | Volatile | `metrics-micrometer` | 0.6.4 | Micrometer 1.10.10 | Volatile +|======================= ==== Improvements From d23380c8767ced38ef4e4a185375e32200c7f69a Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 17:46:44 +0100 Subject: [PATCH 30/44] superfluous CBAS concept --- .../pages/analytics-for-sdk-users.adoc | 25 ------------------- 1 file changed, 25 deletions(-) delete mode 100644 modules/concept-docs/pages/analytics-for-sdk-users.adoc diff --git a/modules/concept-docs/pages/analytics-for-sdk-users.adoc b/modules/concept-docs/pages/analytics-for-sdk-users.adoc deleted file mode 100644 index 878180fd..00000000 --- a/modules/concept-docs/pages/analytics-for-sdk-users.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= Analytics -:description: Parallel data management for complex queries over many records, using a familiar SQL-like syntax. -:nav-title: Analytics for SDK Users -:page-topic-type: concept -:page-aliases: analytics.adoc - -[abstract] -{description} - - -For complex and long-running queries, involving large ad hoc join, set, aggregation, and grouping operation. - - -//// -== MetaData - -=== List of Metrics - -//// - - -== Additional Resources - -* Start with our xref:{version-server}@server:analytics:primer-beer.adoc[introductory primer]. -* Read the practical introduction xref:howtos:analytics-using-sdk.adoc[using analytics from the SDK]. From f3596305014ed983fe411fb89ac3ee5b69ec4bd2 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 17:49:21 +0100 Subject: [PATCH 31/44] superfluous Collections concept --- modules/concept-docs/pages/collections.adoc | 31 --------------------- 1 file changed, 31 deletions(-) delete mode 100644 modules/concept-docs/pages/collections.adoc diff --git a/modules/concept-docs/pages/collections.adoc b/modules/concept-docs/pages/collections.adoc deleted file mode 100644 index ce12a00a..00000000 --- a/modules/concept-docs/pages/collections.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Collections and Scopes -:description: pass:q[Fully supported in Couchbase Server 7.x] -:page-topic-type: concept -:nav-title: Collections - -[abstract] -{description} - -The Collections feature in Couchbase Server is fully implemented in the 3.x API versions of the Couchbase SDK. - -Information on _Collections_ can be found in the xref:{version-server}@server:learn:data/scopes-and-collections.adoc[server docs]. - -== Using Collections & Scopes - -Access a non-default collection, in the default scope, with: - -[source,java] ----- -include::example$CollectionsExample.java[tag=collections_1,indent=0] ----- - -And for a non-default scope: -[source,java] ----- -include::example$CollectionsExample.java[tag=collections_2,indent=0] ----- - - -== Further Reading - -To see Collections in action, take a look at our xref:howtos:working-with-collections.adoc[Collections-enabled Travel Sample page]. From 68b220953853efd45ce3e342dc50f5dc083b71ca Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 17:52:25 +0100 Subject: [PATCH 32/44] superfluous Bucket management concept --- .../pages/buckets-and-clusters.adoc | 29 ------------------- 1 file changed, 29 deletions(-) delete mode 100644 modules/concept-docs/pages/buckets-and-clusters.adoc diff --git a/modules/concept-docs/pages/buckets-and-clusters.adoc b/modules/concept-docs/pages/buckets-and-clusters.adoc deleted file mode 100644 index b7de9176..00000000 --- a/modules/concept-docs/pages/buckets-and-clusters.adoc +++ /dev/null @@ -1,29 +0,0 @@ -= Buckets and Clusters -:description: The Couchbase Java SDK provides an API for managing a Couchbase cluster programmatically. -:navtitle: Buckets & Clusters -:page-topic-type: concept -:page-aliases: managing-clusters.adoc - -include::project-docs:partial$attributes.adoc[] - -[abstract] -{description} - -include::{version-common}@sdk:shared:partial$clusters-buckets.adoc[tag=management] - -Management operations in the Java SDK may be performed through several interfaces depending on the object: - -== Creating and Removing Buckets - -To create or delete a bucket, call the bucket manager with the `buckets()` call on the cluster: - -[source,java] ----- -include::example$BucketsAndClustersExample.java[tag=buckets_and_clusters_1,indent=0] ----- - -// The `BucketSettings` can be created via a builder, [.api]`DefaultBucketSettings.builder()`. -This class is also used to expose information about an existing bucket (`manager.getBucket(string)`) or to update an existing bucket (`manager.updateBucket(bucketSettings)`). - -The default Collection & Default Scope will be used automatically. - From a68471c515a73100de4f6e8dfe8dc1d7be824799 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 17:55:22 +0100 Subject: [PATCH 33/44] Concepts clean-up --- modules/ref/pages/index.adoc | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/modules/ref/pages/index.adoc b/modules/ref/pages/index.adoc index dfe12ca1..002c3b43 100644 --- a/modules/ref/pages/index.adoc +++ b/modules/ref/pages/index.adoc @@ -36,8 +36,6 @@ but the complete set of discussion docs for the SDK is listed and linked below: // TODO - put this in a better order. -* xref:concept-docs:buckets-and-clusters.adoc[Buckets & Clusters] -* xref:concept-docs:collections.adoc[Collections & Scope] * xref:concept-docs:compression.adoc[Compression] * xref:concept-docs:data-model.adoc[Data Model] ** xref:concept-docs:documents.adoc[Documents] @@ -50,26 +48,26 @@ but the complete set of discussion docs for the SDK is listed and linked below: * xref:concept-docs:durability-replication-failure-considerations.adoc[Failure Considerations] * xref:concept-docs:encryption.adoc[Field Level Encryption] * xref:concept-docs:data-services.adoc[Service Selection / Querying your Data] -** xref:concept-docs:analytics-for-sdk-users.adoc[Analytics] -** xref:concept-docs:understanding-views.adoc[Map Reduce Views] +** xref:concept-docs:understanding-views.adoc[Map Reduce Views] [Deprecated] ** xref:concept-docs:n1ql-query.adoc[Query] ** xref:concept-docs:full-text-search-overview.adoc[Search] * xref:concept-docs:sdk-user-management-overview.adoc[User Management] ** xref:concept-docs:certificate-based-authentication.adoc[Cert Auth] -** xref:concept-docs:rbac.adoc[RBAC] // + -* xref:concept-docs:data-durability-acid-transactions.adoc[Data Modelling, Durability, and Consistency] -* xref:concept-docs:querying-your-data.adoc[] - -* xref:concept-docs:durability-replication-failure-considerations.adoc[] +=== Key Discussion Documents * xref:concept-docs:best-practices.adoc[] +* xref:concept-docs:data-durability-acid-transactions.adoc[Data Modelling, Durability, and Consistency] + +* xref:concept-docs:durability-replication-failure-considerations.adoc[] + * xref:concept-docs:management-api.adoc[Managing Couchbase] +* xref:concept-docs:querying-your-data.adoc[] * xref:project-docs:deployment.adoc[SDK Deployment] From c9110af68c5ee07b8c2d78769ee85fca1e5b2828 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 17:58:39 +0100 Subject: [PATCH 34/44] Alias for superfluous concept doc --- modules/howtos/pages/analytics-using-sdk.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/howtos/pages/analytics-using-sdk.adoc b/modules/howtos/pages/analytics-using-sdk.adoc index 7a7128b8..236250c2 100644 --- a/modules/howtos/pages/analytics-using-sdk.adoc +++ b/modules/howtos/pages/analytics-using-sdk.adoc @@ -1,6 +1,6 @@ = Analytics :description: Parallel data management for complex queries over many records, using a familiar SQL-like syntax. -:page-aliases: analytics-query.adoc +:page-aliases: analytics-query.adoc,concept-docs:analytics-for-sdk-users.adoc :page-edition: Enterprise Edition [abstract] From 5990ea60d0b2b7c87aba27ba7d3bbc41d49ee870 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 18:00:53 +0100 Subject: [PATCH 35/44] Collections alias --- .../concept-docs/pages/data-durability-acid-transactions.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/concept-docs/pages/data-durability-acid-transactions.adoc b/modules/concept-docs/pages/data-durability-acid-transactions.adoc index 273dcfc7..f33e8fc6 100644 --- a/modules/concept-docs/pages/data-durability-acid-transactions.adoc +++ b/modules/concept-docs/pages/data-durability-acid-transactions.adoc @@ -1,5 +1,6 @@ = Data Modelling, Durability, and Consistency // :page-aliases: durability-replication-failure-considerations.adoc +:page-aliases: concept-docs:collections.adoc :description: Performance, availability, consistency -- balance your priorities, and model your data to achieve these goals. :page-toclevels: 2 :anyreplica-api: pass:q[https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/AsyncCollection.html#getAnyReplica(java.lang.String,com.couchbase.client.java.kv.GetAnyReplicaOptions)] From 1ecde06d07fc707e503728b1764ca8709aab5f2a Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 15 Sep 2026 18:02:02 +0100 Subject: [PATCH 36/44] Alias for removed legacy buckets/clusters page --- modules/howtos/pages/provisioning-cluster-resources.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/howtos/pages/provisioning-cluster-resources.adoc b/modules/howtos/pages/provisioning-cluster-resources.adoc index 98d20609..103d9365 100644 --- a/modules/howtos/pages/provisioning-cluster-resources.adoc +++ b/modules/howtos/pages/provisioning-cluster-resources.adoc @@ -1,7 +1,7 @@ = Provisioning Cluster Resources :description: Provisioning cluster resources is managed at the collection or bucket level, depending upon the service affected. :navtitle: Provisioning Cluster Resources -:page-aliases: ROOT:managing-clusters.adoc +:page-aliases: ROOT:managing-clusters.adoc,concept-docs:buckets-and-clusters.adoc :page-toclevels: 2 // API refs From 84d4161f48362b8ce3c866c84c1b73de3a2bbf96 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 16 Sep 2026 11:15:39 +0100 Subject: [PATCH 37/44] Liquibase DOC-11885 --- modules/project-docs/pages/third-party-integrations.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/modules/project-docs/pages/third-party-integrations.adoc b/modules/project-docs/pages/third-party-integrations.adoc index 76f121c6..7fdd09da 100644 --- a/modules/project-docs/pages/third-party-integrations.adoc +++ b/modules/project-docs/pages/third-party-integrations.adoc @@ -35,3 +35,6 @@ The philosophy of the project claims to "strongly favor simplicity and conventio In CouchMove you write your migrations in {sqlpp_url}[{sqlpp} (formerly N1QL)], while in https://github.com/couchbaselabs/CouchVersion[CouchVersion] you can write them using the Java SDK, which essentially allow you to create more complex migrations. CouchVersion provides a new approach for adding changes (change sets) based on Java classes and methods with appropriate annotations. + +Liquibase manages schema changes, storing changes in text files as XML, YAML, JSON, or SQL. +It is often used as a migration tool, and Liquibase have made available a https://github.com/liquibase/liquibase-couchbase[Couchbase extension for Liquibase] for Couchbase Server 7.0+. From ea79a2a67e93b3f3192584c567892ee7db0b24ea Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 16 Sep 2026 16:57:00 +0100 Subject: [PATCH 38/44] include fix --- modules/project-docs/pages/compatibility.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc index cf0ee339..961ca328 100644 --- a/modules/project-docs/pages/compatibility.adoc +++ b/modules/project-docs/pages/compatibility.adoc @@ -80,12 +80,12 @@ include::{version-common}@sdk:shared:partial$compat.adoc[tag=virtual] // Network Requirements -include::{version-common}@sdk:shared:partial$compat[tag=network-requirements] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=network-requirements] // Serverless Environments -include::{version-common}@sdk:shared:partial$compat[tag=serverless] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=serverless] @@ -100,7 +100,7 @@ Couchbase SDKs are tested against a variety of different environments to ensure === Couchbase Version/SDK Version Matrix -include::{version-common}@sdk:shared:partial$compat[tag=matrix-notes1] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=matrix-notes1] @@ -130,7 +130,7 @@ include::{version-common}@sdk:shared:partial$compat[tag=matrix-notes1] -include::{version-common}@sdk:shared:partial$compat[tag=matrix-notes2] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=matrix-notes2] From f48998113f777603d207fe59fb8e64bcacd9e429 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 16 Sep 2026 21:22:08 +0100 Subject: [PATCH 39/44] encore, une autre fixe --- modules/project-docs/pages/compatibility.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc index 961ca328..2842cb39 100644 --- a/modules/project-docs/pages/compatibility.adoc +++ b/modules/project-docs/pages/compatibility.adoc @@ -167,7 +167,7 @@ include::{version-common}@sdk:shared:partial$compat.adoc[tag=cloud] |=== -include::{version-common}@sdk:shared:partial$compat[tag=feature-notes] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=feature-notes] From 7b2ddd1b87085172bc0bcc838ed57b3e70d920b0 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Tue, 29 Sep 2026 05:23:44 +0100 Subject: [PATCH 40/44] Older Server compat DOC-14743 --- modules/project-docs/pages/compatibility.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc index 2842cb39..b8bc2e25 100644 --- a/modules/project-docs/pages/compatibility.adoc +++ b/modules/project-docs/pages/compatibility.adoc @@ -121,7 +121,7 @@ include::{version-common}@sdk:shared:partial$compat.adoc[tag=matrix-notes1] | *✔* | *✔* -| *Server 7.2* +| *Server 7.2* ② | *◎* | *◎* | *✔* From 8f8abc0849e4141abd1184b5627349bea564c9cc Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 7 Oct 2026 18:35:55 +0100 Subject: [PATCH 41/44] DOC-14538 CNG standalone --- modules/howtos/pages/managing-connections.adoc | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/modules/howtos/pages/managing-connections.adoc b/modules/howtos/pages/managing-connections.adoc index 6d13d623..ff5c0e36 100644 --- a/modules/howtos/pages/managing-connections.adoc +++ b/modules/howtos/pages/managing-connections.adoc @@ -284,12 +284,7 @@ quarkus.couchbase.password=password == Cloud Native Gateway -Couchbase's next generation connection protocol, introduced in Java SDK 3.5 and xref:operator::concept-cloud-native-gateway.adoc[Couchbase Autonomous Operator 2.6.1] -- -and available as a xref:cloud-native-gateway:intro:about-cng.adoc[standalone product] for use with self-managed Couchbase Server from 8.0 onwards -- -can be enabled simply by changing the connection string to `couchbase2://` but there are a few differences to be aware of, described <<#limitations,below>>. - -The protocol implements a gRPC-style interface between the SDK and Couchbase Server. - +include::{version-common}@sdk:shared:partial$managing-connections.adoc[tag=cng] === Limitations From ed632a3783011f75e4b32ae46e6a8ade61a575c1 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Mon, 12 Oct 2026 22:12:01 +0100 Subject: [PATCH 42/44] 3.13 --- README.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.adoc b/README.adoc index aa8bcf8a..72b45dc7 100644 --- a/README.adoc +++ b/README.adoc @@ -1,9 +1,9 @@ = Couchbase Java SDK Documentation -This repository hosts the documentation source for the https://docs.couchbase.com/java-sdk/3.12/hello-world/overview.html[Couchbase Java SDK]. +This repository hosts the documentation source for the https://docs.couchbase.com/java-sdk/3.13/hello-world/overview.html[Couchbase Java SDK]. -This branch documents the 3.12 release of the SDK. -It follows the https://docs.couchbase.com/java-sdk/3.11/project-docs/compatibility.html#api-version[SDK 3.10 API]. +This branch documents the 3.13 release of the SDK. +It follows the https://docs.couchbase.com/java-sdk/3.13/project-docs/compatibility.html#api-version[SDK 3.10 API]. This branch reflects the new Information Architecture for the SDK docs, helping to guide new-to-Couchbase users through the pitfalls of a complex distributed system. From 995f94210fcddb730a1c9310659de3beedae74d7 Mon Sep 17 00:00:00 2001 From: David Nault Date: Mon, 12 Oct 2026 22:38:04 -0700 Subject: [PATCH 43/44] Release notes for 3.13.0 (#497) * Release notes for 3.13.0 * Gardening DOC-14041 --------- Co-authored-by: Richard Smedley --- .../project-docs/pages/sdk-release-notes.adoc | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index e3ff0db5..54b7a8d7 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -57,8 +57,91 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea [v3.13.0] === Version 3.13.0 (13 October 2026) +https://packages.couchbase.com/clients/java/3.13.0/Couchbase-Java-Client-3.13.0.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.13.0/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.13.0/[Core API Reference] +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + +==== New Features + +* https://jira.issues.couchbase.com/browse/JCBC-2224[JCBC-2224]: +Added an option for Hybrid Search Score Fusion, for future releasese of Couchbase Server. +// Added an option for Hybrid Search Score Fusion when using Couchbase Server 8.5 or later. + +* https://jira.issues.couchbase.com/browse/JCBC-2226[JCBC-2226]: +Added `collection.getReplica()`, which allows reading from a specific replica. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1767[JVMCBC-1767], https://jira.issues.couchbase.com/browse/JVMCBC-1768[JVMCBC-1768]: +Added versions of `EncryptionModule` and `JsonValueModule` that are compatible with Jackson 3. + +==== Improvements + +* https://jira.issues.couchbase.com/browse/JVMCBC-1773[JVMCBC-1773]: +Added handling for a new query error code introduced in Couchbase Server 7.6, mapped to `AuthenticationFailureException`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1756[JVMCBC-1756]: +The executor for blocking transaction operations is now backed by virtual threads for improved scalability when running on Java 21 or later. +This change only affects the reactive Java and Scala transaction APIs, as well as all transactions in Kotlin. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1765[JVMCBC-1765]: +Upgraded Netty to `4.2.19`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1766[JVMCBC-1766]: +Upgraded Jackson to `2.21.7` / `3.1.7`. + +==== Deprecations + +* https://jira.issues.couchbase.com/browse/JVMCBC-1741[JVMCBC-1741]: +`SaslMechanism.SCRAM_SHA1` is now deprecated, and is no longer used unless your application builds a custom `PasswordAuthenticator` that explicitly allows it. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1751[JVMCBC-1751]: +The overload of `Cluster.connect()` that takes a `SeedNode` set is now deprecated in favor of the overload that takes a connection string, which is more versatile. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1772[JVMCBC-1772]: +Deprecated the `IoEnvironment` methods that accept a Netty `EventLoopGroup`, since a future SDK version might not use Netty. +Users who need to tune I/O threading should use `eventLoopThreadCount` instead. + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1771[JVMCBC-1771]: +Fixed a rare deadlock during bucket bootstrap that could cause the SDK to hang while fetching the bucket topology. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1769[JVMCBC-1769]: +Fixed a rare race condition that could cause problems with topology updates. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1764[JVMCBC-1764]: +Fixed a `NullPointerException` related to executing a prepared statement (a query with `adhoc=false`) in a transaction. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1754[JVMCBC-1754]: +Reduced the occurrence of false positive `WatchdogInvalidStateIdentifiedEvent` log messages in deployments using private endpoints, and other environments where node hostnames are not unique. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1763[JVMCBC-1763]: +Tracing spans for KV range scan are now completed correctly. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1743[JVMCBC-1743]: +Fixed a bug that caused the SDK to ignore the "field" parameter of a regexp search query when using the `couchbase2://` protocol. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1446[JVMCBC-1446]: +Fixed an otherwise harmless race condition that caused "Could not locate a single global configuration" warnings in the log. +* https://jira.issues.couchbase.com/browse/JVMCBC-1745[JVMCBC-1745], https://jira.issues.couchbase.com/browse/JVMCBC-1747[JVMCBC-1747]: +The `META-INF/io.netty.versions.properties` and `META-INF/native-image` resources from the SDK's repackaged version of Netty are now relocated to avoid conflicts with vanilla Netty. == Java SDK 3.12 Releases From 3338abd2a420cb1a45e9bee390f5ba0662ba56e5 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 13 Oct 2026 12:34:59 +0000 Subject: [PATCH 44/44] Bump io.grpc:grpc-netty-shaded from 1.28.0 to 1.75.0 Bumps [io.grpc:grpc-netty-shaded](https://github.com/grpc/grpc-java) from 1.28.0 to 1.75.0. - [Release notes](https://github.com/grpc/grpc-java/releases) - [Commits](https://github.com/grpc/grpc-java/compare/v1.28.0...v1.75.0) --- updated-dependencies: - dependency-name: io.grpc:grpc-netty-shaded dependency-version: 1.75.0 dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index e680bfde..f81b7d7d 100644 --- a/pom.xml +++ b/pom.xml @@ -92,7 +92,7 @@ io.grpc grpc-netty-shaded - 1.28.0 + 1.75.0