From e2ae249efb2248c5420e204862c57cb6c906e978 Mon Sep 17 00:00:00 2001 From: Miguel Grinberg Date: Thu, 9 Oct 2025 12:41:07 +0100 Subject: [PATCH 1/2] Update the compatiblity mode section of the docs --- docs/reference/connecting.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/reference/connecting.md b/docs/reference/connecting.md index 27f7fecbc..946c1d4ec 100644 --- a/docs/reference/connecting.md +++ b/docs/reference/connecting.md @@ -277,12 +277,11 @@ client = Elasticsearch( ``` -## Enabling the Compatibility Mode [compatibility-mode] +## Version Compatibility [compatibility-mode] -The {{es}} server version 8.0 is introducing a new compatibility mode that allows you a smoother upgrade experience from 7 to 8. In a nutshell, you can use the latest 7.x Python {{es}} {{es}} client with an 8.x {{es}} server, giving more room to coordinate the upgrade of your codebase to the next major version. - -If you want to leverage this functionality, please make sure that you are using the latest 7.x Python {{es}} client and set the environment variable `ELASTIC_CLIENT_APIVERSIONING` to `true`. The client is handling the rest internally. For every 8.0 and beyond Python {{es}} client, you’re all set! The compatibility mode is enabled by default. +Since version 8.0, the {{es}} server supports a compatibility mode that allows smoother upgrade experiences. In a nutshell, this makes it possible to use the previous major version of the Python {{es}} client with it, giving more room to coordinate the upgrade of your codebase to the next major version. +For example, to upgrade a system that uses {{es}} 8.x you can upgrade the {{es}} server to 9.x first, and the 8.x Python {{es}} client will continue to work (aside from any breaking changes, which should be listed in the server release notes). You can continue using the 8.x client during the server migration, and only upgrade it once the server migration is complete. The process is described in detail in the [REST API compatibility workflow](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/compatibility#_rest_api_compatibility_workflow) section of the {{es}} documentation. ## Using the Client in a Function-as-a-Service Environment [connecting-faas] From 6d2cf6d0d104863f7890042e472b09768ab70aed Mon Sep 17 00:00:00 2001 From: Miguel Grinberg Date: Mon, 13 Oct 2025 12:25:51 +0100 Subject: [PATCH 2/2] merge with compatiblity section in index.md --- docs/reference/connecting.md | 6 ------ docs/reference/index.md | 8 +++++++- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/reference/connecting.md b/docs/reference/connecting.md index 946c1d4ec..56b3aaee7 100644 --- a/docs/reference/connecting.md +++ b/docs/reference/connecting.md @@ -277,12 +277,6 @@ client = Elasticsearch( ``` -## Version Compatibility [compatibility-mode] - -Since version 8.0, the {{es}} server supports a compatibility mode that allows smoother upgrade experiences. In a nutshell, this makes it possible to use the previous major version of the Python {{es}} client with it, giving more room to coordinate the upgrade of your codebase to the next major version. - -For example, to upgrade a system that uses {{es}} 8.x you can upgrade the {{es}} server to 9.x first, and the 8.x Python {{es}} client will continue to work (aside from any breaking changes, which should be listed in the server release notes). You can continue using the 8.x client during the server migration, and only upgrade it once the server migration is complete. The process is described in detail in the [REST API compatibility workflow](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/compatibility#_rest_api_compatibility_workflow) section of the {{es}} documentation. - ## Using the Client in a Function-as-a-Service Environment [connecting-faas] This section illustrates the best practices for leveraging the {{es}} client in a Function-as-a-Service (FaaS) environment. diff --git a/docs/reference/index.md b/docs/reference/index.md index 6046d7801..03143bbb2 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -69,8 +69,14 @@ Compatibility does not imply full feature parity. New {{es}} features are suppor {{es}} language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees. +### Major version upgrades + :::{tip} To upgrade to a new major version, first upgrade {{es}}, then upgrade the Python {{es}} client. ::: -If you need to work with multiple client versions, note that older versions are also released as `elasticsearch7` and `elasticsearch8`. +Since version 8.0, the {{es}} server supports a compatibility mode that allows smoother upgrade experiences. In a nutshell, this makes it possible to upgrade the {{es}} server to the next major version, while continuing to use the same client. This gives more room to coordinate the upgrade of your codebase to the next major version. + +For example, to upgrade a system that uses {{es}} 8.x you can upgrade the {{es}} server to 9.x first, and the 8.x Python {{es}} client will continue to work (aside from any breaking changes, which should be listed in the server release notes). You can continue using the 8.x client during the server migration, and only upgrade it once the server migration is complete. The process is described in detail in the [REST API compatibility workflow](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/compatibility#_rest_api_compatibility_workflow) section of the {{es}} documentation. + +If you need to work with multiple client versions, note that older versions are also released with the `elasticsearch8` and `elasticsearch9` package names so that they can be installed together.