v1.13: Dumpless upgrades (#3138)

guimachiavelli · irevoire · web-flow · commit 89f1502db3f8 · 2025-02-13T15:41:09.000+01:00
---------

Co-authored-by: Tamo &lt;tamo@meilisearch.com&gt;
diff --git a/learn/self_hosted/configure_meilisearch_at_launch.mdx b/learn/self_hosted/configure_meilisearch_at_launch.mdx
@@ -237,6 +237,23 @@ Meilisearch automatically collects data from all instances that do not opt out u
 
 [Read more about our policy on data collection](/learn/resources/telemetry), or take a look at [the comprehensive list of all data points we collect](/learn/resources/telemetry#exhaustive-list-of-all-collected-data).
 
+### Dumpless upgrade <NoticeTag type="experimental" label="experimental" />
+
+**Environment variable**: `MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE`<br />
+**CLI option**: `--experimental-dumpless-upgrade`<br />
+**Default value**: None<br />
+**Expected value**: None
+
+Migrates the database to a new Meilisearch version after you have manually updated the binary.
+
+[Learn more about updating Meilisearch to a new release](/learn/update_and_migration/updating).
+
+<Capsule intent="danger" title="Create a snapshot before a dumpless upgrade">
+Take a snapshot of your instance before performing a dumpless upgrade.
+
+Dumpless upgrade are not currently atomic. It is possible some processes fail and Meilisearch still finalizes the upgrade. This may result in a corrupted database and data loss.
+</Capsule>
+
 ### Dump directory
 
 **Environment variable**: `MEILI_DUMP_DIR`<br />
@@ -303,7 +320,7 @@ Meilisearch currently supports five log levels, listed in order of increasing ve
 - `'TRACE'`: log all events and include even more detailed information on Meilisearch's internal processes. We do not advise using this level as it is extremely verbose. Use `'DEBUG'` before considering `'TRACE'`.
 - `'OFF'`: disable logging
 
-## Customize log output <NoticeTag type="experimental" label="experimental" />
+### Customize log output <NoticeTag type="experimental" label="experimental" />
 
 **Environment variable**: `MEILI_LOGS_MODE`<br />
 **CLI option**: `--experimental-logs-mode`<br />
diff --git a/learn/update_and_migration/updating.mdx b/learn/update_and_migration/updating.mdx
@@ -36,13 +36,124 @@ Once the project has been successfully updated, you will receive an email confir
 
 ## Updating a self-hosted Meilisearch instance
 
+You may update a self-hosted instance in one of two ways: with or without a dump.
+
 <Capsule intent="warning">
 This guide only works for v0.15 and above. If you are using an older Meilisearch release, please [contact support](https://discord.meilisearch.com) for more information.
 </Capsule>
 
-### Step 1: Export data
+### Dumpless upgrade <NoticeTag type="experimental" label="experimental" />
+
+Dumpless upgrades are available when upgrading from Meilisearch >=v1.12 to Meilisearch >=v1.13
+
+#### Step 1: Make a backup
+
+Dumpless upgrades are an experimental feature. Because of that, it may in rare occasions partially fail and result in a corrupted database. To prevent data loss, create a snapshot of your instance:
+
+```sh
+curl \
+  -X POST 'MEILISEARCH_URL/snapshots'
+```
+
+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.Container labels={['Local installation', 'Cloud platforms']}>
+
+<Tabs.Content label="Local installation">
+
+If you're running Meilisearch locally, stop the program by pressing `Ctrl + c`.
+
+</Tabs.Content>
+
+<Tabs.Content label="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
+systemctl stop meilisearch
+```
+
+You may need to prefix the above command with `sudo` if you are not connected as root.
+
+</Tabs.Content>
+</Tabs.Container>
+
+#### Step 3: Install the new Meilisearch binary
+
+Install the latest version of Meilisearch using:
+
+<Tabs.Container labels={['Local installation', 'Cloud platforms']}>
+
+<Tabs.Content label="Local installation">
+
+```bash
+curl -L https://install.meilisearch.com | sh
+```
+
+</Tabs.Content>
+
+<Tabs.Content label="Cloud platforms">
+
+```sh
+# 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
+```
+
+</Tabs.Content>
+</Tabs.Container>
+
+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
+
+Execute the command below to import the dump at launch:
+
+<Tabs.Container labels={['Local installation', 'Cloud platforms']}>
+
+<Tabs.Content label="Local installation">
+
+```bash
+./meilisearch --experimental-dumpless-upgrade 
+```
+
+</Tabs.Content>
+
+<Tabs.Content label="Cloud platforms">
+
+```sh
+meilisearch --experimental-dumpless-upgrade 
+```
+
+</Tabs.Content>
+</Tabs.Container>
+
+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.
+
+<Capsule intent="warning">
+If after the upgrade is completed the task status is set to `failed` or Meilisearch returns internal error messages to your queries, [restart your instance from the snapshot](/learn/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).
+</Capsule>
+
+### Using a dump
+
+#### Step 1: Export data
 
-#### Verify your database version
+##### Verify your database version
 
 First, verify the version of Meilisearch that's compatible with your database using the get version endpoint:
 
@@ -66,7 +177,7 @@ If you get the `missing_authorization_header` error, you might be using **v0.24
 
 If your [`pkgVersion`](/reference/api/version#version-object) is 0.21 or above, you can jump to [creating the dump](#create-the-dump). If not, proceed to the next step.
 
-#### Set all fields as displayed attributes
+##### Set all fields as displayed attributes
 
 <Capsule intent="note">
 If your dump was created in Meilisearch v0.21 or above, [skip this step](#create-the-dump).
@@ -95,7 +206,7 @@ This command returns an `updateId`. Use the get update endpoint to track the sta
 
 Once the status is `processed`, you're good to go. Repeat this process for all indexes, then move on to creating your dump.
 
-#### Create the dump
+##### Create the dump
 
 Before creating your dump, make sure that your [dump directory](/learn/self_hosted/configure_meilisearch_at_launch#dump-directory) is somewhere accessible. By default, dumps are created in a folder called `dumps` at the root of your Meilisearch directory.
 
@@ -183,9 +294,9 @@ For v0.27 and below, the response to your request returns a dump `uid`. Use it
 
 Once the `dumpCreation` task shows `"status": "succeeded"`, you're ready to move on.
 
-### Step 2: Prepare for migration
+#### Step 2: Prepare for migration
 
-#### Stop the Meilisearch instance
+##### Stop the Meilisearch instance
 
 Stop your Meilisearch instance.
 
@@ -210,7 +321,7 @@ You may need to prefix the above command with `sudo` if you are not connected as
 </Tabs.Content>
 </Tabs.Container>
 
-#### Create a backup
+##### 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](/learn/self_hosted/configure_meilisearch_at_launch#database-path).
 
@@ -239,7 +350,7 @@ mv /var/lib/meilisearch/data.ms /tmp/
 </Tabs.Content>
 </Tabs.Container>
 
-#### Install the desired version of Meilisearch
+##### Install the desired version of Meilisearch
 
 Install the latest version of Meilisearch using:
 
@@ -275,9 +386,9 @@ For **cloud platforms**, move the new Meilisearch binary to the `/usr/bin` direc
 mv meilisearch /usr/bin/meilisearch
 ```
 
-### Step 3: Import data
+#### Step 3: Import data
 
-#### Launch Meilisearch and import the dump
+##### Launch Meilisearch and import the dump
 
 Execute the command below to import the dump at launch:
 
@@ -306,7 +417,7 @@ meilisearch --db-path /var/lib/meilisearch/data.ms --import-dump "/var/opt/meili
 
 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
+##### 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:
 
