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

WARNING

This guide does not work for versions below v0.15. For more information, contact support (opens new window).

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

./meilisearch --master-key="MASTER_KEY"

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

curl \
  -X GET 'http://localhost:7700/version' \
  -H 'Authorization: Bearer API_KEY'

NOTE

If you're using v0.24 or below, use the X-MEILI-API-KEY: apiKey authorization header:

curl \
  -X GET 'http://localhost:7700/version' \
  -H 'X-Meili-API-Key: API_KEY'  

The response should look something like this:

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

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) to access and export your database.

NOTE

If you are updating to v0.28, keys imported from the old version will have their key and uid fields regenerated.

# Step 2: Set all fields as displayed attributes

NOTE

If your dump was created in Meilisearch v0.21 or above, continue to step 3.

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://localhost:7700/indexes/{index_uid}/settings/displayed-attributes' \
  -H 'Authorization: Bearer API_KEY'

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

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

curl \
  -X DELETE 'http://localhost:7700/indexes/{index_uid}/settings/displayed-attributes' \
  -H 'Authorization: Bearer API_KEY'

This command returns a taskUid. You can use this to track the status of the operation. Once the status is succeeded, you're good to go.

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

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

You can then create a dump of your database:

curl \
  -X POST 'http://localhost:7700/dumps' \
  -H 'Authorization: Bearer API_KEY'

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"
}

This command returns a taskUid. You can use this to track the status of your dump. Keep in mind that the process can take some time to complete.

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

{
  "uid": 1,
  "indexUid": null,
  "status": "succeeded",
  "type": "dumpCreation",
  "details": {
    "dumpUid": "20220621-161029217"
  },
  "duration": "PT0.025872S",
  "enqueuedAt": "2022-06-21T16:10:29.217688Z",
  "startedAt": "2022-06-21T16:10:29.218297Z",
  "finishedAt": "2022-06-21T16:10:29.244169Z"
}

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

NOTE

If you are using the Meilisearch official images on DigitalOcean, AWS, or GCP, you will find the data.ms folder at /var/lib/meilisearch/data.ms.

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

# launch the latest version of Meilisearch with the master key and import the specified dump file
./meilisearch --import-dump /dumps/your_dump_file.dump --master-key="MASTER_KEY"

WARNING

If you are using Meilisearch v0.20 or below, migration should be done in two steps. First, import your dump into an instance running any version of Meilisearch from v0.21 to v0.24, inclusive. Second, export another dump from this instance and import it to a final instance running your targeted version.

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! πŸŽ‰