diff --git a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md index 4de0e82b5a4..0bf3ff9a397 100644 --- a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md +++ b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md @@ -4,23 +4,132 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and ## Notes -- This upgrade is only applicable for upgrading the enterprise edition of NebulaGraph v3.x (x < 4) to v{{nebula.release}}. For upgrading from version 3.4.0 and above to {{nebula.release}}, you can directly replace the binary files for an upgrade. For more information, see [Upgrade NebulaGraph to {{nebula.release}}](https://docs.nebula-graph.com.cn/{{nebula.release}}/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-graph-to-latest/). - - !!! note - - If your version is below 3.0.0, please upgrade to enterprise edition 3.1.0 before upgrading to v{{nebula.release}}. For details, see [Upgrade NebulaGraph Enterprise Edition 2.x to 3.1.0](https://docs.nebula-graph.io/3.1.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-graph-to-latest/). +- Rolling Upgrade is not supported. You must stop all the NebulaGraph services before the upgrade. +- There is no upgrade script. You have to manually upgrade each server in the cluster. + - The IP address of the machine performing the upgrade operation must be the same as the original machine. +- You must have the sudo privileges to complete the steps in this topic. - The remaining disk space on the machine must be at least 1.5 times the size of the original data directory. + +## Upgrade influences + + + +- Client compatibility + + After the upgrade, you will not be able to connect to NebulaGraph from old clients. You will need to upgrade all clients to a version compatible with NebulaGraph {{nebula.release}}. + +- Configuration changes + + A few configuration parameters have been changed. For more information, see the release notes and configuration docs. + +- nGQL compatibility + + The nGQL syntax is partially incompatible: + + - Disable the `YIELD` clause to return custom variables. + + - The `YIELD` clause is required in the `FETCH`, `GO`, `LOOKUP`, `FIND PATH` and `GET SUBGRAPH` statements. + + - It is required to specify a tag to query properties of a vertex in a `MATCH` statement. For example, from `return v.name` to `return v.player.name`. + +- Full-text indexes + + Before upgrading a NebulaGraph cluster with full-text indexes deployed, you must manually delete the full-text indexes in Elasticsearch, and then run the `SIGN IN` command to log into ES and recreate the indexes after the upgrade is complete. To manually delete the full-text indexes in Elasticsearch, you can use the curl command `curl -XDELETE -u : ':/'`, for example, `curl -XDELETE -u elastic:elastic 'http://192.168.8.xxx:9200/nebula_index_2534'`. If no username and password are set for Elasticsearch, you can omit the `-u :` part. + + !!! note + + For upgrades from version 3.5.0 and later to {{nebula.release}}, there's no need to manually delete the full-text indexes. + +## Upgrading to {{nebula.release}} from version 3.4.0 and above + + +1. Stop all {{nebula.name}} services. + + ``` + /scripts/nebula.service stop all + ``` + + Replace `install_path` with the installation directory of the {{nebula.name}} instance you want to upgrade. + + Allow approximately 1 minute for the `storaged` process to flush data. You can continue by running the `nebula.service status all` command to confirm that all services have stopped. For detailed instructions on starting and stopping services, refer to [Managing Services](../manage-service.md). + + !!! note + + If services cannot be stopped within 20 minutes, abandon the upgrade, and contact customer support. + + !!! caution + + Starting from version 3.0.0, {{nebula.name}} supports inserting points without tags. To retain points without tags, add the `--graph_use_vertex_key=true` flag to the configuration file (`nebula-graphd.conf`) of all Graph services within the cluster and add the `--use_vertex_key=true` flag to the configuration file (`nebula-storaged.conf`) of all Storage services. + +2. Prepare the installation package for {{nebula.name}} {{nebula.release}} and extract it. You can specify any installation directory. + +3. In the directory of {{nebula.release}}, use the new binary files from its `bin` directory to replace the old binary files in the `bin` directory of the {{nebula.name}} installation path. + + !!! note + Update the binary files for each machine where {{nebula.name}} services are deployed. + + + +4. In the `nebula-metad.conf` configuration file of NebulaGraph, add the `license_manager_url` parameter and set it to the LM's path. + + The LM is used to verify {{nebula.name}}'s licensing information. For details, see [LM Configuration](../../9.about-license/2.license-management-suite/3.license-manager.md). + + !!! note + Starting from version 3.5.0, {{nebula.name}} enables license validation, so it's necessary to install and configure LM. + +5. Start all Meta services. + + ``` + /scripts/nebula-metad.service start + ``` + + After starting, the Meta services will elect a leader. This process takes a few seconds. + + Once started, you can start any Graph service node and connect to it using {{nebula.name}}. Run [`SHOW HOSTS meta`](../../3.ngql-guide/7.general-query-statements/6.show/6.show-hosts.md) and [`SHOW META LEADER`](../../3.ngql-guide/7.general-query-statements/6.show/19.show-meta-leader.md). If they return the status of the Meta node correctly, the Meta service has started successfully. + + !!! note + + If there are any exceptions during startup, abandon the upgrade, and contact customer support. + +5. Start all Graph and Storage services. !!! note - To manually delete the full-text indexes in Elasticsearch, you can use the curl command `curl -XDELETE -u : ':/'`, for example, `curl -XDELETE -u elastic:elastic 'http://192.168.8.223:9200/nebula_index_2534'`. If no username and password are set for Elasticsearch, you can omit the `-u :` part. + If there are any exceptions during startup, abandon the upgrade, and contact customer support. -## Steps +6. Connect to the new version of {{nebula.name}} and verify that the service is operational and that the data is intact. For information on connecting to the service, refer to [Connecting to Nebula Graph](../connect-to-nebula-graph.md). + + Some reference commands to test the upgrade are as follows: + + ```ngql + nebula> SHOW HOSTS; + nebula> SHOW HOSTS storage; + nebula> SHOW SPACES; + nebula> USE + nebula> SHOW PARTS; + nebula> SUBMIT JOB STATS; + nebula> SHOW STATS; + nebula> MATCH (v) RETURN v LIMIT 5; + ``` + +## Upgrade 3.x(x < 4)to {{nebula.release}} 1. [Contact us](https://www.nebula-graph.io/contact) to obtain the installation package of the enterprise edition of NebulaGraph v{{nebula.release}} and install it. @@ -32,11 +141,29 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and Please ensure that the number of storage paths set for the `--data_path` parameter in the Meta and Storage service configuration files of the {{nebula.release}} cluster is the same as that for the `--data_path` parameter in the configuration files of the 3.x cluster. Otherwise, the upgraded cluster will not start. -1. Stop the enterprise edition of v3.x services. For details see [Manage NebulaGraph services](https://docs.nebula-graph.io/3.5.0-sc/4.deployment-and-installation/manage-service/). +2. Back up the data and the binary files in the subdirectory `bin` of the 3.x cluster. + + !!! note + + The backup is used for rollback in case of upgrade failure. The backup files are not used in the upgrade process. + +3. Stop the enterprise edition of v3.x services. For details see [Manage NebulaGraph services](https://docs.nebula-graph.io/3.5.0-sc/4.deployment-and-installation/manage-service/). Run the `nebula.service status all` command to confirm that all services have been stopped after running the command. -3. In the installation directory of the Enterprise Edition NebulaGraph v{{nebula.release}}, run the following commands to upgrade the Storage and Meta services. + +4. In the subdirectory `etc` of the {{nebula.name}} v{{nebula.release}} installation directory, update the configuration files (if there have been any configuration updates previously). + + !!! note + + If there were no configuration updates previously, you can skip this step. + +5. In the `nebula-metad.conf` file of {{nebula.name}} v{{nebula.release}}, set `license_manager_url` to the URL of [LM](../../9.about-license/2.license-management-suite/3.license-manager.md). + + !!! note + For the Enterprise Edition of NebulaGraph v3.5.0 or later, you need to install and configure LM to verify the license used to start NebulaGraph. + +6. In the installation directory of the Enterprise Edition NebulaGraph v{{nebula.release}}, run the following commands to upgrade the Storage and Meta services. - Upgrade the Storage service: @@ -89,7 +216,8 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and After the upgrade, a `data` directory will be generated in the v{{nebula.release}} installation directory, containing the upgraded data files. -4. Start and connect to the NebulaGraph v{{nebula.release}} enterprise edition service and verify that the data is correct. The following commands can be used as reference: + +7. Start and connect to the NebulaGraph v{{nebula.release}} enterprise edition service and verify that the data is correct. The following commands can be used as reference: ``` nebula> SHOW HOSTS; @@ -102,11 +230,15 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and nebula> MATCH (v) RETURN v LIMIT 5; ``` -## Docker Compose Deployment -!!! caution - - For NebulaGraph deployed using Docker Compose, it is recommended to redeploy the new version and import data. + +