Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modify cache versioning to support backwards compatibility #8386

Merged
merged 1 commit into from
Oct 20, 2024
Merged

Modify cache versioning to support backwards compatibility #8386

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion crates/uv-cache/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -764,7 +764,7 @@ pub enum CacheBucket {
impl CacheBucket {
fn to_str(self) -> &'static str {
match self {
Self::SourceDistributions => "sdists-v4",
Self::SourceDistributions => "sdists-v5",
Self::FlatIndex => "flat-index-v1",
Self::Git => "git-v0",
Self::Interpreter => "interpreter-v2",
Expand Down
2 changes: 1 addition & 1 deletion crates/uv/tests/it/cache_prune.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -328,7 +328,7 @@ fn prune_stale_revision() -> Result<()> {
----- stderr -----
DEBUG uv [VERSION] ([COMMIT] DATE)
Pruning cache at: [CACHE_DIR]/
DEBUG Removing dangling source revision: [CACHE_DIR]/sdists-v4/[ENTRY]
DEBUG Removing dangling source revision: [CACHE_DIR]/sdists-v5/[ENTRY]
DEBUG Removing dangling cache archive: [CACHE_DIR]/archive-v0/[ENTRY]
Removed 8 files ([SIZE])
"###);
Expand Down
19 changes: 8 additions & 11 deletions docs/concepts/cache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,16 +158,13 @@ release contains a breaking change to the cache format, uv will not attempt to r
an incompatible cache bucket.

For example, uv 0.4.13 included a breaking change to the core metadata bucket. As such, the bucket
version was increased from v12 to v13.
version was increased from v12 to v13. Within a cache version, changes are guaranteed to be both
forwards- and backwards-compatible.

Within a cache version, changes are guaranteed to be forwards-compatible, but _not_
backwards-compatible.
Since changes in the cache format are accompanied by changes in the cache version, multiple versions
of uv can safely read and write to the same cache directory. However, if the cache version changed
between a given pair of uv releases, then those releases may not be able to share the same
underlying cache entries.

For example, uv 0.4.8 can read cache entries written by uv 0.4.7, but uv 0.4.7 cannot read cache
entries written by uv 0.4.8. As a result, it's safe to share a cache directory across multiple uv
versions, as long as those versions are strictly increasing over time, as is common in production
and development environments.

If you intend to use multiple uv versions on an ongoing basis, we recommend using separate caches
for each version, as (e.g.) a cache populated by uv 0.4.8 may not be usable by uv 0.4.7, despite the
cache _versions_ remaining unchanged between the releases.
For example, it's safe to use a single shared cache for uv 0.4.12 and uv 0.4.13, though the cache
itself may contain duplicate entries in the core metadata bucket due to the change in cache version.
Loading