# Dumps API and CLI
# 1. Summary
A dump is a compressed file containing an export of a MeiliSearch instance. It contains all indexes, documents, settings, tasks, and API keys but in a raw unprocessed form. A dump isn't an exact copy of a database—it is closer to a blueprint that allows creating of an identical dataset.
# 2. Motivation
The dumps exist to upgrade a MeiliSearch instance from a previous version to a more recent version. It can also be a helpful tool for loading a production state on a staging server to make changes and test them before propagating them to production.
# 3. Functional Specification
# 3.1. Summary Key Points
- A dump creation can be scheduled from the MeiliSearch API using the
POST - /dumpsendpoint.
- A dump creation status can be tracked using the
GET - /tasks/:task_uidendpoint.
- MeiliSearch can only create one dump at a time.
- By default, dumps are created in a folder named
dumps, and can be found in the same directory as the MeiliSearch binary.
dumpsdirectory can be customized using the
--dump-dirconfiguration option. If the dump directory does not already exist when the dump creation process is called, MeiliSearch will create it.
.dumpfile can be imported using the
- The MeiliSearch server starts when the dump is fully imported and indexed.
- By default, importing a dump when a database already exists (a non-empty data.ms folder in the same directory as the MeiliSearch binary) will stop the process and throw an error.
- When using the command-line flag
--ignore-dump-if-db-exists=true, MeiliSearch will use the existing database to start an instance instead of throwing an error. The dump will be ignored.
- By default, trying to import a dump that does not exist, will stop the process and throw an error.
- When using the command-line flag
--ignore-missing-dump, MeiliSearch will continue its process and not throw an error.
- When a dump is being imported, the http API is not available. Meilisearch can't receive read or write requests.
dumpCreationtask takes priority over enqueued
tasks. This means that if a
dumpCreationtask is created, it will be directly processed when the current processing task finishes even if other tasks have been enqueued before.
# 3.2. Dumps API Definition
# 3.2.1. POST
Create a dump
# 220.127.116.11. Body Payload
# 18.104.22.168. Response Definition
When the request is successful, Meilisearch returns the HTTP code
202 Accepted. The response's content is the summarized representation of the received asynchronous task.
The uid of the generated dump can be found in the task details.
# 22.214.171.124. Errors
- 🔴 If Meilisearch is secured, accessing this route without the
Authorizationheader returns a missing_authorization_header error.
- 🔴 If Meilisearch is secured, accessing this route with a key that does not have permissions (i.e. other than the master-key) returns an invalid_api_key error.
# 3.3. CLI Definition
By default, MeiliSearch creates dumps in a directory called
dumps at the root of your MeiliSearch.
The destination can be modified with the
--dump-dir flag. e.g.
Using the CLI flag
--import-dump, MeiliSearch will replace the data.ms with the dump data and start the server using the provided dump. e.g.
--import-dump flag is specified when a database exists, an error occurs in the CLI.
Error: database already exists at ":pathToDataMs/data.ms", try to delete it or rename it
To avoid MeiliSearch to throw an error when finding that a database already exists, the following flag:
--ignore-dump-if-db-exists can be used. When using this flag, MeiliSearch will use the existing database to start an instance instead of throwing an error. The dump will be ignored.
To avoid MeiliSearch to throw an error when there is no dump at the given path, the following flag:
--ignore-missing-dump can be used. MeiliSearch will then continue its process and not import any dump.
--ignore-missing-dump flag is not specified and the file cannot be found, an error occurs in the CLI.
Error: dump doesn't exist at ":pathToDumps/:missingFile"
# 3.3.5 Other dump related errors
When starting a new Meilisearch version, if Meilisearch tries to read an old data.ms and but cannot read it, the following message should appear:
Error: Your database version (`:old_version`) is incompatible with your current engine (`:new_version`). To migrate data between Meilisearch versions, follow our guide on https://docs.meilisearch.com/learn/advanced/updating.html
# 3.4. Dump version support
To handle dump and Meilisearch version compatibility, it is necessary to also versionize the dumps feature.
The following table describes which version of the dump correspond to which version of Meilisearch
v0.20.0 and below
v0.30.0 and later
All dumps created before and up to Meilisearch v1.0 can be imported into Meilisearch v1.X.Y.
# 4. Technical Aspects
# 4.1. Dump Creation
When a dump is being created, the task queue can receive other future operations to perform.
# 4.2. Importing a dump
When a dump is being imported, the http API is not available. Meilisearch can't receive read or write requests.
# 4.3. Dump Creation Task Priority
Dump creation tasks have priority over other task types. If a
dumpCreation task is enqueued, it will be directly processed when the current processing task finishes even if other tasks have been enqueued before.
# 5. Future Possibilities
- Give information about the import of a dump within the tasks.