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 repo 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

fxv repo optimize <REPO_PATH> [LEVEL]

The path points at a repository directory, and the command works the same way whether that repository is backed by the local filesystem or by object storage. Credentials for an S3-backed repository come from the repository configuration, so no --s3-* flags are needed here.

Both the published repository and your workspace's draft repository benefit from maintenance, and the same guidance applies to each.

Run this from the root of a workspace. This is the usual target, and it optimizes the object storage repository when the workspace is connected to one.

fxv repo optimize .fxv_workspace/published_repo

Your local draft revisions live in their own store, which also accumulates files as you work.

fxv repo optimize .fxv_workspace/draft_repo

A repository created with fxv repo new file:///... can be optimized directly by path.

fxv repo optimize /path/to/my-repo

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 is safe to run concurrently with other FlexVault operations. 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.