Merge pull request #6486 from meilisearch/stabilize-dumpless-upgrade

curquiza · web-flow · commit f7871bd28b27 · 2026-07-21T13:46:45.000Z
Stabilize dumpless upgrade
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -14,7 +14,7 @@ Fixes #...
 - [ ] Automated tests have been added.
 - [ ] If some tests cannot be automated, manual rigorous tests should be applied.
 - [ ] ⚠️ If there is any change in the DB:
-    - [ ] Test that any impacted DB still works as expected after using `--experimental-dumpless-upgrade` on a DB created with the last released Meilisearch
+    - [ ] Test that any impacted DB still works as expected after using `--upgrade-db` on a DB created with the last released Meilisearch
     - [ ] Test that during the upgrade, **search is still available** (artificially make the upgrade longer if needed)
     - [ ] Set the `db change` label.
 - [ ] If necessary, the feature have been tested in the Cloud production environment (with [prototypes](./documentation/prototypes.md)) and the Cloud UI is ready.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -238,7 +238,7 @@ This project uses GitHub Merge Queues that helps us manage pull requests merging
 Before merging a PR, the maintainer should ensure the following requirements are met
 - Automated tests have been added.
 - If some tests cannot be automated, manual rigorous tests should be applied.
-- ⚠️ If there is an change in the DB: it's mandatory to manually test the `--experimental-dumpless-upgrade` on a DB of the previous Meilisearch minor version (e.g. v1.13 for the v1.14 release).
+- ⚠️ If there is an change in the DB: it's mandatory to manually test the `--upgrade-db` on a DB of the previous Meilisearch minor version (e.g. v1.13 for the v1.14 release).
 - If necessary, the feature have been tested in the Cloud production environment (with [prototypes](./documentation/prototypes.md)) and the Cloud UI is ready.
 - If necessary, the [documentation](https://github.com/meilisearch/documentation) related to the implemented feature in the PR is ready.
 - If necessary, the [integrations](https://github.com/meilisearch/integration-guides) related to the implemented feature in the PR are ready.
diff --git a/TESTING.md b/TESTING.md
@@ -198,9 +198,9 @@ In most cases, the change binary instruction will be used to update a database.
 
 To properly test the dumpless upgrade, one should typically:
 
-1. Open the database without processing the update task: Use a `binary` instruction to switch to the desired version, passing `--experimental-dumpless-upgrade` and `--experimental-max-number-of-batched-tasks=0` as extra CLI arguments
+1. Open the database without processing the update task: Use a `binary` instruction to switch to the desired version, passing `--upgrade-db` and `--experimental-max-number-of-batched-tasks=0` as extra CLI arguments
 2. Check that the search, stats and task queue still work.
-3. Open the database and process the update task: Use a `binary` instruction to switch to the desired version, passing `--experimental-dumpless-upgrade` as the extra CLI argument. Use a `health` command to wait for the upgrade task to finish.
+3. Open the database and process the update task: Use a `binary` instruction to switch to the desired version, passing `--upgrade-db` as the extra CLI argument. Use a `health` command to wait for the upgrade task to finish.
 4. Check that the indexing, search, stats, and task queue still work.
 
 ```jsonc
@@ -223,7 +223,7 @@ To properly test the dumpless upgrade, one should typically:
         "source": "build", // build the binary from the sources in the current git repository
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade", // allows to open with a newer MS
+          "--upgrade-db", // allows to open with a newer MS
           "--experimental-max-number-of-batched-tasks=0" // prevent processing of the update task
         ]
       }
@@ -238,7 +238,7 @@ To properly test the dumpless upgrade, one should typically:
         "source": "build", // build the binary from the sources in the current git repository
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade" // allows to open with a newer MS
+          "--upgrade-db" // allows to open with a newer MS
           // no `--experimental-max-number-of-batched-tasks=0`
         ]
       }
diff --git a/crates/index-scheduler/src/lib.rs b/crates/index-scheduler/src/lib.rs
@@ -160,8 +160,6 @@ pub struct IndexSchedulerOptions {
     pub export_default_payload_size_bytes: Byte,
     /// The experimental features enabled for this instance.
     pub instance_features: InstanceTogglableFeatures,
-    /// Whether the index scheduler is able to auto upgrade or not.
-    pub auto_upgrade: bool,
     /// The maximal number of entries in the search query cache of an embedder.
     ///
     /// 0 disables the cache.
diff --git a/crates/index-scheduler/src/scheduler/mod.rs b/crates/index-scheduler/src/scheduler/mod.rs
@@ -127,7 +127,6 @@ impl Scheduler {
             batched_tasks_size_limit,
             export_default_payload_size_bytes: _,
             instance_features: _,
-            auto_upgrade: _,
             embedding_cache_cap,
             ip_policy,
             experimental_no_snapshot_compaction,
diff --git a/crates/index-scheduler/src/test_utils.rs b/crates/index-scheduler/src/test_utils.rs
@@ -115,7 +115,6 @@ impl IndexScheduler {
             batched_tasks_size_limit: u64::MAX,
             instance_features: Default::default(),
             export_default_payload_size_bytes: byte_unit::Byte::parse_str("20MiB", false).unwrap(),
-            auto_upgrade: true, // Don't cost much and will ensure the happy path works
             embedding_cache_cap: 10,
             // NO DANGER: test code
             ip_policy: IpPolicy::danger_always_allow(),
diff --git a/crates/index-scheduler/src/upgrade/mod.rs b/crates/index-scheduler/src/upgrade/mod.rs
@@ -65,7 +65,7 @@ pub fn upgrade_index_scheduler(
 
     if initial_version < (1, 12, 0) {
         bail!(
-                "Database version {initial_major}.{initial_minor}.{initial_patch} is too old for the experimental dumpless upgrade feature. Please generate a dump using the v{initial_major}.{initial_minor}.{initial_patch} and import it in the v{target_major}.{target_minor}.{target_patch}",
+                "Database version {initial_major}.{initial_minor}.{initial_patch} is too old to be upgraded via `--upgrade-db`. Please generate a dump using the v{initial_major}.{initial_minor}.{initial_patch} and import it in the v{target_major}.{target_minor}.{target_patch}",
             );
     }
 
diff --git a/crates/meilisearch-types/src/versioning.rs b/crates/meilisearch-types/src/versioning.rs
@@ -81,13 +81,14 @@ pub enum VersionFileError {
     MalformedVersionFile { context: String },
     #[error(
         "Your database version ({major}.{minor}.{patch}) is incompatible with your current engine version ({}).\n\
-        To migrate data between Meilisearch versions, please follow our guide on https://www.meilisearch.com/docs/learn/update_and_migration/updating.",
+        To migrate data between Meilisearch versions, please follow our guide on https://www.meilisearch.com/docs/learn/update_and_migration/updating.\n\
+        Alternatively, you can set the `--upgrade-db` flag (or the `MEILI_UPGRADE_DB` environment variable) to upgrade the database on startup.",
         env!("CARGO_PKG_VERSION").to_string()
     )]
     VersionMismatch { major: u32, minor: u32, patch: u32 },
     #[error("Database version {major}.{minor}.{patch} is higher than the Meilisearch version {VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_PATCH}. Downgrade is not supported")]
     DowngradeNotSupported { major: u32, minor: u32, patch: u32 },
-    #[error("Database version {major}.{minor}.{patch} is too old for the experimental dumpless upgrade feature. Please generate a dump using the v{major}.{minor}.{patch} and import it in the v{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_PATCH}")]
+    #[error("Database version {major}.{minor}.{patch} is too old to be upgraded via `--upgrade-db`. Please generate a dump using the v{major}.{minor}.{patch} and import it in the v{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_PATCH}")]
     TooOldForAutomaticUpgrade { major: u32, minor: u32, patch: u32 },
     #[error("Error while modifying the database: {0}")]
     ErrorWhileModifyingTheDatabase(#[from] heed::Error),
diff --git a/crates/meilisearch/src/analytics/segment_analytics.rs b/crates/meilisearch/src/analytics/segment_analytics.rs
@@ -195,7 +195,7 @@ struct Infos {
     experimental_drop_search_after: usize,
     experimental_nb_searches_per_core: usize,
     experimental_logs_mode: LogMode,
-    experimental_dumpless_upgrade: bool,
+    upgrade_db: bool,
     experimental_replication_parameters: bool,
     experimental_enable_logs_route: bool,
     experimental_dynamic_search_rules: bool,
@@ -261,7 +261,7 @@ impl Infos {
             experimental_drop_search_after,
             experimental_nb_searches_per_core,
             experimental_logs_mode,
-            experimental_dumpless_upgrade,
+            upgrade_db,
             experimental_replication_parameters,
             experimental_enable_logs_route,
             experimental_reduce_indexing_memory_usage,
@@ -344,7 +344,7 @@ impl Infos {
             experimental_drop_search_after: experimental_drop_search_after.into(),
             experimental_nb_searches_per_core: experimental_nb_searches_per_core.into(),
             experimental_logs_mode,
-            experimental_dumpless_upgrade,
+            upgrade_db,
             experimental_replication_parameters,
             experimental_enable_logs_route: experimental_enable_logs_route | logs_route,
             experimental_dynamic_search_rules: dynamic_search_rules,
diff --git a/crates/meilisearch/src/lib.rs b/crates/meilisearch/src/lib.rs
@@ -307,7 +307,6 @@ pub fn setup_meilisearch(
         index_growth_amount: byte_unit::Byte::from_str("10GiB").unwrap().as_u64() as usize,
         index_count: DEFAULT_INDEX_COUNT,
         instance_features: opt.to_instance_features(),
-        auto_upgrade: opt.experimental_dumpless_upgrade,
         embedding_cache_cap: opt.experimental_embedding_cache_entries,
         experimental_no_snapshot_compaction: opt.experimental_no_snapshot_compaction,
         ip_policy,
@@ -454,7 +453,7 @@ fn check_version(
     let (db_major, db_minor, db_patch) = get_version(&opt.db_path)?;
 
     if db_major != bin_major || db_minor != bin_minor || db_patch != bin_patch {
-        if opt.experimental_dumpless_upgrade {
+        if opt.upgrade_db {
             update_version_file_for_dumpless_upgrade(
                 opt,
                 index_scheduler_opt,
diff --git a/crates/meilisearch/src/option.rs b/crates/meilisearch/src/option.rs
@@ -51,7 +51,7 @@ const MEILI_IGNORE_DUMP_IF_DB_EXISTS: &str = "MEILI_IGNORE_DUMP_IF_DB_EXISTS";
 const MEILI_DUMP_DIR: &str = "MEILI_DUMP_DIR";
 const MEILI_LOG_LEVEL: &str = "MEILI_LOG_LEVEL";
 const MEILI_EXPERIMENTAL_LOGS_MODE: &str = "MEILI_EXPERIMENTAL_LOGS_MODE";
-const MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE: &str = "MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE";
+const MEILI_UPGRADE_DB: &str = "MEILI_UPGRADE_DB";
 const MEILI_EXPERIMENTAL_REPLICATION_PARAMETERS: &str = "MEILI_EXPERIMENTAL_REPLICATION_PARAMETERS";
 const MEILI_EXPERIMENTAL_ENABLE_LOGS_ROUTE: &str = "MEILI_EXPERIMENTAL_ENABLE_LOGS_ROUTE";
 const MEILI_EXPERIMENTAL_CONTAINS_FILTER: &str = "MEILI_EXPERIMENTAL_CONTAINS_FILTER";
@@ -444,12 +444,14 @@ pub struct Opt {
     #[serde(default)]
     pub experimental_logs_mode: LogMode,
 
-    /// Experimental dumpless upgrade. For more information, see: <https://github.com/orgs/meilisearch/discussions/804>
+    /// Upgrade the database from a previous Meilisearch version without a dump. For more
+    /// information, see: <https://github.com/orgs/meilisearch/discussions/804>
     ///
-    /// When set, Meilisearch will auto-update its database without using a dump.
-    #[clap(long, env = MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE, default_value_t)]
+    /// When set, Meilisearch will upgrade its database on startup if it was created by a
+    /// previous version.
+    #[clap(long, env = MEILI_UPGRADE_DB, default_value_t)]
     #[serde(default)]
-    pub experimental_dumpless_upgrade: bool,
+    pub upgrade_db: bool,
 
     /// Experimental logs route feature. For more information,
     /// see: <https://github.com/orgs/meilisearch/discussions/721>
@@ -624,7 +626,7 @@ impl Opt {
             experimental_drop_search_after,
             experimental_nb_searches_per_core,
             experimental_logs_mode,
-            experimental_dumpless_upgrade,
+            upgrade_db,
             experimental_enable_logs_route,
             experimental_replication_parameters,
             experimental_reduce_indexing_memory_usage,
@@ -707,10 +709,7 @@ impl Opt {
             MEILI_EXPERIMENTAL_LOGS_MODE,
             experimental_logs_mode.to_string(),
         );
-        export_to_env_if_not_present(
-            MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE,
-            experimental_dumpless_upgrade.to_string(),
-        );
+        export_to_env_if_not_present(MEILI_UPGRADE_DB, upgrade_db.to_string());
         export_to_env_if_not_present(
             MEILI_EXPERIMENTAL_REPLICATION_PARAMETERS,
             experimental_replication_parameters.to_string(),
diff --git a/crates/meilisearch/tests/upgrade/mod.rs b/crates/meilisearch/tests/upgrade/mod.rs
@@ -29,7 +29,7 @@ async fn malformed_version_file() {
     let db_path = default_settings.db_path.clone();
     std::fs::create_dir_all(&db_path).unwrap();
     std::fs::write(db_path.join("VERSION"), "kefir").unwrap();
-    let options = Opt { experimental_dumpless_upgrade: true, ..default_settings };
+    let options = Opt { upgrade_db: true, ..default_settings };
     let err = Server::new_with_options(options).await.map(|_| ()).unwrap_err();
     snapshot!(err, @"Version file is corrupted and thus Meilisearch is unable to determine the version of the database. The version contains 1 parts instead of 3 (major, minor and patch)");
 }
@@ -41,7 +41,7 @@ async fn version_too_old() {
     let db_path = default_settings.db_path.clone();
     std::fs::create_dir_all(&db_path).unwrap();
     std::fs::write(db_path.join("VERSION"), "1.11.9999").unwrap();
-    let options = Opt { experimental_dumpless_upgrade: true, ..default_settings };
+    let options = Opt { upgrade_db: true, ..default_settings };
     let err = Server::new_with_options(options).await.map(|_| ()).unwrap_err().to_string();
 
     let major = meilisearch_types::versioning::VERSION_MAJOR;
@@ -51,7 +51,7 @@ async fn version_too_old() {
     let current_version = format!("{major}.{minor}.{patch}");
     let err = err.replace(&current_version, "[current version]");
 
-    snapshot!(err, @"Database version 1.11.9999 is too old for the experimental dumpless upgrade feature. Please generate a dump using the v1.11.9999 and import it in the v[current version]");
+    snapshot!(err, @"Database version 1.11.9999 is too old to be upgraded via `--upgrade-db`. Please generate a dump using the v1.11.9999 and import it in the v[current version]");
 }
 
 #[actix_rt::test]
@@ -69,7 +69,7 @@ async fn version_requires_downgrade() {
     let future_version = format!("{major}.{minor}.{patch}");
 
     std::fs::write(db_path.join("VERSION"), &future_version).unwrap();
-    let options = Opt { experimental_dumpless_upgrade: true, ..default_settings };
+    let options = Opt { upgrade_db: true, ..default_settings };
     let err = Server::new_with_options(options).await.map(|_| ()).unwrap_err();
 
     let err = err.to_string();
@@ -82,12 +82,10 @@ async fn version_requires_downgrade() {
 #[actix_rt::test]
 async fn upgrade_to_the_current_version() {
     let temp = tempfile::tempdir().unwrap();
-    let server = Server::new_with_options(Opt {
-        experimental_dumpless_upgrade: true,
-        ..default_settings(temp.path())
-    })
-    .await
-    .unwrap();
+    let server =
+        Server::new_with_options(Opt { upgrade_db: true, ..default_settings(temp.path()) })
+            .await
+            .unwrap();
     // The upgrade tasks should NOT be spawned => task queue is empty
     let (tasks, _status) = server.tasks().await;
     snapshot!(tasks, @r#"
diff --git a/crates/meilisearch/tests/upgrade/v1_12/v1_12_0.rs b/crates/meilisearch/tests/upgrade/v1_12/v1_12_0.rs
@@ -16,7 +16,7 @@ async fn import_v1_12_0() {
     let temp = tempfile::tempdir().unwrap();
     let original_db_path = exist_relative_path!("tests/upgrade/v1_12/v1_12_0.ms");
     let options = Opt {
-        experimental_dumpless_upgrade: true,
+        upgrade_db: true,
         master_key: Some("kefir".to_string()),
         ..default_settings(temp.path())
     };
diff --git a/documentation/release.md b/documentation/release.md
@@ -9,7 +9,7 @@ This guide is to describe how to make releases for the current repository.
 <summary>Check out the TODO 👇👇👇</summary>
 - [ ] Define the version of the release (`vX.Y.Z`) based on our <a href="https://github.com/meilisearch/meilisearch/blob/main/documentation/versioning-policy.md">Versioning Policy</a></br>.
 - [ ] Define the commit that will reference the tag release. Every PR merged after this commit will not be taken into account in the future release
-- [ ] Manually test `--experimental-dumpless-upgrade` on a DB of the previous Meilisearch minor version</br>
+- [ ] Manually test `--upgrade-db` on a DB of the previous Meilisearch minor version</br>
 - [ ] Check recent <a href="https://github.com/meilisearch/meilisearch/actions">automated tests</a> on `main`</br>
     - [ ] Scheduled test suite</br>
     - [ ] Scheduled SDK tests</br>
diff --git a/workloads/tests/api-keys.json b/workloads/tests/api-keys.json
@@ -140,7 +140,7 @@
         "source": "build",
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade",
+          "--upgrade-db",
           "--experimental-max-number-of-batched-tasks=0"
         ]
       }
@@ -175,7 +175,7 @@
         "source": "build",
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade"
+          "--upgrade-db"
         ]
       }
     },
diff --git a/workloads/tests/dsr.json b/workloads/tests/dsr.json
@@ -529,7 +529,7 @@
       "binary": {
         "source": "build",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade",
+          "--upgrade-db",
           "--experimental-max-number-of-batched-tasks=0"
         ]
       }
@@ -631,7 +631,7 @@
         "source": "build",
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade"
+          "--upgrade-db"
         ]
       }
     },
diff --git a/workloads/tests/hf-embed-hannoy.json b/workloads/tests/hf-embed-hannoy.json
@@ -148,7 +148,7 @@
         "source": "build",
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade",
+          "--upgrade-db",
           "--experimental-max-number-of-batched-tasks=0"
         ]
       }
@@ -223,7 +223,7 @@
       "binary": {
         "source": "build",
         "edition": "community",
-        "extraCliArgs": ["--experimental-dumpless-upgrade"]
+        "extraCliArgs": ["--upgrade-db"]
       }
     },
     {
diff --git a/workloads/tests/hf-embed.json b/workloads/tests/hf-embed.json
@@ -581,7 +581,7 @@
         "source": "build",
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade",
+          "--upgrade-db",
           "--experimental-max-number-of-batched-tasks=0"
         ]
       }
@@ -641,7 +641,7 @@
         "description": "apply upgrade task",
         "source": "build",
         "edition": "community",
-        "extraCliArgs": ["--experimental-dumpless-upgrade"]
+        "extraCliArgs": ["--upgrade-db"]
       }
     },
     {
diff --git a/workloads/tests/movies.json b/workloads/tests/movies.json
@@ -74,7 +74,7 @@
         "source": "build",
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade",
+          "--upgrade-db",
           "--experimental-max-number-of-batched-tasks=0"
         ]
       }
@@ -251,7 +251,7 @@
         "source": "build",
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade"
+          "--upgrade-db"
         ]
       }
     },
diff --git a/workloads/tests/network.json b/workloads/tests/network.json
@@ -290,7 +290,7 @@
         "source": "build",
         "edition": "community",
         "extraCliArgs": [
-          "--experimental-dumpless-upgrade",
+          "--upgrade-db",
           "--experimental-max-number-of-batched-tasks=0"
         ]
       }

Original file line number	Diff line number	Diff line change
`@@ -65,7 +65,7 @@ pub fn upgrade_index_scheduler(`
`65`	`65`
`66`	`66`	`if initial_version < (1, 12, 0) {`
`67`	`67`	`bail!(`
`68`		`- "Database version {initial_major}.{initial_minor}.{initial_patch} is too old for the experimental dumpless upgrade feature. Please generate a dump using the v{initial_major}.{initial_minor}.{initial_patch} and import it in the v{target_major}.{target_minor}.{target_patch}",`
	`68`	+ "Database version {initial_major}.{initial_minor}.{initial_patch} is too old to be upgraded via `--upgrade-db`. Please generate a dump using the v{initial_major}.{initial_minor}.{initial_patch} and import it in the v{target_major}.{target_minor}.{target_patch}",
`69`	`69`	`);`
`70`	`70`	`}`
`71`	`71`