Skip to main content

The documentation here is for an unreleased version of Recyclarr.

Visit the documentation site for the Current Version instead.

Migration System

Summary​

The Migration System allows Recyclarr to perform automatic upgrade steps between releases. These steps, referred to as Migration Steps, handle breaking changes so you don't have to act manually. Most migration steps correspond to major releases.

When Migrations Run​

Migrations run automatically each time the Recyclarr server starts, before it loads your configuration. When a CLI command starts a temporary server, migrations run before that command too.

When a migration step executes, the server logs a message:

Migration step completed: <step description>

If no migrations are needed, nothing is logged at the default level.

Failure & Recovery​

When a Migration Step fails, processing of further steps is halted and the server does not start. The failure results in diagnostic information in the server log:

  • Step description. What the migration was trying to do.
  • Failure reason. Why the step could not be completed.
  • Remediation steps. One or more ways to resolve the problem, typically either performing the steps by hand or taking action to allow the migration to succeed the next time Recyclarr starts.