> ## Documentation Index
> Fetch the complete documentation index at: https://meilisearch-6b28dec2-stabilize-dumpless-upgrade.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update to the latest Meilisearch version

> Learn how to migrate to the latest Meilisearch release.

Meilisearch databases are only compatible with the version of Meilisearch used to create them. The following guide will walk you through upgrading an existing database from an older version of Meilisearch to the most recent one, either with the `--upgrade-db` flag or with a [dump](/resources/self_hosting/data_backup/dumps).

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](#version-specific-warnings).

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

<Frame>
  <img src="https://mintcdn.com/meilisearch-6b28dec2-stabilize-dumpless-upgrade/S7jcZFc02PP6fwOz/assets/images/updating/update-button.png?fit=max&auto=format&n=S7jcZFc02PP6fwOz&q=85&s=b3674f98317e6a72f4a3af286f781296" alt="Button to update Meilisearch version to 1.0.2" width="1334" height="455" data-path="assets/images/updating/update-button.png" />
</Frame>

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

<Frame>
  <img src="https://mintcdn.com/meilisearch-6b28dec2-stabilize-dumpless-upgrade/S7jcZFc02PP6fwOz/assets/images/updating/update-in-progress.png?fit=max&auto=format&n=S7jcZFc02PP6fwOz&q=85&s=ee6f6da94766407f960b8b34f04ab3a7" alt="Project update in progress" width="1369" height="539" data-path="assets/images/updating/update-in-progress.png" />
</Frame>

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

To update a self-hosted instance, create a snapshot of your data, install the new binary, and relaunch Meilisearch with the `--upgrade-db` flag. Meilisearch then upgrades your database on startup.

In some cases, Meilisearch cannot upgrade your database this way and returns an error at launch. If that happens, [update your instance using a dump](#using-a-dump) instead.

### Updating with the `--upgrade-db` flag

<Note>
  The `--upgrade-db` flag is available since Meilisearch v1.51. If you are upgrading to an older version, use `--experimental-dumpless-upgrade` instead.
</Note>

#### Step 1: Make a backup

Database upgrades are not atomic. In rare occasions, the process may partially fail and result in a corrupted database. To prevent data loss, create a snapshot of your instance:

<CodeGroup>
  ```javascript JS theme={null}
  client.createSnapshot()
  ```

  ```python Python theme={null}
  client.create_snapshot()
  ```

  ```php PHP theme={null}
  $client->createSnapshot();
  ```

  ```java Java theme={null}
  client.createSnapshot();
  ```

  ```ruby Ruby theme={null}
  client.create_snapshot
  ```

  ```go Go theme={null}
  client.CreateSnapshot()
  ```

  ```csharp C# theme={null}
  await client.CreateSnapshotAsync();
  ```

  ```rust Rust theme={null}
  client
    .create_snapshot()
    .await
    .unwrap();
  ```

  ```swift Swift theme={null}
  let task = try await self.client.createSnapshot()
  ```
</CodeGroup>

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.

<Tabs>
  <Tab title="Local installation">
    If you're running Meilisearch locally, stop the program by pressing `Ctrl + c`.
  </Tab>

  <Tab title="Cloud platforms">
    If you're running Meilisearch as a `systemctl` service, connect via SSH to your cloud instance and execute the following command to stop Meilisearch:

    ```bash theme={null}
    systemctl stop meilisearch
    ```

    You may need to prefix the above command with `sudo` if you are not connected as root.
  </Tab>
</Tabs>

#### Step 3: Install the new Meilisearch binary

Install the latest version of Meilisearch using:

<Tabs>
  <Tab title="Local installation">
    ```bash theme={null}
    curl -L https://install.meilisearch.com | sh
    ```
  </Tab>

  <Tab title="Cloud platforms">
    ```sh theme={null}
    # replace MEILISEARCH_VERSION with the version of your choice. Use the format: `vX.X.X`
    curl "https://github.com/meilisearch/meilisearch/releases/download/MEILISEARCH_VERSION/meilisearch-linux-amd64" --output meilisearch --location --show-error
    ```
  </Tab>
</Tabs>

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

Relaunch Meilisearch with the `--upgrade-db` flag:

<Tabs>
  <Tab title="Local installation">
    ```bash theme={null}
    ./meilisearch --upgrade-db
    ```
  </Tab>

  <Tab title="Cloud platforms">
    ```sh theme={null}
    meilisearch --upgrade-db
    ```
  </Tab>
</Tabs>

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.

#### If Meilisearch fails to launch with an error

Meilisearch cannot upgrade databases created with versions older than v1.12. In that case, it fails to launch and returns the following error:

```
Database version X.Y.Z is too old to be upgraded via `--upgrade-db`. Please generate a dump using the vX.Y.Z and import it in the vA.B.C
```

If you see this error, reinstall the Meilisearch version your database was created with, relaunch your instance, then [update it using a dump](#using-a-dump).

#### 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 the `--upgrade-db` flag:

1. Cancel the `upgradeDatabase` 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](/resources/self_hosting/data_backup/snapshots#starting-from-a-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](https://github.com/meilisearch/meilisearch).

### Using a dump

Use this method when Meilisearch cannot upgrade your database with the `--upgrade-db` flag.

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

<CodeSamplesUpdatingGuideCheckVersionNewAuthorizationHeader />

The response should look something like this:

```json theme={null}
{
  "commitSha": "stringOfLettersAndNumbers",
  "commitDate": "YYYY-MM-DDTimestamp",
  "pkgVersion": "x.y.z"
}
```

Proceed to [creating the dump](/reference/api/management/create-dump).

##### Create the dump

Before creating your dump, make sure that your [dump directory](/resources/self_hosting/configuration/reference#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:

<Tabs>
  <Tab title="UNIX">
    ```bash theme={null}
    which meilisearch
    ```

    It should return something like this:

    ```bash theme={null}
    /absolute/path/to/your/meilisearch/directory
    ```
  </Tab>

  <Tab title="Windows CMD">
    ```bash theme={null}
    where meilisearch
    ```

    It should return something like this:

    ```bash theme={null}
    /absolute/path/to/your/meilisearch/directory
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```bash theme={null}
    (Get-Command meilisearch).Path
    ```

    It should return something like this:

    ```bash theme={null}
    /absolute/path/to/your/meilisearch/directory
    ```
  </Tab>
</Tabs>

You can then create a dump of your database using the [create a dump endpoint](/reference/api/management/create-dump):

<CodeSamplesUpdatingGuideCreateDump />

The server should return a response that looks like this:

```json theme={null}
{
  "taskUid": 1,
  "indexUid": null,
  "status": "enqueued",
  "type": "dumpCreation",
  "enqueuedAt": "2022-06-21T16:10:29.217688Z"
}
```

Use the `taskUid` to [track the status](/reference/api/tasks/get-task) 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.

#### Step 2: Prepare for migration

##### Stop the Meilisearch instance

Stop your Meilisearch instance.

<Tabs>
  <Tab title="Local installation">
    If you're running Meilisearch locally, you can stop the program with `Ctrl + c`.
  </Tab>

  <Tab title="Cloud platforms">
    If you're running Meilisearch as a `systemctl` service, connect via SSH to your cloud instance and execute the following command to stop Meilisearch:

    ```bash theme={null}
    systemctl stop meilisearch
    ```

    You may need to prefix the above command with `sudo` if you are not connected as root.
  </Tab>
</Tabs>

##### 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](/resources/self_hosting/configuration/reference#database-path).

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:

<Tabs>
  <Tab title="Local installation">
    ```
    mv /path/to/your/meilisearch/directory/meilisearch/data.ms /tmp/
    mv /path/to/your/meilisearch/directory/meilisearch /tmp/
    ```
  </Tab>

  <Tab title="Cloud platforms">
    ```
    mv /usr/bin/meilisearch /tmp/
    mv /var/lib/meilisearch/data.ms /tmp/
    ```
  </Tab>
</Tabs>

##### Install the desired version of Meilisearch

Install the latest version of Meilisearch using:

<Tabs>
  <Tab title="Local installation">
    ```bash theme={null}
    curl -L https://install.meilisearch.com | sh
    ```
  </Tab>

  <Tab title="Cloud platforms">
    ```sh theme={null}
    # replace {meilisearch_version} with the version of your choice. Use the format: `vX.X.X`
    curl "https://github.com/meilisearch/meilisearch/releases/download/{meilisearch_version}/meilisearch-linux-amd64" --output meilisearch --location --show-error
    ```
  </Tab>
</Tabs>

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:

<Tabs>
  <Tab title="Local installation">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Cloud platforms">
    ```sh theme={null}
    # replace {dump_uid.dump} with the name of your dump file
    meilisearch --db-path /var/lib/meilisearch/data.ms --import-dump "/var/opt/meilisearch/dumps/{dump_uid.dump}"
    ```
  </Tab>
</Tabs>

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](/reference/api/settings/update-displayedattributes).

### 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](https://github.com/meilisearch/MeiliSearch/releases).

If something went wrong, you can always roll back to the previous version. Feel free to [reach out for help](https://discord.meilisearch.com) 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](#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:

<Tabs>
  <Tab title="Local installation">
    ```
    mv /tmp/meilisearch /path/to/your/meilisearch/directory/meilisearch
    mv /tmp/data.ms /path/to/your/meilisearch/directory/meilisearch/data.ms
    ```
  </Tab>

  <Tab title="Cloud platforms">
    ```
    mv /tmp/meilisearch /usr/bin/meilisearch
    mv /tmp/data.ms /var/lib/meilisearch/data.ms
    ```
  </Tab>
</Tabs>

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:

<Tabs>
  <Tab title="Local installation">
    ```
    rm /path/to/your/meilisearch/directory/meilisearch/dumps/{dump_uid.dump}
    ```
  </Tab>

  <Tab title="Cloud platforms">
    ```
    rm /var/opt/meilisearch/dumps/{dump_uid.dump}
    ```
  </Tab>
</Tabs>

## Version-specific warnings

After migrating to the most recent version of Meilisearch, your codebase may require some changes. For version-specific changes and full changelogs, see the [releases tab on GitHub](https://github.com/meilisearch/meilisearch/releases).