# Update to the latest Meilisearch version

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

TIP

If you are running Meilisearch as a systemctl service using v0.22 or above, try our migration script (opens new window).

DANGER

This guide only works for versions v0.15 and above. If you are using an older version, please contact support (opens new window) for more information.

# Version-specific update instructions

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.

  • If you are updating from v0.20 or below, please ensure all updates finish processing before creating the dump. enqueued updates will not be exported and may result in data loss.

  • If you are using v0.24 or below, use the X-Meili-API-Key: API_KEY authorization header:

curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'X-Meili-API-Key: API_KEY'  
  • 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 before creating your dump.

  • If you are updating to v0.28 or above, existing keys will have their key and uid fields regenerated.

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

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

The response should look something like this:

{
  "commitSha": "stringOfLettersAndNumbers",
  "commitDate": "YYYY-MM-DDTimestamp",
  "pkgVersion": "x.y.z"
}

If your pkgVersion is 0.21 or above, you can jump to creating the dump. If not, proceed to the next step.

# Set all fields as displayed attributes

NOTE

If your dump was created in Meilisearch v0.21 or above, skip this step.

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

Start by verifying that all attributes are included in 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 for all indexes is {'displayedAttributes': '["*"]'}, you can move on to the next step.

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

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. Use the get update endpoint to track the status of the operation:

 # replace {indexUid} with the uid of your index and {updateId} with the updateId returned by the previous request
  curl \
    -X GET 'http://<your-domain-name>/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.

# Create the dump

Before creating your dump, make sure that your dump directory is somewhere accessible. By default, dumps are created in a folder called dumps at the root of your Meilisearch directory.

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:

You can then create a dump of your database:

curl \
  -X POST 'http://<your-domain-name>/dumps' \
  -H 'Authorization: Bearer API_KEY'
# -H 'X-Meili-API-Key: API_KEY' for v0.24 or below

The server should return a response that looks like this:

{
  "taskUid": 1,
  "indexUid": null,
  "status": "enqueued",
  "type": "dumpCreation",
  "enqueuedAt": "2022-06-21T16:10:29.217688Z"
}

Use the taskUid to track the status of your dump. Keep in mind that the process can take some time to complete.

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:

  curl \
    -X GET 'http://<your-domain-name>/dumps/:dump_uid/status'
    -H 'Authorization: Bearer API_KEY' 
  # -H 'X-Meili-API-Key: API_KEY' for v0.24 or below

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

# Step 2: Prepare for migration

# Stop the Meilisearch instance

Stop your Meilisearch instance.

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

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:

# Install the desired version of Meilisearch

Install the latest version of Meilisearch using:

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

# Step 3: Import data

# Launch Meilisearch and import the dump

Execute the command below to import the dump at launch:

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.

# 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

If required, set displayedAttributes back to its previous value using the update displayed attributes endpoint.

# 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 (opens new window).

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, and feel free to reach out for help (opens new window) 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:

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: