Skip to content

Maintain Your Repository

FlexVault stores content and metadata in log-structured stores. Every publish and snapshot adds new files rather than rewriting existing ones, so over time the metadata describing your content is spread across a growing number of files. Left alone, general operation degrades: the more files FlexVault has to consult, the slower it gets.

Optimization merges those files back together. Running it periodically keeps a repository fast.

Maintenance is not yet automated

FlexVault does not run optimization for you. Until it does, this is a manual step that someone has to schedule and run. The intended direction is to trigger optimization from object storage events and run it on a serverless platform such as Cloudflare Workers, S3 event handlers and Lambda, or Fly machines, but that design is not settled and none of it is available yet.

Optimization levels

fxv workspace optimize takes an optional level.

Level What it does Status
quick Merges the store without discarding stale data or repacking files. Faster, but some redundancy remains afterwards. Default, available now
full A deeper pass that also removes duplicate data and repacks files. Takes longer, and is the better choice when you can afford the time. Not implemented yet

Use quick today. full is accepted by the command but has no effect, so both levels currently perform a quick optimization.

Run an optimization

Run fxv workspace optimize from inside a workspace:

fxv workspace optimize [--draft | --published | --all] [LEVEL]

A workspace has two repositories that benefit from maintenance, and the same guidance applies to each.

Your local draft revisions live in the workspace's draft repository, which also accumulates files as you work. This is the default.

fxv workspace optimize
fxv workspace optimize

The published repository is the one the workspace publishes to, and the one every workspace of it reads from. Optimizing it speeds up every workspace. For a remote repository, the command downloads and uploads the files it merges, which can be many gigabytes.

fxv workspace optimize --published
fxv workspace optimize --published

Optimizes the draft repository first, then the published repository.

fxv workspace optimize --all
fxv workspace optimize --all

Optimize a repository with no workspace

A repository is optimized through a workspace of it. To optimize a local repository that you created with fxv repo new file:///... and do not otherwise use from a workspace, create a workspace of it with fxv init, then optimize its published repository from there:

fxv init file://c:/path/to/my-repo --path ./my-repo-workspace
cd my-repo-workspace
fxv workspace optimize --published
fxv init file:///path/to/my-repo --path ./my-repo-workspace
cd my-repo-workspace
fxv workspace optimize --published

Keep the workspace and run fxv workspace optimize --published in it each time.

How often to run it

As a rough guide, optimize roughly every ten commits. The right interval depends on how large those commits are: a handful of very large commits creates more work than many small ones, so busy repositories benefit from running it more often.

There is no harm in running it more frequently than needed. A quick optimization on an already-tidy store finishes quickly.

For now you need to track this yourself. A future release will report when maintenance is due as part of fxv status, so you will not have to keep count.

Running alongside normal work

Optimization can run while other FlexVault commands use the repository. The repository stays in a valid state at every stage, so you do not need to stop people publishing or syncing while it runs, and you do not need to take the repository offline.

The exception is a repository that is being repaired or upgraded. Until that has finished, fxv workspace optimize fails with advice to try again once it has.

Only one optimize of a repository can run at a time. If another optimize of the same repository is already running, fxv workspace optimize fails with advice to run it again once that one has finished. If an optimize of a remote repository stops before it finishes, for example because its process was killed, other optimizes of that repository fail for up to 3 minutes afterwards due to the temporary lock it leaves behind. The remaining lock duration is shown in the error message if fxv workspace optimize is run again before the lock expires.