Update to the latest MeiliSearch version

Currently, MeiliSearch databases can only be opened by the MeiliSearch version you used to create them. The following guide will walk you through all the steps to migrate an existing database from an older version of MeiliSearch to the most recent one.

If you already have a MeiliSearch database with some data you don’t want to lose, you are in the right place!

NOTE

If you have already installed the latest version and manually indexed your data and settings, you can ignore this guide.

Verify your database version

Before we begin, you need to verify the version of MeiliSearch that’s compatible with your database, i.e. the version that indexed the data. You can do so by launching a MeiliSearch instance:

  1. ./meilisearch

If MeiliSearch launches successfully, use the get version endpoint, note your pkgVersion, and proceed to the next step.

  1. curl -X GET 'http://127.0.0.1:7700/version'

The response should look something like this:

  1. {
  2.   "commitSha": "stringOfLettersAndNumbers",
  3.   "commitDate": "YYYY-MM-DDTimestamp",
  4.   "pkgVersion": "x.y.z"
  5. }

If you get the error Cannot open database, expected MeiliSearch engine version: 0.X.X, current engine version 0.Y.Y, your database is not compatible with the currently installed MeiliSearch version.

In this case, you need to download the compatible version now (i.e. 0.X.X in the above error message) so that you can access and export your database.

cURL

Homebrew

Source

APT

Docker

If you downloaded MeiliSearch using curl, find and download the compatible version hereUpdate MeiliSearch - 图1 (opens new window) before continuing.

Replace 0.X.X with the version you would like to install.

  1. brew install meilisearch@0.X.X

Replace 0.X.X with the version you would like to install.

  1. # clone MeiliSearch and checkout the branch of the expected version
  2. git clone https://github.com/meilisearch/MeiliSearch
  3. cd MeiliSearch
  4. git checkout v0.X.X
  6. # update the rust toolchain to the latest version
  7. rustup update
  9. # compile the project
  10. cargo build --release
  12. # execute the server binary
  13. ./target/release/meilisearch

Replace 0.X.X with the version you would like to install.

  1. apt-get install meilisearch=0.X.X

Replace 0.X.X with the version you would like to install.

  1. docker run -it --rm \
  2.     -p 7700:7700 \
  3.     -v "$(pwd)/data.ms:/data.ms" \
  4.     getmeili/meilisearch:v0.X.X

Proceed according to your database version

Now that you know which MeiliSearch version your database is compatible with, proceed accordingly:

  • If your database version is v0.15.0 or above, continue to the next section.
  • If your version is v0.14.0 or below, go here.

Updating from v0.15.0 or above

Because MeiliSearch v0.15.0 and above include the dumps feature, updating is relatively simple.

In this guide, we will:

  1. Set all fields as displayed attributes
  2. Create a dump using the MeiliSearch version that’s compatible with your database
  3. Delete the database folder
  4. Import the dump using the most recent MeiliSearch version

Step 1: Set all fields as displayed attributes

NOTE

If your dump was created in MeiliSearch v0.21 or above, continue to step 2.

When creating dumps, MeiliSearch calls the same method as the get documents endpoint. This means that all fields must be displayed in order to be saved in the dump.

Start by using the get displayed attributes endpoint to verify that all attributes are displayed.

  1. # whenever you see :index_uid, replace it with your index's unique id
  2. curl -X GET \
  3.   'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes'

If the response is {'displayedAttributes': '["*"]'}, you can move on to the next step.

If it’s something else, then you need to use the reset displayed attributes endpoint. Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards.

  1. curl -X DELETE \
  2.   'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes'

This command should return an updateId:

  1. { "updateId": 1 }

Now that all fields are displayed, proceed to the next step.

Step 2: 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.

NOTE

If you are running MeiliSearch in a service using systemd, like AWS or a DO droplet, the dumps folder can be found in the configuration file directory, cd /var/opt/meilisearch/dumps.

If you’re unsure where your MeiliSearch directory is located, try this:

macOS / Linux

Windows CMD

Windows PowerShell

  1. which meilisearch

It should return something like this:

  1. /absolute/path/to/your/meilisearch/directory
  1. where meilisearch

It should return something like this:

  1. /absolute/path/to/your/meilisearch/directory
  1. (Get-Command meilisearch).Path

It should return something like this:

  1. /absolute/path/to/your/meilisearch/directory

To create a dump, use the create dump endpoint.

  1. curl -X POST 'http://127.0.0.1:7700/dumps'

The server should return a response that looks like this:

  1. {
  2.   "uid": "20210212-151153878",
  3.   "status": "in_progress",
  4.   "startedAt": "2021-02-12T15:11:53.402327Z"
  5. }

This process can take some time. Since dump creation is an asynchronous process, you can use the returned uid to track its status.

  1. # replace :dump_uid with the uid returned by the previous command
  2. curl -X GET 'http://127.0.0.1:7700/dumps/:dump_uid/status'

Once the response to the previous command looks like this ("status": "done"), move on.

  1. {
  2.   "uid": "20200929-114144097",
  3.   "status": "done",
  4.   "startedAt": "2020-09-29T11:41:44.392327Z",
  5.   "finishedAt": "2020-09-29T11:41:50.792147Z"
  6. }

Step 3: Delete the database folder

To delete the old MeiliSearch version, you need to delete the data.ms folder. data.ms should be at the root of the MeiliSearch binary, unless you chose another locationUpdate MeiliSearch - 图2 (opens new window).

Step 4: Import the dump

Now that you’ve got your dump, install the latest version of MeiliSearch and import the dump at launch using the CLI option.

  1. # launch the latest version of MeiliSearch and import the specified dump file
  2. ./meilisearch --import-dump /dumps/your_dump_file.dump

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.

Finally, 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! 🎉

Updating from v0.14.0 or below

Since these versions predate the dumps feature, the best solution is to export your documents and your index settings as .JSON files.

In this guide, we will:

  1. Save your settings
  2. Set all fields as displayed attributes
  3. Save your documents
  4. Delete the database folder
  5. Upload your data to the latest version of MeiliSearch

If you don’t need to preserve index settings, skip directly to step two.

Step 1: Save your settings

First, use the get settings endpoint to retrieve the settings of any indexes you want to preserve, and save them to a file using the method you prefer.

  1. # the -o option saves the output as a local file
  2. curl -X GET \
  3.   'http://127.0.0.1:7700/indexes/:index_uid/settings' -o mysettings.json

Repeat this process for all indexes you wish to migrate.

It is important to save your settings before exporting documents, since the next step may require you to modify the settings.

Step 2: Set all fields as displayed attributes

To prevent data loss, all fields must be set as displayed.

By default, all fields are added to the displayed attributes list. Still, it’s a good idea to verify this before proceeding to the next step. You can do so by using the get displayed attributes endpoint:

  1. curl -X GET \
  2.   'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes'

If the response is '["*"]', you can move on to the next step.

If it’s something else, then you need to use the reset displayed-attributes endpoint. Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards.

  1. curl -X DELETE \
  2.   'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes'

This command should return an updateId:

  1. { "updateId": 1 }

Now that all fields are displayed, proceed to the next step.

Step 3: Save your documents

Use the get documents endpoint to retrieve your documents and save them using the method you prefer. Make sure to set the limit on documents returned so that, if you have some number of documents n, limit ≥ n. Otherwise, you risk data loss.

  1. # the -o option saves the output as a local file
  2. # whenever you see :index_uid, replace it with your index's unique id
  3. curl -X GET \
  4.   'http://127.0.0.1:7700/indexes/:index_uid/documents?limit=n' \
  5.   -o mydocuments.json

Step 4: Delete the database folder

To delete the old MeiliSearch version, you need to delete the data.ms folder. data.ms should be at the root of the MeiliSearch binary, unless you chose another locationUpdate MeiliSearch - 图3 (opens new window).

Step 5: Upload your data to the latest version of MeiliSearch

Finally, install the latest version of MeiliSearch and upload your data as usual.

If you chose to save your settings, make sure to follow this order:

  1. # update your settings
  2. curl -X POST -H "Content-Type: application/json" -d @mysettings.json \
  3.   'http://127.0.0.1:7700/indexes/:index_uid/settings'
  5. # then, add your documents
  6. curl -X POST -H "Content-Type: application/json" -d @mydocuments.json \
  7.   'http://127.0.0.1:7700/indexes/:index_uid/documents'

Since updating the settings requires re-indexing all documents, this order saves time and memory.

Congratulations! You have successfully migrated your MeiliSearch database to the latest version! 🎉