Purpose of migrate command?

Getting Help
1

Hi All,

What is the purpose of the restic migrate command?

Of all the restic commands, this one makes the least sense to me, and could mean a few things. The inbuilt tool help is a little sparse:

Basic help

./restic
  migrate       Apply migrations

Detailed help

./restic help migrate

The "migrate" command applies migrations to a repository. When no migration
name is explicitly given, a list of migrations that can be applied is printed.

Usage:
  restic migrate [name] [flags]

Flags:
  -f, --force   apply a migration a second time
  -h, --help    help for migrate

What does applying a migration to a repository mean?

Does it mean migrating repositories from a target location to another? E.g. S3 to B2?

When I ran the command, I didn’t see a list of migrations I could perform.

I think the help command and/or the docs could be improved a little to describe what the intended purpose of this command is. I also searched the restic forum, GitHub issue register and Docs page and couldn’t find anything on it.

Any ideas? Can we improve the help around it?

Thanks!

2

You are right, the help text here is a bit scant. :slight_smile:

I believe this migrates from an old version of a repository to a new version. But I might be wrong, because I’ve never used it…

If I’m right, perhaps this command should be renamed to upgrade-repository or something…

3

Yes. So I found the PR and its at Add 'migrate' command, change s3 layout by fd0 · Pull Request #1004 · restic/restic · GitHub

This PR adds a migrate command and a migration to move s3 repositories from the s3legacy to the default layout. The default layout for s3 is now default.

That command was introduced with restic version 0.7.0.
So if you have an old old repository on an s3 repo that is not already in the new layout, you can migrate it to it with this command. But if you have just recently started using restic with a version that is 0.7.0 or later than you don’t have to use that command.

1 Like
4

Thanks guys. If the help description could be updated a bit, this would make it much clearer. I think the name ‘migrate’ is reasonably OK once you understand what it does. Changing the name could impact any parameter switches people have used in scripts, so probably best to leave as is.

Updating the help description seems the easiest and most useful way to help in future! :slight_smile:

Something like:

Before

./restic
  migrate       Apply migrations

After

./restic
  migrate       Migrate a legacy repository to the current format

Before

./restic help migrate

The "migrate" command applies migrations to a repository. When no migration
name is explicitly given, a list of migrations that can be applied is printed.

After

./restic help migrate

The "migrate" command migrates a repository from a legacy format to the current format. When no migration
name is explicitly given, a list of migrations that can be applied is printed.
1 Like
5

Oh, indeed! Thanks a lot for proposing new help texts! Would you mind submitting them as a PR?

I have plans to also use the migrate command for repository data structure migrations, like if when we change the repository format (e.g. to add compression). Until now we have used it only to migrate the file structure within the s3 backend.

6

I have no idea how to do that, but will give it a try to learn!