🦜 Meilisearch script to update version and migrate data 🦜

Meilisearch Version Migration Script is a script that migrates your Meilisearch from a version, v.0.22.0 or higher, to a newer version without losing data nor settings.

Meilisearch is an open-source search engine. Discover what Meilisearch is!

• ☝️ Requirements
• 🚗 Usage
• 🎉 Features
• 💔 Incompatible Versions
• 📖 Documentation
• ⚙️ Development Workflow and Contributing

Currently the script only works in an environment in which Meilisearch is running as a systemctl service.

The Meilisearch's data.ms must be stored at the following path: /var/lib/meilisearch/data.ms.
To ensure this is the case, Meilisearch should have started with the following flags: --db-path /var/lib/meilisearch/data.ms

You can check the information by looking at the file located here cat /etc/systemd/system/meilisearch.service.
You should find a line with the specific command used.

ExecStart=/usr/bin/meilisearch --db-path /var/lib/meilisearch/data.ms --env production

By default all Meilisearch instances created using one of our cloud providers are storing data.ms in this directory.

A Meilisearch instance with a version greater than v0.21 should be running before launching the script. This can be checked using the following command:

systemctl status meilisearch

If you don't have a running Meilisearch instance, you can create one using one of our Cloud Providers:

Alternatively, by downloading and running Meilisearch on your own server and start it as a systemctl service.

⚠️ In case of failure during the execution of the script and for security purposes, we strongly recommend creating manually your own dump. After creating a dump, the file is located at /dumps at the root of the server.

Download the script on your Meilisearch server:

curl https://raw.githubusercontent.com/meilisearch/meilisearch-migration/main/scripts/update_meilisearch_version.sh --output migration.sh --location

To launch the script you should open the server using SSH and run the following command:

sh migration.sh meilisearch_version

• meilisearch_version: the Meilisearch version formatted like this: vX.X.X

An official release:

sh migration.sh v0.24.0

A release candidate:

sh migration.sh v0.24.0rc1

• Automatic Dumps export and import in case of version incompatibility.
• Rollback in case of failure.

The script is made to migrate the data properly in case the required version is not compatible with the current version.

It is done by doing the following:

• Create a dump
• Stop Meilisearch service
• Download and update Meilisearch
• Start Meilisearch
• If the start fails because versions are not compatible:
  • Delete current data.ms
  • Import the previously created dump
  • Restart Meilisearch
• Remove generated dump file.

If something goes wrong during the version update process a rollback occurs:

• The script rolls back to the previous Meilisearch version by using the previous cached Meilisearch binary.
• The previous data.ms is used and replaces the new one to ensure Meilisearch works exactly as before the script was used.
• Meilisearch is started again.

Example: Your current version is v0.23.0 you want to update Meilisearch to v0.24.0. Thus inside your server you import and launch the script

sh migration.sh v0.24.0

The migration fails for whatever reason. The script uses the cached v0.23.0 binary and the cached data.ms of the previous version to rollback to its original state.

Versions that are lower than the v0.22.0 can not be migrated.

It may also happen that versions are incompatible with each other in some specific cases. The breaking changes are described in the CHANGELOG of the release.

In this case, an error will be thrown by Meilisearch and the script will roll back to the version of Meilisearch before launching the script.

In order to do the update to the next version, you'll have to manually:

• Export your data without using the dumps, for example by browsing your documents using this route.
• Download and launch the binary corresponding to the new version of Meilisearch.
• Re-index your data and the new settings in the new Meilisearch instance.

See our Documentation or our API References.

Any new contribution is more than welcome in this project!

If you want to know more about the development workflow or want to contribute, please visit our contributing guidelines for detailed instructions!

Meilisearch provides and maintains many SDKs and Integration tools like this one. We want to provide everyone with an amazing search experience for any kind of project. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the integration-guides repository.