Upgrade Your Repository¶

As FlexVault develops, the format it stores repositories in changes from time to time. When a release changes the format, a repository written by an earlier version has to be upgraded before the new version of fxv can read it. Until then, commands exit with code 96 and this error:

Error: This published repository uses format version 2, which this version of fxv reads only after the repository is upgraded to version 3. Run `fxv repo upgrade` in the workspace to upgrade it, or `fxv repo upgrade <URI>` to upgrade the repository at a URI.

The release notes state when a release changes the format, and this page has a section for each of those releases.

Before you upgrade¶

Upgrades are designed to be safe to run, and an upgrade that is interrupted, for example by a dropped connection or by pressing Ctrl-C, finishes when you run the same command again. Even so, back up the repository before you upgrade it:

For a repository in object storage, copy the bucket, or the path in it that contains the repository, with your storage provider's tools.
For a local filesystem repository, copy the repository directory.

The upgrade also converts each workspace's local data, including its unpublished draft revisions. Publish any work you want to keep beforehand, or back up the workspace's .fxv_workspace directory along with the repository.

Once a repository is upgraded, older versions of fxv can no longer use it. Agree on a time with everyone who uses the repository, and install the new version with fxv upgrade on every machine that connects to it, including build workers. If a plugin or other integration on a machine does not support the new version, fxv upgrade blocks the upgrade and tells you which one. Update that integration first.

Let other fxv commands finish, and close editors that use a FlexVault plugin, before you start. An upgrade does not start while another process is using the repository. While an upgrade runs, other commands that would change the repository fail, with advice to try again once it has finished.

Run the upgrade¶

Run fxv repo upgrade from inside a workspace:

fxv repo upgrade

This upgrades the repository the workspace publishes to, starting with the remote repository if it has one, and then the workspace's own data. Before it changes a repository that other workspaces use, fxv repo upgrade prints this and waits for confirmation:

This upgrades the repository at 's3.us-east-1.amazonaws.com/my-bucket/my-repo' for every workspace that uses it. Versions of fxv older than this one can no longer use it, and each workspace of it needs `fxv repo upgrade`.
Upgrade it now? [y/N]

When it finishes, it prints:

Upgraded the published repository from format version 2 to 3.
Upgraded the draft repository from format version 2 to 3.
Run `fxv repo upgrade` in each other workspace of this repository as well.

In a workspace connected to a remote repository, the upgrade can download parts of the repository again, so it takes longer on a large one.

Upgrade every other workspace¶

Each workspace has its own local data to convert, so run fxv repo upgrade in every other workspace of the repository too, on each machine. The repository is already upgraded by then, so the command converts only that workspace and does not ask for confirmation.

Upgrade from a script¶

With --unattended, or when standard input is not a terminal, fxv repo upgrade cannot ask for confirmation and fails instead. Pass --yes to confirm in advance:

fxv repo upgrade --yes --unattended

Upgrade a repository directly¶

fxv repo upgrade <URI> upgrades only the repository at that URI, without a workspace. Use this to upgrade a repository before anyone runs the command in their own workspace. An s3:// URI needs the same --s3-* options as fxv repo new:

Windows (PowerShell) Linux / macOS

fxv repo upgrade s3://my-bucket/my-repo `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-region REGION

fxv repo upgrade s3://my-bucket/my-repo \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-region REGION

Every workspace of the repository still needs fxv repo upgrade afterwards, to convert its own data.

If the upgrade is interrupted¶

Run the same command again. It skips the steps that already finished and completes the rest.

Upgrade from 0.11 to 0.12¶

fxv 0.12.0 changes the repository format. Repositories and workspaces created or used with any 0.11 release, from 0.11.0 to 0.11.3, need upgrading before 0.12.0 can use them.

Publish or back up any unpublished work in each workspace, using the version of fxv you have now.
Back up the repository.
Install fxv 0.12.0 on every machine that uses the repository.
In one workspace, run fxv repo upgrade and confirm. This upgrades the repository and that workspace.
Run fxv repo upgrade in every other workspace.