Milvus Backup is a command-line tool and API service for backing up and restoring Milvus data. Backup and restore operations run while the Milvus cluster remains available.
Use the latest release whenever possible. The latest version supports backups from Milvus 2.2 and later, and restores to Milvus 2.4 and later.
A backup can be restored only to the same or a newer Milvus version:
| Backup version | Restore to 2.4 | Restore to 2.5 | Restore to 2.6 |
|---|---|---|---|
| 2.2 | Supported | Supported | Supported |
| 2.3 | Supported | Supported | Supported |
| 2.4 | Supported | Supported | Supported |
| 2.5 | — | Supported | Supported |
| 2.6 | — | — | Supported |
For example, a backup created from Milvus 2.5 cannot be restored to Milvus 2.4.
Download a binary from the release page, or install it with Homebrew on macOS:
brew install zilliztech/tap/milvus-backupMilvus Backup must be able to connect to Milvus, the storage used by Milvus, and the backup destination. Copy the example configuration and update it for your deployment:
cp configs/backup.yaml backup.yamlThe main sections are:
milvus: how to reach Milvus — credentials, the gRPC endpoint and its TLS settings — and undermilvus.storage, the storage the deployment keeps its data in. Themilvus.etcdsettings are only required when using--backup_index_extra.backup: where backup data is written, underbackup.storage, and how much of the backup runs in parallel.restore: restore concurrency and temporary file handling.transfer: how objects move between the two storage backends.log: log level and output settings.
Both storage sections describe a backend the same way, and backup.storage inherits anything it does not name from milvus.storage. Backing up into the same backend takes little more than a bucket name; rootPath is the exception, and always defaults to backup.
| File | Scenario |
|---|---|
| backup.yaml | MinIO, with every setting spelled out |
| backup-s3.yaml | Milvus on MinIO, backups on AWS S3 |
| backup-gcp.yaml | Google Cloud Storage with a service account |
| backup-azure.yaml | Azure Blob Storage with an account key |
| backup-iam.yaml | AWS S3 with an instance role, no keys in the file |
| backup-local.yaml | Milvus on MinIO, backups on a local disk |
| backup-local-milvus.yaml | Milvus standalone with local storage (COMMON_STORAGETYPE=local), backups on MinIO |
Use values that match the Milvus deployment. In common installations, the storage defaults differ:
| Field | Docker Compose | Helm |
|---|---|---|
milvus.storage.bucketName |
a-bucket |
milvus-bucket |
milvus.storage.rootPath |
files |
file |
Credentials can also be supplied through environment variables, and any value can be overridden for a single run with --set:
milvus-backup --set MILVUS_USER=root --set MILVUS_PASSWORD=Milvus list
milvus-backup --set milvus.grpc.address=milvus-proxy listRun milvus-backup config show to print the resolved configuration along with where each value came from.
Configuration files carry a configVersion. A file written before it existed still loads — it is read with the older schema and translated, with a warning naming the file. Convert one with:
milvus-backup config migrate --config backup.yaml -o backup-v2.yamlThe migration report is written to stderr and lists everything that needs a decision, such as a secret that has to move to a renamed environment variable, or a v1 variable whose parameter now belongs in the file. The converted file goes to stdout, or to -o.
Run the configuration check before creating a backup:
milvus-backup check
milvus-backup create -n my_backup
milvus-backup list
milvus-backup restore -n my_backupThe main commands are:
| Command | Description |
|---|---|
check |
Validate connections and inspect the resolved configuration. |
create |
Create a backup. |
delete |
Delete a backup by name. |
get |
Show a backup by name. |
list |
List backups in object storage. |
restore |
Restore a backup. |
l0compact |
Convert L0 delete data into a restorable physical backup copy. |
migrate |
Migrate backup data to Zilliz Cloud. |
server |
Start the REST API server. |
Run milvus-backup <command> --help for command-specific flags. See the CLI end-to-end guide for a complete backup and restore example.
--filter limits a command to some of the collections instead of all of them. It takes a comma-separated list, where an entry is a collection in the default database (coll1), a collection in a named database (db1.coll1), or every collection in a database (db1.*):
# back up two collections
milvus-backup create -n my_backup --filter hello_milvus,db1.hello_milvus2
# back up every collection in db1 (quoted, so the shell does not expand the *)
milvus-backup create -n my_backup --filter 'db1.*'
# restore the whole backup
milvus-backup restore -n my_backupOn restore, --filter names collections as they will exist in the target Milvus, so it matches the name after --suffix or --rename has been applied:
# restores hello_milvus from the backup into a new hello_milvus_recover
milvus-backup restore -n my_backup -s _recover --filter hello_milvus_recover
# restores db1.coll1 into db2.coll1
milvus-backup restore -n my_backup -r db1.coll1:db2.coll1 --filter db2.coll1Filtering on the pre-rename name matches nothing and restores nothing.
Start the REST API server with:
milvus-backup serverIt listens on port 8080 by default. Use -p to select another port:
milvus-backup server -p 8443The Swagger UI is available at:
http://localhost:8080/api/v1/docs/index.html
See the API demo for example requests. The Swagger UI reflects the current API and should be treated as the authoritative reference.
- Storage transfer: copy backup data between different storage systems, such as MinIO and AWS S3.
- RBAC backup and restore: include Milvus RBAC metadata in a backup or restore operation.
- Segment merging restore: group small segments into fewer import jobs to improve restore performance.
The milvus.storage settings must match the storage used by Milvus. Describe the backup destination under backup.storage:
configVersion: v2
milvus:
storage:
provider: minio
address: localhost
port: 9000
bucketName: a-bucket
rootPath: files
auth:
type: static
accessKeyID: minioadmin
secretAccessKey: minioadmin
backup:
storage:
provider: aws
address: s3.us-east-1.amazonaws.com
port: 443
region: us-east-1
useSSL: true
bucketName: <your-bucket-name>
rootPath: backups
auth:
type: static
accessKeyID: <your-access-key-id>
secretAccessKey: <your-secret-access-key>The two ends are different backends, so the default transfer.mode of auto streams the objects through milvus-backup rather than asking either service to copy them. See configs/backup-s3.yaml for the complete file.
Do not commit storage credentials to the repository. Prefer environment variables or another secret-management mechanism in production.
See docs/FAQ.md for common issues and troubleshooting advice.
Build the binary:
make allThe resulting executable is written to ./milvus-backup.
Run the test suite:
make testSee CONTRIBUTING.md before submitting a change.
Milvus Backup is licensed under the Apache License 2.0.