Choose Meilisearch Snapshots for Recovery and Dumps for Migration

A Meilisearch backup is useful only when its format matches the event you need to recover from. Snapshots restore an already indexed database quickly on the same Meilisearch version. Dumps trade that speed for portability across versions because the target rebuilds the indexes. Current self-hosted releases add a third path: protect the database with a snapshot, then run the supported in-place upgrade.

That distinction matters on a VPS because a file can be present, recent, and still be the wrong recovery artifact. Scheduled snapshots overwrite their predecessor. Dump imports can consume substantial CPU, memory, temporary disk, and downtime. An index that is fully derived from PostgreSQL or another source may be safer to rebuild than to preserve as if Meilisearch were the primary database.

Operators exploring self-hosted applications for persistent server workloads should decide which of those contracts applies before the first production document is indexed.

Start with the outcome, not the file extension

Choose the artifact by asking what must remain true after recovery:

• Routine host or disk failure, same Meilisearch version: restore a snapshot.
• Move to another Meilisearch version: use the current upgrade path or import a dump.
• Recreate a derivative search index: replay the authoritative application data and settings.
• Preserve evidence before any mutation: export and copy the artifact away from the server before changing the live database.

Meilisearch’s backup overview calls a snapshot an exact copy of data.ms. That exactness explains both its fast startup and its version boundary. A dump is a portable description of indexes, documents, settings, and tasks that must be indexed again at import time.

Version awareness is now especially important. As checked on August 4, 2026, Meilisearch v1.52.0 is current, and the stable --upgrade-db flag has been available since v1.51. Do not turn that date into permission to skip release-specific warnings: the source database version and target binary still determine which path is valid.

Four recovery contracts deserve separate runbooks

Snapshot is a recovery artifact

The snapshot guide describes snapshots as same-version exact copies. Starting from one is faster than importing a dump, but the target database path must be empty. A snapshot created by one Meilisearch version is not an upgrade bridge to another version.

Dump is a migration artifact

Dump creation runs as an asynchronous task. Once that task succeeds, Meilisearch writes one complete .dump file; the official dump documentation says it does not leave a partial dump file when interrupted. Import still needs a clean target path, and the API remains unavailable until reindexing finishes.

Rebuild is sometimes the stronger contract

Search indexes often duplicate data owned by an application database. In that design, a tested export-and-replay job can recover documents while version-controlled configuration restores searchable, filterable, sortable, ranking, typo, and synonym settings. This path is weak when Meilisearch contains unique data or manual settings that the application cannot reproduce.

Build the routine backup lane before scheduling upgrades

Native scheduling is convenient, but it is not retention. When --schedule-snapshot is present without an interval, Meilisearch waits 24 hours before creating the first snapshot and then creates one every 24 hours. Each scheduled snapshot overwrites the old one in the snapshot directory. Copy completed artifacts to separate storage if the recovery point objective requires more than one generation.

Container deployments also need a stable volume and a reproducible version. Teams still deciding how to describe that workload can compare Docker and Docker Compose deployment tradeoffs before committing paths, image tags, and import flags to an operations runbook. Meilisearch explicitly advises against latest because different hosts can pull different releases at different times.

Create the artifact and inspect its task

Keep the administrative key out of shell history. The following example reads it without echo, requests one snapshot, and prints the task identifier. Replace only the URL; do not expose the management API publicly for this job.

export MEILI_URL='http://127.0.0.1:7700'
read -r -s -p 'Meilisearch admin key: ' MEILI_ADMIN_KEY
printf '\n'

curl --silent --show-error --request POST \
  --header "Authorization: Bearer ${MEILI_ADMIN_KEY}" \
  "${MEILI_URL}/snapshots" | jq '{taskUid,status,type,enqueuedAt}'

An accepted request is not a backup receipt. Query the returned task until status becomes succeeded, then verify that the expected file exists and copy it off the host.

TASK_UID='replace-with-returned-task-uid'

curl --silent --show-error \
  --header "Authorization: Bearer ${MEILI_ADMIN_KEY}" \
  "${MEILI_URL}/tasks/${TASK_UID}" | jq '{uid,status,type,error,details,finishedAt}'

Budget temporary space as well as destination space

Meilisearch first builds an uncompressed staging copy under TMPDIR when creating snapshots or dumps. The configuration reference warns that a job can fail with No space left on device even when --snapshot-dir or --dump-dir points to a spacious volume. Measure the active database and the filesystem holding TMPDIR before promising a backup window.

Off-server copies should have restricted access, a hash, and a retention policy. Readers designing stronger deletion resistance can use object-lock backup boundaries to separate immutability from mere file presence. Encryption, access control, and lifecycle rules remain storage responsibilities; Meilisearch does not add them to a local artifact automatically.

Rehearse same-version recovery away from production

A restore drill should never start by deleting the live data.ms. Create a separate empty directory or isolated instance, pin the exact source version, import the copied snapshot, and keep production traffic pointed at the original service.

Freeze the recovery inputs

Record the source pkgVersion from GET /version, snapshot filename, file hash, creation task, storage location, and target test path. Then verify that the target path truly has no database. Meilisearch refuses snapshot import when a database already exists; flags that ignore the snapshot in that condition can make a rehearsal look successful while testing nothing.

The official Docker guide places persistent data under /meili_data and requires import paths to be reachable inside the container. Pin the image tag to the recorded version rather than latest, mount the copied artifact read-only where practical, and expose the drill on a private port or network.

Test more than process health

HTTP 200 proves that the process answers, not that search behavior survived. Compare at least one known query per important index, document counts, filter and sort behavior, ranking-sensitive results, synonyms, typo tolerance, and settings. If clients depend on API keys, test their permissions with newly derived key values rather than assuming the previous secret string survived.

Restore rehearsal is a general application-backup discipline, not a Meilisearch exception. Vaultwarden restore testing shows the same separation between owning data, supporting files, and a verified recovery result, even though its artifacts differ.

Change versions without gambling the only indexed copy

Current self-hosted guidance starts with a snapshot, stops the service, installs the target binary, and relaunches with --upgrade-db. According to the official update procedure, the upgrade is not atomic. Rare partial failures can corrupt the database, which is why the snapshot must exist before the binary touches it.

Use --upgrade-db only inside its compatibility envelope

The stable flag begins with v1.51. Databases created by versions older than v1.12 cannot use this in-place path; Meilisearch directs those operators back to the original compatible binary so they can export a dump. Read every skipped release warning when a jump spans multiple versions because client behavior and settings may also change.

During a supported upgrade, Meilisearch creates an UpgradeDatabase task. Searches may continue, but newly enqueued tasks wait behind that upgrade. Track the task and define a maintenance boundary even when query traffic remains available.

Rollback belongs inside that boundary. Current Meilisearch guidance says canceling the UpgradeDatabase task automatically rolls the database back to its pre-upgrade state. If the task has already failed, relaunch the target binary, request cancellation, wait for the cancellation to finish, then restore the previous binary. Older target releases have different recovery instructions; upgrades to v1.14 or earlier depend on restarting from the pre-upgrade snapshot instead. Do not improvise across those version boundaries—follow the update guide for the exact target release.

Keep the dump fallback independent

Generate a dump while the old compatible instance is still healthy, wait for dumpCreation to succeed, copy the file off-server, and import it into an empty target database. Never test a downgrade by importing a newer dump into an older release; official guidance warns that behavior can be unexpected.

Reindexing changes the capacity question. Import time grows with dataset size, and Meilisearch can use considerable memory and CPU while rebuilding indexes. Workloads whose measured migration window exceeds current compute may justify dedicated server capacity for sustained indexing, but sizing should follow a rehearsal rather than an assumed document count.

API credentials need a deliberate cutover. Dumps contain API-key records, yet the derived key field depends on the master key and is not propagated. Preserve authorization rules, set the intended master key on the target, derive or rotate client keys, and test each client role before shifting traffic.

Accept recovery by search behavior and rollback readiness

Open a controlled acceptance window only after the target version, index list, document counts, settings, representative queries, and client authorization all match the recorded expectations. Compare latency during warm-up separately from correctness; a cold restored instance can be correct before caches settle.

Cutover remains reversible only when its path has a proven rollback. Dump imports and source rebuilds can preserve the untouched source database while routing changes. An in-place --upgrade-db run mutates its database, so its rollback relies on the supported task-cancellation procedure, the previous binary, and the exported snapshot—not on an unchanged old database. Do not delete migration artifacts merely because the new process started. Keep them until the acceptance window and rollback deadline close.

Broader database operations guides can help place this search-specific drill beside storage, replication, and transaction recovery practices. The common principle is evidence: an artifact, a compatible restore path, and a tested result must exist together.

Keep one compact recovery-contract record

For every accepted artifact, retain six facts together: source version, artifact type, successful task UID, SHA-256 hash, off-server location, and last tested restore result. Add the target version and measured import time when the record supports a migration.

That record makes the next decision mechanical. Same-version failure selects the snapshot lane. Cross-version movement selects supported --upgrade-db protection or the dump lane. A derivative index can select replay from its authoritative source. Recovery is proven only when the chosen lane reaches correct search results without destroying the rollback lane.