columnar: gc ia meta & schema files in cloud_helper

[yongman]

What problem does this PR solve?

Issue Number: close #10995
ref https://github.com/tidbcloud/cloud-storage-engine/issues/5686
close https://github.com/tidbcloud/cloud-storage-engine/issues/5716

Problem Summary:
The disk or memory can be keep increasing in the long run with no background gc.

What is changed and how it works?

1. Add gc for ia_meta files in disk. (In TiKV there has a background gc task to scan the local meta files and do the gc)
2. Add gc for schema_files map in memory.
3. Decrease the ia mem_cap default value from 20% to 10%.
4. Update kvengine to latest cloud-storage-engine commit b49d94ae594914225390e3914f92025f1486d95b to fix the columnar file decryption with re-mapped file id during packed restoration.

Check List

Tests

• Unit test
• Integration test
• Manual test (add detailed scripts or steps below)
• No code

Side effects

• Performance regression: Consumes more CPU
• Performance regression: Consumes more Memory
• Breaking backward compatibility

Documentation

• Affects user behaviors
• Contains syntax changes
• Contains variable changes
• Contains experimental features
• Changes MySQL compatibility

Release note

None

Summary by CodeRabbit

• New Features
  • Added a configuration option to cap cached schema keyspaces.
  • Added an optional background cleanup loop to evict stale schema files and perform IA metadata GC.
• Bug Fixes
  • Improved schema cache eviction by updating keyspace recency on snapshot access.
  • Refined shutdown coordination so the heartbeat and background cleanup stop reliably.
• Tests
  • Extended coverage for stale-version pruning, recency updates, and GC eviction (with and without keyspace limits), plus adjusted default assertions.
• Chores
  • Updated the cloud storage engine submodule and refreshed dependency pinning/config defaults.

[ti-chi-bot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Schema-file cache recency tracking and global eviction are added to CloudHelper. Runtime configuration now controls IA metadata and schema cache GC, with a background thread, coordinated shutdown, updated defaults, and pinned dependency wiring.

Changes

Runtime garbage collection

Layer / File(s)	Summary
Schema cache tracking and eviction contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs	Adds shared per-keyspace cache state, recency updates, stale-version pruning, configurable keyspace eviction, and unit tests.
Snapshot access recency integration contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs	Propagates shared cache state through snapshot loading and touches the active keyspace after snapshot creation or reuse.
Configurable background GC lifecycle contrib/tiflash-columnar-hub/hub-runtime/src/run.rs	Adds GC configuration, starts periodic IA metadata and schema cache cleanup, coordinates shutdown, and joins the background thread.
Dependency and engine wiring contrib/tiflash-columnar-hub/Cargo.toml, contrib/tiflash-columnar-hub/hub-runtime/Cargo.toml, contrib/cloud-storage-engine	Pins workspace kvproto resolution and updates the cloud-storage-engine submodule reference.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant EngineStoreLifecycle
  participant BackgroundGCLoop
  participant IAMetaFiles
  participant CloudHelper
  EngineStoreLifecycle->>BackgroundGCLoop: start when gc_interval is non-zero
  BackgroundGCLoop->>IAMetaFiles: run IA metadata GC
  BackgroundGCLoop->>CloudHelper: gc_schema_file_cache()
  CloudHelper->>CloudHelper: prune and evict schema-file entries
  EngineStoreLifecycle->>BackgroundGCLoop: set service_shutdown
  BackgroundGCLoop-->>EngineStoreLifecycle: exit and join

Loading

Suggested reviewers: lloyd-pottiger

Poem

I’m a rabbit with cache in my burrow tonight,
Touching keyspaces and pruning bytes light.
IA files hop cleanly, GC loops with care,
Shutdown bells whisper through runtime air.
~( ,_,_,/)
( •ㅅ• )

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.58% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR addresses #10995 by adding background GC for ia_meta files on disk and schema_files in memory.
Out of Scope Changes check	✅ Passed	The dependency pinning and submodule bump appear tied to the GC and kvengine fixes, with no clear unrelated changes.
Title check	✅ Passed	The title matches the main change: GC for IA meta and schema files in cloud_helper.
Description check	✅ Passed	The description covers the problem, changes, testing, side effects, docs, and release note sections.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs`:
- Around line 1390-1399: Update the cache-state insertion in the
latest_by_keyspace loop to capture the current access_seq and assign it to
last_access_seq for newly discovered keyspaces instead of 0. Keep existing
entries’ latest_version updates unchanged, so freshly loaded keyspaces are
treated as recently accessed during gc_schema_file_cache_global eviction.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 9faf5786-67f3-4e03-b576-cc762b795186

📥 Commits

Reviewing files that changed from the base of the PR and between 3d986e3 and f7f5c20.

📒 Files selected for processing (2)

• contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs
• contrib/tiflash-columnar-hub/hub-runtime/src/run.rs

[yongman]

/test pull-integration-test

[yongman]

/hold

[coderabbitai]

🧹 Nitpick comments (1)

contrib/tiflash-columnar-hub/hub-runtime/src/run.rs (1)

1096-1119: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy lift

Add an end-to-end GC lifecycle test.

The added test only validates TOML parsing; it does not prove the spawned loop removes expired IA metadata, evicts schema-cache entries, or exits promptly on shutdown. Add a deterministic integration test using a temporary data directory and a short interval.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@contrib/tiflash-columnar-hub/hub-runtime/src/run.rs` around lines 1096 -
1119, Add a deterministic end-to-end test for spawn_background_gc_loop using a
temporary data directory and short GC interval. Exercise expired IA metadata
cleanup and schema-cache eviction, then signal shutdown and join the returned
thread, asserting the loop exits promptly and both cleanup effects occur rather
than only validating TOML parsing.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@contrib/tiflash-columnar-hub/hub-runtime/src/run.rs`:
- Around line 1096-1119: Add a deterministic end-to-end test for
spawn_background_gc_loop using a temporary data directory and short GC interval.
Exercise expired IA metadata cleanup and schema-cache eviction, then signal
shutdown and join the returned thread, asserting the loop exits promptly and
both cleanup effects occur rather than only validating TOML parsing.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 693b2191-cd14-42c7-9df9-92a185f8b26c

📥 Commits

Reviewing files that changed from the base of the PR and between 97f3f53 and d39fe33.

📒 Files selected for processing (2)

• contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs
• contrib/tiflash-columnar-hub/hub-runtime/src/run.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

contrib/tiflash-columnar-hub/hub-runtime/src/run.rs (1)

1707-1707: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Update the stale Linux ia.mem_cap assertion.

ConfigFile::default() now sets config.ia.mem_cap to Percent(10.0), but Line 1693 still expects Percent(20.0), so the Linux test will fail.

Proposed fix

-            assert_eq!(config.ia.mem_cap, AbsoluteOrPercentSize::Percent(20.0));
+            assert_eq!(config.ia.mem_cap, AbsoluteOrPercentSize::Percent(10.0));

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@contrib/tiflash-columnar-hub/hub-runtime/src/run.rs` at line 1707, Update the
Linux test’s stale ia.mem_cap assertion in the ConfigFile::default() validation
to expect AbsoluteOrPercentSize::Percent(10.0), matching the current default;
leave the existing ia_meta_cap assertion unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@contrib/tiflash-columnar-hub/hub-runtime/src/run.rs`:
- Line 1707: Update the Linux test’s stale ia.mem_cap assertion in the
ConfigFile::default() validation to expect AbsoluteOrPercentSize::Percent(10.0),
matching the current default; leave the existing ia_meta_cap assertion
unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 359b9a0b-fa7a-48fa-9e22-a6cb64a917bd

📥 Commits

Reviewing files that changed from the base of the PR and between d39fe33 and 6f83a78.

⛔ Files ignored due to path filters (1)

• contrib/tiflash-columnar-hub/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (4)

• contrib/cloud-storage-engine
• contrib/tiflash-columnar-hub/Cargo.toml
• contrib/tiflash-columnar-hub/hub-runtime/Cargo.toml
• contrib/tiflash-columnar-hub/hub-runtime/src/run.rs

[JaySon-Huang]

LGTM

[windtalker]

lgtm

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2026-07-30 03:25:05.013900435 +0000 UTC m=+2066491.049995492: ☑️ agreed by JaySon-Huang.
• 2026-07-30 03:38:20.644356923 +0000 UTC m=+2067286.680451979: ☑️ agreed by windtalker.

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: JaySon-Huang, JinheLin, windtalker

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [JaySon-Huang,JinheLin,windtalker]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[yongman]

/cherry-pick release-nextgen-202603

[ti-chi-bot]

@yongman: new pull request created to branch release-nextgen-202603: #11006.

Details

In response to this:

/cherry-pick release-nextgen-202603

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the ti-community-infra/tichi repository.