diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index c67b025e64..247aaa9d9f 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -910,25 +910,26 @@ settings_guide_typo_tolerance_1: |- }' updating_guide_check_version_new_authorization_header: |- curl \ - -X GET 'http://localhost:7700/version' \ + -X GET 'http:///version' \ -H 'Authorization: Bearer API_KEY' updating_guide_check_version_old_authorization_header: |- curl \ - -X GET 'http://localhost:7700/version' \ + -X GET 'http:///version' \ -H 'X-Meili-API-Key: API_KEY' -updating_guide_get_displayed_attributes_new: |- +updating_guide_get_displayed_attributes_old_authorization_header: |- # whenever you see {index_uid}, replace it with your index's unique id curl \ - -X GET 'http://localhost:7700/indexes/{index_uid}/settings/displayed-attributes' \ - -H 'Authorization: Bearer API_KEY' -updating_guide_reset_displayed_attributes_new: |- + -X GET 'http:///indexes/{index_uid}/settings/displayed-attributes' \ + -H 'X-Meili-API-Key: API_KEY' +updating_guide_reset_displayed_attributes_old_authorization_header: |- curl \ - -X DELETE 'http://localhost:7700/indexes/{index_uid}/settings/displayed-attributes' \ - -H 'Authorization: Bearer API_KEY' + -X DELETE 'http:///indexes/{index_uid}/settings/displayed-attributes' \ + -H 'X-Meili-API-Key: API_KEY' updating_guide_create_dump: |- curl \ - -X POST 'http://localhost:7700/dumps' \ + -X POST 'http:///dumps' \ -H 'Authorization: Bearer API_KEY' + # -H 'X-Meili-API-Key: API_KEY' for v0.24 or below getting_started_typo_tolerance: |- curl \ -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 50ff3f3426..23e5954206 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -136,8 +136,8 @@ typo_tolerance_guide_4: |- settings_guide_typo_tolerance_1: |- updating_guide_check_version_new_authorization_header: |- updating_guide_check_version_old_authorization_header: |- -updating_guide_get_displayed_attributes_new: |- -updating_guide_reset_displayed_attributes_new: |- +updating_guide_get_displayed_attributes_old_authorization_header: |- +updating_guide_reset_displayed_attributes_old_authorization_header: |- updating_guide_create_dump: |- getting_started_typo_tolerance: |- settings_guide_pagination_1: |- diff --git a/learn/advanced/geosearch.md b/learn/advanced/geosearch.md index 5950e64b84..2ee65806b2 100644 --- a/learn/advanced/geosearch.md +++ b/learn/advanced/geosearch.md @@ -2,6 +2,10 @@ Meilisearch allows you to filter and sort results based on their geographic location. This can be useful when you only want results within a specific area or when sorting results based on their distance from a specific location. +::: danger `_geo` field in v0.27, v0.28, and v0.29 +Due to Meilisearch allowing malformed `_geo` fields in the above-mentioned versions, please ensure the `_geo` field follows the correct format. +::: + ## Preparing documents for location-based search In order to start filtering and sorting documents based on their geographic location, you must make sure they contain a valid `_geo` field. diff --git a/learn/advanced/updating.md b/learn/advanced/updating.md index b749f6b6dc..f315c1b957 100644 --- a/learn/advanced/updating.md +++ b/learn/advanced/updating.md @@ -1,30 +1,40 @@ +--- +sidebarDepth: 2 +--- + # Update to the latest Meilisearch version -Currently, Meilisearch databases can only be opened by the Meilisearch version you used to create them. The following guide will walk you through all the steps to migrate an existing database from an older version of Meilisearch to the most recent one. +Currently, Meilisearch databases are only compatible with the version of Meilisearch used to create them. The following guide will walk you through using a [dump](/learn/advanced/dumps.md) to migrate an existing database from an older version of Meilisearch to the most recent one. + +If you're updating your Meilisearch instance on cloud platforms like DigitalOcean, AWS, or GCP, ensure that you can connect to your cloud instance via SSH. Depending on the user you are connecting with (root, admin, etc.), you may need to prefix some commands with `sudo`. -If you already have a Meilisearch database with some data you don’t want to lose, you are in the right place! +::: tip +If you are running Meilisearch as a `systemctl` service using v0.22 or above, try our [migration script](https://github.com/meilisearch/meilisearch-migration). +::: ::: danger -This guide does not work for versions below v0.15. For more information, [contact support](https://discord.gg/meilisearch). +This guide only works for versions v0.15 and above. If you are using an older version, please [contact support](https://discord.gg/meilisearch) for more information. ::: -## Step 1: Verify your database version +## Version-specific update instructions -Before we begin, you need to verify the version of Meilisearch that's compatible with your database, in other words, the version that indexed the data. You can do so by launching a Meilisearch instance: +This section contains instructions for upgrading from specific versions. Most versions don't require version-specific steps and you should be able to upgrade directly. If the version you are upgrading from isn't listed here, no additional steps are required. -```bash -./meilisearch --master-key="MASTER_KEY" -``` +- If you are using **v0.24 or below**, use the `X-Meili-API-Key: API_KEY` authorization header: + + -If Meilisearch launches successfully, use the get version endpoint, note your `pkgVersion`, and [proceed to the next step](#step-2-set-all-fields-as-displayed-attributes). +- Due to an error affecting `_geo` fields in Meilisearch **v0.27, v0.28, and v0.29**, you might not be able to import your dump. Please ensure the `_geo` field follows the [correct format](/learn/advanced/geosearch.md#preparing-documents-for-location-based-search) before creating your dump. - +- If you are **updating to v0.28 or above**, existing keys will have their `key` and `uid` fields regenerated. -::: note -If Meilisearch returns a [`missing_authorization_header`](/reference/errors/error_codes.md#missing-authorization-header) error code, you might be using v0.24 or below. Change the authorization header to `X-MEILI-API-KEY: apiKey`: +## Step 1: Export data - -::: +### Verify your database version + +First, verify the version of Meilisearch that's compatible with your database using the get version endpoint: + + The response should look something like this: @@ -36,106 +46,42 @@ The response should look something like this: } ``` -If you get the error `Cannot open database, expected Meilisearch engine version: 0.X.X, current engine version 0.Y.Y`, your database is not compatible with the currently installed Meilisearch version. - -In this case, you need to download the compatible version now (`0.X.X` in the above error message) to access and export your database. - -:::: tabs - -::: tab cURL -If you downloaded Meilisearch using `curl`, find and download the compatible version [here](https://github.com/meilisearch/meilisearch/releases) before continuing. -::: - -::: tab Homebrew - -Replace `0.X.X` with the version you would like to install. - -```bash -brew install meilisearch@0.X.X -``` - -::: - -::: tab Source - -Replace `0.X.X` with the version you would like to install. - -```bash -# clone Meilisearch and checkout the branch of the expected version -git clone https://github.com/meilisearch/meilisearch -cd MeiliSearch -git checkout v0.X.X - -# update the rust toolchain to the latest version -rustup update - -# compile the project -cargo build --release - -# execute the server binary -./target/release/meilisearch -``` - -::: - -::: tab APT - -Replace `0.X.X` with the version you would like to install. - -```bash -apt-get install meilisearch-http=0.X.X -``` - -::: - -::: tab Docker - -Replace `0.X.X` with the version you would like to install. +If your [`pkgVersion`](/reference/api/version.md#version-object) is 0.21 or above, you can jump to [creating the dump](#create-the-dump). If not, proceed to the next step. -```bash -docker run -it --rm \ - -p 7700:7700 \ - -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v0.X.X -``` - -::: - -:::: - -:::note -If you are updating to v0.28, keys imported from the old version will have their `key` and `uid` fields regenerated. -::: - -## Step 2: Set all fields as displayed attributes +### Set all fields as displayed attributes ::: note -If your dump was created in Meilisearch v0.21 or above, continue to [step 3](#step-3-create-the-dump). +If your dump was created in Meilisearch v0.21 or above, [skip this step](#create-the-dump). ::: When creating dumps using Meilisearch versions below v0.21, all fields must be [displayed](/learn/configuration/displayed_searchable_attributes.md#displayed-fields) in order to be saved in the dump. Start by verifying that all attributes are included in the displayed attributes list: - + -If the response is `{'displayedAttributes': '["*"]'}`, you can move on to the [next step](#step-3-create-the-dump). +If the response for all indexes is `{'displayedAttributes': '["*"]'}`, you can move on to the [next step](#create-the-dump). -If it's something else, then you need to reset the list of displayed attributes. Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards. +If the response is anything else, save the current list of displayed attributes in a text file and then reset the displayed attributes list to its default value `(["*"])`: - + -This command returns a `taskUid`. You can use this to [track the status of the operation](/reference/api/tasks.md#get-one-task). Once the status is `succeeded`, you're good to go. +This command returns an `updateId`. Use the get update endpoint to track the status of the operation: -Now that all fields are displayed, proceed to the next step. +```sh + # replace {indexUid} with the uid of your index and {updateId} with the updateId returned by the previous request + curl \ + -X GET 'http:///indexes/{indexUid}/updates/{updateId}' + -H 'X-Meili-API-Key: API_KEY' +``` + +Once the status is `processed`, you're good to go. Repeat this process for all indexes, then move on to creating your dump. -## Step 3: Create the dump +### Create the dump Before creating your dump, make sure that your [dump directory](/learn/configuration/instance_options.md#dumps-directory) is somewhere accessible. By default, dumps are created in a folder called `dumps` at the root of your Meilisearch directory. -::: note -If you are running Meilisearch in a service using `systemd`, like AWS or a DO droplet, the dumps folder can be found in the configuration file directory, `cd /var/opt/meilisearch/dumps`. -::: +**Cloud platforms** like DigitalOcean, AWS, and GCP are configured to store dumps in the `/var/opt/meilisearch/dumps` directory. If you're unsure where your Meilisearch directory is located, try this: @@ -201,59 +147,228 @@ The server should return a response that looks like this: } ``` -This command returns a `taskUid`. You can use this to [track the status](/reference/api/tasks.md#get-one-task) of your dump. Keep in mind that the process can take some time to complete. +Use the `taskUid` to [track the status](/reference/api/tasks.md#get-one-task) of your dump. Keep in mind that the process can take some time to complete. -Once the `dumpCreation` task shows `"status": "succeeded"`, you're ready to move on. +::: note +The response will vary slightly depending on your version. For v0.27 and below, the response returns a dump `uid`. You can track the status of the dump using the get dumps status endpoint: -```json -{ - "uid": 1, - "indexUid": null, - "status": "succeeded", - "type": "dumpCreation", - "canceledBy": null, - "details": { - "dumpUid": "20220621-161029217" - }, - "error": null, - "duration": "PT0.025872S", - "enqueuedAt": "2022-06-21T16:10:29.217688Z", - "startedAt": "2022-06-21T16:10:29.218297Z", - "finishedAt": "2022-06-21T16:10:29.244169Z" -} +```sh + curl \ + -X GET 'http:///dumps/:dump_uid/status' + -H 'Authorization: Bearer API_KEY' + # -H 'X-Meili-API-Key: API_KEY' for v0.24 or below ``` -## Step 4: Stop the Meilisearch instance +::: + +Once the `dumpCreation` task shows `"status": "succeeded"`, you're ready to move on. + +## Step 2: Prepare for migration -Stop your Meilisearch instance. If you're running Meilisearch as a `systemctl` service, you can stop your instance with: +### Stop the Meilisearch instance + +Stop your Meilisearch instance. + +:::: tabs + +::: tab Local installation + +If you're running Meilisearch locally, you can stop the program with `Ctrl + c`. + +::: + +::: tab Cloud platforms + +If you're running Meilisearch as a `systemctl` service, connect via SSH to your cloud instance and execute the following command to stop Meilisearch: ```bash systemctl stop meilisearch ``` -## Step 5: Delete the database folder +You may need to prefix the above command with `sudo` if you are not connected as root. -To delete the old Meilisearch version, you need to delete the `data.ms` folder. `data.ms` should be at the root of the Meilisearch binary, unless you chose [another location](/learn/configuration/instance_options.md#database-path). +::: + +:::: + +### Create a backup + +Instead of deleting `data.ms`, we suggest creating a backup in case something goes wrong. `data.ms` should be at the root of the Meilisearch binary unless you chose [another location](/learn/configuration/instance_options.md#database-path). + +On **cloud platforms**, you will find the `data.ms` folder at `/var/lib/meilisearch/data.ms`. + +Move the binary of the current Meilisearch installation and database to the `/tmp` folder: + +:::: tabs + +::: tab Local installation + +``` +mv /path/to/your/meilisearch/directory/meilisearch/data.ms /tmp/ +mv /path/to/your/meilisearch/directory/meilisearch /tmp/ +``` + +::: + +::: tab Cloud platforms + +``` +mv /usr/bin/meilisearch /tmp/ +mv /var/lib/meilisearch/data.ms /tmp/ +``` -::: note -If you are using the Meilisearch official images on DigitalOcean, AWS, or GCP, you will find the `data.ms` folder at `/var/lib/meilisearch/data.ms`. ::: -## Step 6: Import the dump +:::: + +### Install the desired version of Meilisearch + +Install the latest version of Meilisearch using: -Now that you’ve got your dump, install the [latest version of Meilisearch](/learn/getting_started/quick_start.md#setup-and-installation) and [import the dump](/learn/advanced/dumps.md#importing-a-dump) at launch using the CLI option: +:::: tabs + +::: tab Local installation ```bash -# launch the latest version of Meilisearch with the master key and import the specified dump file -./meilisearch --import-dump /dumps/your_dump_file.dump --master-key="MASTER_KEY" +curl -L https://install.meilisearch.com | sh +``` + +::: + +::: tab Cloud platforms + +```sh +# replace {meilisearch_version} with the version of your choice. Use the format: `vX.X.X` +curl "https://github.com/meilisearch/meilisearch/releases/download/{meilisearch_version}/meilisearch-linux-amd64" --output meilisearch --location --show-error +``` + +::: + +:::: + +Give execute permission to the Meilisearch binary: + +``` +chmod +x meilisearch +``` + +For **cloud platforms**, move the new Meilisearch binary to the `/usr/bin` directory: + +``` +mv meilisearch /usr/bin/meilisearch ``` ::: warning If you are using Meilisearch v0.20 or below, migration should be done in two steps. First, import your dump into an instance running any version of Meilisearch from v0.21 to v0.24, inclusive. Second, export another dump from this instance and import it to a final instance running your targeted version. + +Once Meilisearch v1 is released, this two-step process won't be necessary as v1 will be compatible with dumps from all previous versions. +::: + +## Step 3: Import data + +### Launch Meilisearch and import the dump + +Execute the command below to import the dump at launch: + +:::: tabs + +::: tab Local installation + +```bash +# replace {dump_uid.dump} with the name of your dump file +./meilisearch --import-dump dumps/{dump_uid.dump} --master-key="MASTER_KEY" +``` + +::: + +::: tab Cloud platforms + +```sh +# replace {dump_uid.dump} with the name of your dump file +meilisearch --db-path /var/lib/meilisearch/data.ms --import-dump "/var/opt/meilisearch/dumps/{dump_uid.dump}" +``` + ::: +:::: + Importing a dump requires indexing all the documents it contains. Depending on the size of your dataset, this process can take a long time and cause a spike in memory usage. -Finally, don’t forget to set `displayedAttributes` back to its previous value if necessary. You can do this using the [update displayed attributes endpoint](/reference/api/settings.md#update-displayed-attributes). +### Restart Meilisearch as a service + +If you're running a **cloud instance**, press `Ctrl`+`C` to stop Meilisearch once your dump has been correctly imported. Next, execute the following command to run the script to configure Meilisearch and restart it as a service: + +``` +meilisearch-setup +``` -Congratulations! You have successfully migrated your Meilisearch database to the latest version! 🎉 +If required, set `displayedAttributes` back to its previous value using the [update displayed attributes endpoint](/reference/api/settings.md#update-displayed-attributes). + +## Conclusion + +Now that your updated Meilisearch instance is up and running, verify that the dump import was successful and no data was lost. + +If everything looks good, then congratulations! You successfully migrated your database to the latest version of Meilisearch. Be sure to check out the [changelogs](https://github.com/meilisearch/MeiliSearch/releases). + +If something went wrong, you can always roll back to the previous version and try again. Be sure to check out the [version-specific update instructions](#version-specific-update-instructions), and feel free to [reach out for help](https://discord.gg/meilisearch) if the problem continues. + +### Delete backup files or rollback (_optional_) + +Delete the Meilisearch binary and `data.ms` folder created by the previous steps. Next, move the backup files back to their previous location using: + +:::: tabs + +::: tab Local installation + +``` +mv /tmp/meilisearch /path/to/your/meilisearch/directory/meilisearch +mv /tmp/data.ms /path/to/your/meilisearch/directory/meilisearch/data.ms +``` + +::: + +::: tab Cloud platforms + +``` +mv /tmp/meilisearch /usr/bin/meilisearch +mv /tmp/data.ms /var/lib/meilisearch/data.ms +``` + +::: + +:::: + +For **cloud platforms** run the configuration script at the root of your Meilisearch directory: + +``` +meilisearch-setup +``` + +If all went well, you can delete the backup files using: + +``` +rm -r /tmp/meilisearch +rm -r /tmp/data.ms +``` + +You can also delete the dump file if desired: + +:::: tabs + +::: tab Local installation + +``` +rm /path/to/your/meilisearch/directory/meilisearch/dumps/{dump_uid.dump} +``` + +::: + +::: tab Cloud platforms + +``` +rm /var/opt/meilisearch/dumps/{dump_uid.dump} +``` + +::: + +::::