How to update your app to the latest Meilisearch version

Carolina Ferreira -

The following guide will walk you through the steps required to update your Meilisearch instance on DigitalOcean, AWS, or GCP when using the Meilisearch official images.

Before you begin, please note the following:

  • This guide does not work for versions below v0.15. Since dumps were introduced in v0.15, you’ll need to reindex all your documents and settings manually if you are on v0.14 or below
  • If you are updating to v0.28 or above, keys imported from the old version will have their key and uid fields regenerated
  • You’ll need to connect via SSH to your cloud instance, and depending on the user you are connecting with (root, admin, etc.), you may need to prefix some commands with sudo

Also, if you are using v0.22 or above, you can use our migration script and let it do all the work for you!

Step 1: Check your Meilisearch version

You need to know your Meilisearch version. If you don’t know or are not sure, you can use the get version endpoint:

curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'Authorization: Bearer API_KEY'

If you get a missing_authorization_header error code, you might be on v0.24 or below. Change the authorization header to X-MEILI-API-KEY as follows:

curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'X-Meili-API-Key: API_KEY'

Check your pkgVersion if it's “0.21.0” or higher, you can go straight to step 3. If not, please proceed to the next step.

Step 2: Set all fields as displayed attributes

⚠️
This step is only mandatory if you are on v0.20 or below.

‌‌

When creating dumps using Meilisearch versions below v0.21, all fields must be displayed in order to be saved in the dump.

First, you need to verify the displayed attributes list. 

# whenever you see {index_uid}, replace it with your index's unique id
curl \
  -X GET 'http://<your-domain-name>/indexes/{index_uid}/settings/displayed-attributes' \
  -H 'X-Meili-API-Key: API_KEY'

If the response includes {'displayedAttributes': '["*"]'}, you can move on to step 3.

‌‌If it's something else, save the current list to restore it after the migration is complete, and proceed to reset the list of displayed attributes to its default value ([“*”]):

curl \
  -X DELETE 'http://<your-domain-name>/indexes/{index_uid}/settings/displayed-attributes' \
  -H 'X-Meili-API-Key: API_KEY'

This command returns an updateId. You can use this to track the status of the operation.

# replace {updateId} with the updateId returned by the previous request
curl \
  -X GET 'http://<your-domain-name>/indexes/{index_uid}/updates/{updateId}' \
  -H 'X-Meili-API-Key: API_KEY'

Once the status is processed, you're good to go.

Now that all fields are displayed proceed to the next step.

Step 3: Create the dump

Before creating your dump, make sure that your dump directory is accessible. By default, dumps are created in a folder called dumps in the configuration file directory: /var/opt/meilisearch/dumps.

‌‌You can then create a dump of your Meilisearch database:

# replace the header with -H 'X-Meili-API-Key: API_KEY' if you are on v0.24 or below
curl \
  -X POST 'http://<your-domain-name>/dumps' \
  -H 'Authorization: Bearer API_KEY'

‌‌If you are on v0.27 or below, dumps use a separate queue from the task queue. The response should return a dump uid. You can use it to track the status of the dump with the get dumps status endpoint:

# replace the header with -H 'X-Meili-API-Key: API_KEY' if you are on v0.24 or below
curl -X GET 'http://<your-domain-name>/dumps/{uid}/status' \
  -H 'Authorization: Bearer API_KEY'

Once the dump status is done, you can move on to the next step.

{
    "uid":"20221130-110940190",
    "status":"done",
    "startedAt":"2022-11-30T11:09:40.190772Z",
    "finishedAt":"2022-11-30T11:09:45.94484Z"
}

‌‌‌‌If you are on v0.28 or above, dumps are considered tasks and share the task queue. The response should then return a taskUid you can use to track its status with the get task endpoint:

curl \
  -X GET 'http://<your-domain-name>/tasks/{taskUid}' \
  -H 'Authorization: Bearer API_KEY’

‌‌Once the dumpCreation task shows "status": "succeeded", you're ready to move on to the next step.

{
  "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"
}

‌Step 4: Stop the Meilisearch instance

If you haven’t done it yet, connect via SSH to your cloud instance and execute the following command to stop Meilisearch. Remember you may need to prefix it with sudo if you are not connected as root.

systemctl stop meilisearch

‌‌Step 5: Save the current binary and database for backup

Move the binary of the current Meilisearch version and the database to the tmp/ folder:

mv /usr/bin/meilisearch /tmp
mv /var/lib/meilisearch/data.ms /tmp/

‌Step 6: Install the desired version of Meilisearch

‌‌‌‌You can use this command to download the Meilisearch binary. Replace {meilisearch_version} with the version of your choice formatted like this: vX.X.X.

curl "https://github.com/meilisearch/meilisearch/releases/download/{meilisearch_version}/meilisearch-linux-amd64" --output meilisearch --location --show-error

Make the meilisearch binary executable:

chmod +x meilisearch

Move the new Meilisearch binary to the directory containing the executable files:

mv meilisearch /usr/bin/meilisearch

Step 7: Launch Meilisearch and import the dump

‌Now that you’ve got the desired Meilisearch version, execute the command below to import the dump at launch.

Don’t forget to replace the dump_uid.dump with the actual dump file name.

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.

Step 8: Restart Meilisearch as a service

Once your dump has been correctly imported, press Ctrl+C  to stop Meilisearch. Next, execute the command below to run the script to configure Meilisearch and restart it as a service:

meilisearch-setup

Don’t forget to set displayedAttributes back to its previous value if necessary. You can do this using the update displayed attributes endpoint.

🎉 Congratulations! You have successfully migrated your Meilisearch database to the latest version!

Step 9: Clean files or rollback

Clean files

If you’ve gone through all the previous steps and Meilisearch is up and running, it’s time to do some cleanup. Remember those files we saved for backup? You can delete them with the following commands:

rm /tmp/meilisearch
rm -r /tmp/data.ms

‌Since you no longer need it, you can also delete the dump file:

rm /var/opt/meilisearch/dumps/{dump_uid.dump}

Ro‌‌llback

If for some reason, something went wrong, you can always roll back to the previous version. Move the files back to their previous location using:


mv /tmp/meilisearch /usr/bin/meilisearch
mv /tmp/data.ms /var/lib/meilisearch/data.ms

‌And run the configuration script: 

meilisearch-setup

‌‌Everything should be as it was. Phew!

I hope this guide has helped you to enjoy all the advantages of the latest version of Meilisearch. Don’t forget our support team is always ready to help! We have a dedicated support channel on our brand new Discord server!

‌‌‌‌‌‌‌‌‌‌