Awesome

🚨 IMPORTANT NOTICE: Reduced Maintenance & Support 🚨

Dear Community,

We'd like to share some updates regarding the future maintenance of this repository:

Our team is small, and our availability will be reduced in the upcoming times. As such, response times might be slower, and we will not be accepting enhancements for this repository moving forward.

If you're looking for reliable alternatives, consider using Cloud Service. It offers a robust solution for those seeking an alternative to this repository.

Seeking immediate support? Please join us on our Discord channel.

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!

Table of Contents <!-- omit in toc -->

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

☝️ Requirements

1. Systemctl

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

2. Correct data.ms path

The Meilisearch's data.ms must be stored at the following path: /var/lib/meilisearch/data.ms.<br> 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.<br> 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.

3. A Running Meilisearch instance

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.

🚗 Usage

⚠️ 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:

bash migration.sh meilisearch_version

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

Note

If you want to run the script from an AWS instance and you are logged in as admin, you probably have to use this command instead:

sudo -E bash migration.sh meilisearch_version

If you want to run the script from a GCP VM instance and you are logged in as a user, you probably have to set the $MEILISEARCH_MASTER_KEY like:

export MEILISEARCH_MASTER_KEY=YOUR_API_KEY

Then run the command line as sudo:

sudo bash migration.sh meilisearch_version

Example:

An official release:

bash migration.sh v0.24.0

A release candidate:

bash migration.sh v0.24.0rc1

🎉 Features

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

Automatic Dumps

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.

Rollback in case of failure

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

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

💔 Version incompatibilities

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.

📖 Documentation

See our Documentation or our API References.

🤖 Compatibility with Meilisearch

This package guarantees compatibility with version v1.x of Meilisearch, but some features may not be present. Please check the issues for more info.

⚙️ Development Workflow and Contributing

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.