feat(fuzzy-finder): add TTL-based candidate caching for database and table completion

[apstndb]

Summary

Add TTL-based caching for fuzzy completion candidates (databases and tables) to avoid repeated network calls when triggering fuzzy finders multiple times. Cached results are reused within a 30-second window unless invalidated by session changes or DDL execution.

Key Changes

• session.go: Add schemaGeneration uint64 field to Session with SchemaGeneration() / IncrementSchemaGeneration() accessors, providing a lightweight signal for schema-dependent cache invalidation
• execute_sql.go: Increment schema generation after successful DDL execution (both sync and async paths)
• fuzzy_finder.go: Add fuzzyCacheEntry struct with TTL + session pointer + schema generation validity checks; cache database and table candidates on fuzzyFinderCommand; short-circuit resolveCandidates() on cache hit (skips loading indicator and network call)
• fuzzy_finder_test.go: Add TestFuzzyCacheEntryValid table-driven test covering nil entry, session change, TTL expiry, valid cache, and stale schema generation

Cache Invalidation Triggers

Trigger	Mechanism
TTL expiry (30s)	time.Now().After(expiresAt)
USE/DETACH (session change)	Session pointer comparison
DDL (schema change)	schemaGeneration counter mismatch

Test Plan

• make check passes (test + lint + fmt-check)
• Manual testing: verified repeated fuzzy finder triggers reuse cached results, and cache invalidates after DDL

Fixes #514

[gemini-code-assist]

Summary of Changes

Hello @apstndb, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the performance and user experience of the fuzzy finder feature by introducing a robust caching mechanism. By storing frequently accessed database and table completion candidates in a time-limited cache, it eliminates redundant network requests, leading to faster response times. The cache is intelligently invalidated upon schema modifications or session changes, ensuring data consistency without manual intervention.

Highlights

• TTL-based Caching for Fuzzy Finder: Implemented a Time-To-Live (TTL) based caching mechanism for fuzzy completion candidates (databases and tables) to reduce repeated network calls.
• Schema Change Detection: Introduced a schemaGeneration counter in the Session struct, which is incremented after DDL (Data Definition Language) executions to invalidate schema-dependent caches.
• Cache Invalidation Triggers: Cache entries are invalidated based on TTL expiry (30 seconds), session changes (e.g., USE/DETACH commands), and schema changes (DDL execution).
• Optimized Candidate Resolution: The resolveCandidates() function in the fuzzy finder now checks the cache first, short-circuiting network calls and loading indicators on a cache hit.
• Comprehensive Cache Testing: Added a new test suite, TestFuzzyCacheEntryValid, to thoroughly verify the cache invalidation logic under various conditions including nil entries, session changes, TTL expiry, and schema generation mismatches.

Changelog

• internal/mycli/execute_sql.go
  • Incremented session.schemaGeneration after asynchronous DDL execution.
  • Incremented session.schemaGeneration after synchronous DDL execution.
• internal/mycli/fuzzy_finder.go
  • Defined fuzzyCacheTTL constant for cache entry expiration.
  • Introduced fuzzyCacheEntry struct to store candidates, expiry time, session, and schema generation.
  • Added valid method to fuzzyCacheEntry to check if a cache entry is still usable based on session, TTL, and schema generation.
  • Added databaseCache and tableCache fields to fuzzyFinderCommand to hold cached candidates.
  • Implemented getCachedCandidates method to retrieve candidates from the cache if valid.
  • Implemented setCachedCandidates method to store new candidates in the appropriate cache with expiry and schema generation.
  • Modified resolveCandidates to first check for cached candidates before initiating a network fetch.
  • Updated resolveCandidates to store successfully fetched candidates in the cache.
• internal/mycli/fuzzy_finder_test.go
  • Imported the time package for time-related operations.
  • Added TestFuzzyCacheEntryValid with multiple test cases to validate the fuzzyCacheEntry.valid method's logic for different invalidation scenarios.
• internal/mycli/session.go
  • Added schemaGeneration field to the Session struct to track schema changes.
  • Added SchemaGeneration() getter method to retrieve the current schema generation counter.
  • Added IncrementSchemaGeneration() method to increment the schema generation counter, signaling cache invalidation.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Code Metrics Report

📊 View detailed coverage report (available for 7 days)

	main (e4b5fb0)	#517 (5b29b0a)	+/-
Coverage	68.1%	68.0%	-0.2%
Code to Test Ratio	1:1.2	1:1.2	-0.1
Test Execution Time	1m17s	1m4s	-13s

Details

  |                     | main (e4b5fb0) | #517 (5b29b0a) |  +/-  |
  |---------------------|----------------|----------------|-------|
- | Coverage            |          68.1% |          68.0% | -0.2% |
  |   Files             |             55 |             55 |     0 |
  |   Lines             |           5929 |           5959 |   +30 |
+ |   Covered           |           4043 |           4053 |   +10 |
- | Code to Test Ratio  |          1:1.2 |          1:1.2 |  -0.1 |
  |   Code              |          13611 |          13683 |   +72 |
+ |   Test              |          16960 |          17037 |   +77 |
+ | Test Execution Time |          1m17s |           1m4s |  -13s |

Code coverage of files in pull request scope (65.0% → 64.2%)

Files	Coverage	+/-	Status
internal/mycli/execute_sql.go	73.6%	-0.2%	modified
internal/mycli/fuzzy_finder.go	22.7%	+0.5%	modified
internal/mycli/session.go	73.3%	+0.0%	modified

---

Reported by octocov

[gemini-code-assist]

Code Review

This pull request introduces a well-designed TTL-based caching mechanism for fuzzy finder candidates, which should significantly improve performance by reducing network calls. The implementation is clean and the cache invalidation logic correctly handles session changes, TTL expiry, and schema modifications via DDL. The addition of unit tests for the cache validation logic is also a great practice.

However, I've identified a critical data race on the new schemaGeneration field in the Session struct. The increment and read operations are not atomic, which could lead to incorrect cache behavior or panics in concurrent scenarios (e.g., fuzzy finder used during an async DDL). I've provided a suggestion to resolve this using the sync/atomic package, which is idiomatic for this use case.

[apstndb]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a TTL-based caching mechanism for fuzzy finder candidates, specifically for database and table completions, to reduce network calls and improve performance. The implementation correctly handles cache invalidation based on TTL, session changes, and schema modifications triggered by DDL statements. The use of an atomic counter for tracking schema generation is appropriate for ensuring thread safety. The new caching logic is also validated with a comprehensive set of unit tests. The changes are well-implemented and I have no issues to report.

[apstndb]

/gemini summary

[gemini-code-assist]

Summary of Changes

This pull request significantly enhances the performance and user experience of the fuzzy finder feature by introducing a robust caching mechanism for database and table completion candidates. By storing frequently accessed suggestions in a time-limited cache, it eliminates redundant network requests, leading to faster response times. The cache is intelligently invalidated upon schema modifications or session changes, ensuring data consistency without manual intervention.

Highlights

• TTL-based Caching for Fuzzy Finder: Implemented a Time-To-Live (TTL) based caching mechanism for fuzzy completion candidates (databases and tables) to reduce repeated network calls, with a default expiry of 30 seconds.
• Schema Change Detection: Introduced a schemaGeneration counter in the Session struct, which is atomically incremented after DDL (Data Definition Language) executions to invalidate schema-dependent caches.
• Intelligent Cache Invalidation: Cache entries are invalidated based on TTL expiry, changes in the active session, and mismatches in the schemaGeneration counter, ensuring data consistency.
• Optimized Candidate Resolution: The resolveCandidates() function in the fuzzy finder now checks for valid cached candidates first, bypassing network calls and loading indicators on a cache hit.
• Comprehensive Cache Testing: Added a new test suite, TestFuzzyCacheEntryValid, to thoroughly verify the cache invalidation logic under various conditions including nil entries, session changes, TTL expiry, and schema generation mismatches.

Changelog

• internal/mycli/execute_sql.go
  • Incremented session.schemaGeneration after asynchronous DDL execution.
  • Incremented session.schemaGeneration after synchronous DDL execution.
• internal/mycli/fuzzy_finder.go
  • Defined fuzzyCacheTTL constant for cache entry expiration.
  • Introduced fuzzyCacheEntry struct to store candidates, expiry time, session, and schema generation.
  • Added valid method to fuzzyCacheEntry to check if a cache entry is still usable based on session, TTL, and schema generation.
  • Added databaseCache and tableCache fields to fuzzyFinderCommand to hold cached candidates.
  • Implemented getCachedCandidates method to retrieve candidates from the cache if valid.
  • Implemented setCachedCandidates method to store new candidates in the appropriate cache with expiry and schema generation.
  • Modified resolveCandidates to first check for cached candidates before initiating a network fetch.
  • Updated resolveCandidates to store successfully fetched candidates in the cache.
• internal/mycli/fuzzy_finder_test.go
  • Imported the time package for time-related operations.
  • Added TestFuzzyCacheEntryValid with multiple test cases to validate the fuzzyCacheEntry.valid method's logic for different invalidation scenarios.
• internal/mycli/session.go
  • Imported sync/atomic for thread-safe operations.
  • Added schemaGeneration field to the Session struct to track schema changes.
  • Added SchemaGeneration() getter method using atomic load to retrieve the current schema generation counter.
  • Added IncrementSchemaGeneration() method using atomic add to increment the schema generation counter, signaling cache invalidation.

Activity

• gemini-code-assist[bot] provided an initial summary of the pull request's changes.
• gemini-code-assist[bot] identified a potential data race on the schemaGeneration field and suggested using atomic operations for thread safety.
• apstndb (author) acknowledged the bot's feedback and confirmed applying atomic operations to schemaGeneration, noting it as a defensive measure for future concurrency.
• github-actions[bot] posted a code metrics report, indicating a slight decrease in overall coverage but an increase in lines and covered lines.
• apstndb requested a review from gemini-code-assist[bot].
• apstndb requested a summary from gemini-code-assist[bot].