Skip to main content

Upgrade from v1.x to later releases

Version scope

This document applies to MySQL-based RAGFlow v1.0.0-rc1 and later Docker deployments. To upgrade from an earlier release, first follow Upgrade from v0.x to v1.x.

The commands below start one application instance. For a custom multi-replica deployment, use the orchestration platform's documentation to reduce it to one application instance before migration and restore the remaining instances only after migration succeeds.

Before upgrading

  1. Stop document imports, parsing jobs, data-source synchronization, and other processes that can write data.
  2. Back up the metadata database and all other persistent data from the same stopped deployment. Verify that the backup can be restored. See Backup and Restore (v1.x).
  3. Use the Docker Compose files, environment template, and image shipped with the target release. Copy the required settings from the existing deployment into the new template.
  4. Keep enough free time in the maintenance window for schema changes and data backfills. Large databases can take longer to migrate.

Run the migration

1. Stop the current deployment

Stop the existing deployment before installing the target release files:

docker compose -p docker -f docker/docker-compose.yml down

2. Start the target release

Install the target release files, merge the required settings into its docker/.env template, and start the deployment:

docker compose -p docker -f docker/docker-compose.yml up -d

For a MySQL metadata database, RAGFlow runs the required migration during startup.

3. Monitor the migration

Follow the RAGFlow application logs:

docker compose -p docker -f docker/docker-compose.yml logs -f ragflow-cpu

Keep the log view open until the migration finishes and the application starts. Press Ctrl+C to leave the log view; the containers continue running. Review warnings as well as errors before allowing users, ingestion workers, or synchronization jobs to write data.

If the logs report a migration failure, stop the deployment and preserve the logs. For a parser-config conversion error, follow the instructions below. For other failures, follow Roll back after a failed migration.

Parser-config conversion failures

The v1.0.0-rc2 step converts saved Python v0.27.2 ingestion settings for Parser, Chunker, Tokenizer, and Extractor together before the existing dataset raptor and graphrag cleanup records the shared version. Invalid JSON, metadata schemas that Go cannot represent, and unsupported PDF engine or OCR model-reference choices stop --migrate and block application startup. The error identifies the table, row ID, and rejected setting.

Keep all writers stopped. Back up the affected row's original parser_config, then correct the reported value in that row. For an unsupported engine or OCR model reference, explicitly choose and configure an engine that Go can run; deleting the setting would select the template's default engine instead. Start the target deployment again to rerun --migrate, and review its logs before resuming writes.

Each failed batch rolls back and its migration version does not advance. Earlier batches may already be committed; rerunning the conversion after correcting the data is safe. Do not change the migration version manually. To return to the previous release instead, restore the complete pre-upgrade recovery point as described below.

4. Check the deployment status

Display the state of the containers:

docker compose -p docker -f docker/docker-compose.yml ps

Wait until the expected services report a running or healthy state, then complete the checks below.

Verify the upgraded deployment

After migration, confirm that:

  • All expected containers are running and healthy.
  • Existing users can sign in.
  • Existing knowledge bases and files are visible.
  • Existing files can be opened and retrieved.
  • A new document can be uploaded, parsed, and retrieved.
  • Existing conversation history is available.
  • Model providers and tenant default models are configured correctly.
  • Enabled ingestion and file-synchronization services can complete new jobs.

Roll back after a failed migration

Rollback is performed by restoring the complete pre-upgrade backup together with its matching RAGFlow release and configuration.

To return to the previous release:

  1. Stop the failed deployment.
  2. Restore the metadata database, object storage, search index, cache, queue, and other persistent data from the same pre-upgrade backup point.
  3. Restore the matching Docker Compose files and configuration.
  4. Start the previous RAGFlow release and repeat the verification checks.