How to update your app to the latest Meilisearch version

Share the article

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:

bash

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:

bash

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.

bash

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 ([“*”]):

bash

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

bash

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:

bash

‌‌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:

bash

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

JSON

‌‌‌‌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:

bash

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

json

‌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.

bash

‌‌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:

bash

‌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.

json

Make the meilisearch binary executable:

bash

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

bash

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.

json

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:

json

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:

bash

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

bash

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:

bash

‌And run the configuration script:

bash

‌‌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!

‌‌‌‌‌‌‌‌‌‌