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 or AWS, 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 migrating to the latest version of Meilisearch will cause you to skip multiple versions, this may require changes to your codebase. Refer to our version-specific update warnings for more details.
If you are running Meilisearch as a systemctl service using v0.22 or above, try our migration script.

​
Updating Meilisearch Cloud

Log into your Meilisearch Cloud account and navigate to the project you want to update. Click on the project you want to update. Look for the “General settings” section at the top of the page. Whenever a new version of Meilisearch is available, you will see an update button next to the “Meilisearch version” field.
Button to update Meilisearch version to 1.0.2
To update to the latest Meilisearch release, click the “Update to v.X.Y.Z” button. This will open a pop-up with more information about the update process. Read it, then click on “Update”. The “Status” of your project will change from “running” to “updating”.
Project update in progress
Once the project has been successfully updated, you will receive an email confirming the update and “Status” will change back to “running”.

​
Updating a self-hosted Meilisearch instance

You may update a self-hosted instance in one of two ways: with or without a dump.
This guide only works for v0.15 and above. If you are using an older Meilisearch release, please contact support for more information.

​
Dumpless upgrade experimental

Dumpless upgrades are available when upgrading from Meilisearch >=v1.12 to Meilisearch >=v1.13

​
Step 1: Make a backup

Dumpless upgrades are an experimental feature. Because of that, it may in rare occasions partially fail and result in a corrupted database. To prevent data loss, create a snapshot of your instance: 
curl \
  -X POST 'MEILISEARCH_URL/snapshots'
Meilisearch will respond with a partial task object. Use its taskUid to monitor the snapshot creation status. Once the task is completed, proceed to the next step.

​
Step 2: Stop the Meilisearch instance

Next, stop your Meilisearch instance.
If you’re running Meilisearch locally, stop the program by pressing Ctrl + c.

​
Step 3: Install the new Meilisearch binary

Install the latest version of Meilisearch using: 
curl -L https://install.meilisearch.com | sh
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 4: Relaunch Meilisearch

Execute the command below to import the dump at launch: 
./meilisearch --experimental-dumpless-upgrade
Meilisearch should launch normally and immediately create a new UpgradeDatabase task. This task is processed immediately and cannot be canceled. You may follow its progress by using the GET /tasks?types=UpgradeDatabase endpoint to obtain its taskUid, then querying GET /tasks/TASK_UID. While the task is processing, you may continue making search queries. You may also enqueue new tasks. Meilisearch will only process new tasks once UpgradeDatabase is completed.

​
Rolling back an update

If the upgrade is taking too long, or if after the upgrade is completed its task status is set to failed, you can cancel the upgrade task. Cancelling the update task automatically rolls back your database to its state before the upgrade began. After launching Meilisearch with --experimental-dumpless-upgrade flag:
  1. Cancel the databaseUpgrade task
  2. If you cancelled the update before it failed, skip to the next step. If the update failed, relaunch Meilisearch using the binary of the version you were upgrading to
  3. Wait for Meilisearch to process your cancellation request
  4. Replace the new binary with the binary of the previous version
  5. Relaunch Meilisearch
If you are upgrading Meilisearch to <= v1.14, you must instead restart your instance from the snapshot you generated during step 1. You may then retry the upgrade, or upgrade using a dump. You are also welcome to open an issue on the Meilisearch repository.

​
Using a dump

​
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 you get the missing_authorization_header error, you might be using v0.24 or below. For each command, replace the Authorization: Bearer header with the X-Meili-API-Key: API_KEY header:
curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'X-Meili-API-Key: API_KEY'
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
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 and AWS are configured to store dumps in the /var/opt/meilisearch/dumps directory. If you’re unsure where your Meilisearch directory is located, try this: 
which meilisearch
It should return something like this:
/absolute/path/to/your/meilisearch/directory
Due to an error allowing malformed _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.
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.
For v0.27 and below, the response to your request returns a dump uid. Use it with the /dumps/:dump_uid/status route to track the request status:
  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.
If you’re running Meilisearch locally, you can stop the program with Ctrl + c.
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: 
mv /path/to/your/meilisearch/directory/meilisearch/data.ms /tmp/
mv /path/to/your/meilisearch/directory/meilisearch /tmp/
Install the desired version of Meilisearch
Install the latest version of Meilisearch using: 
curl -L https://install.meilisearch.com | sh
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: 
# replace {dump_uid.dump} with the name of your dump file
./meilisearch --import-dump dumps/{dump_uid.dump} --master-key="MASTER_KEY"
# Or, if you chose another location for data files and dumps before the update, also add the same parameters
./meilisearch --import-dump dumps/{dump_uid.dump} --master-key="MASTER_KEY" --db-path PATH_TO_DB_DIR/data.ms --dump-dir PATH_TO_DUMP_DIR/dumps
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. If something went wrong, you can always roll back to the previous version. Feel free to reach out for help if the problem continues. If you successfully migrated your database but are having problems with your codebase, be sure to check out our version-specific warnings.

​
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: 
mv /tmp/meilisearch /path/to/your/meilisearch/directory/meilisearch
mv /tmp/data.ms /path/to/your/meilisearch/directory/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: 
rm /path/to/your/meilisearch/directory/meilisearch/dumps/{dump_uid.dump}

​
Version-specific warnings

After migrating to the most recent version of Meilisearch, your code-base may require some changes. This section contains warnings for some of the most impactful version-specific changes. For full changelogs, see the releases tab on GitHub.
  • If you are updating from v0.25 or below, be aware that:
    • The private and public keys have been deprecated and replaced by two default API keys with similar permissions: Default Admin API Key and Default Search API Key.
    • The updates API has been replaced with the tasks API.
  • If you are updating from v0.27 or below, existing keys will have their key and uid fields regenerated.
  • If you are updating from v0.30 or below to v1.0 or above on a cloud platform, replace --dumps-dir with --dump-dir in the following files:
    • /etc/systemd/system/meilisearch.service
    • /var/opt/meilisearch/scripts/first-login/001-setup-prod.sh