Struct PreparedStatementCache 

pub struct PreparedStatementCache { /* private fields */ }

Connection-aware prepared statement cache

This cache tracks prepared statements per connection, ensuring that statement metadata is associated with the correct connection.

Thread Safety

The cache uses RwLock for interior mutability, allowing concurrent reads and exclusive writes. All operations are thread-safe.

Connection Lifecycle

When a connection is returned to the pool or closed, its cache should be cleared by calling clear_connection().

Implementations

impl PreparedStatementCache

pub fn new(max_size: usize) -> Self

Create a new connection-aware prepared statement cache

Arguments

• max_size - Maximum number of statements to cache per connection

Example

use do_memory_storage_turso::prepared::PreparedStatementCache;

let cache = PreparedStatementCache::new(100);

pub fn with_config(config: PreparedCacheConfig) -> Self

Create a cache with custom configuration

pub fn get_connection_id(&self) -> ConnectionId

Get or create a connection ID for a connection

This generates a unique ID for tracking the connection in the cache. The ID should be stored alongside the connection and used for all cache operations with that connection.

pub fn record_hit(&self, conn_id: ConnectionId, sql: &str)

Record a cache hit for a statement

This should be called when a statement is found in SQLite’s internal cache or when the application determines a statement was reused.

Arguments

• conn_id - Connection identifier
• sql - SQL statement that was hit

pub fn record_miss( &self, conn_id: ConnectionId, sql: &str, prepare_time_us: u64, )

Record a cache miss for a statement

This should be called when a statement needs to be prepared.

Arguments

• conn_id - Connection identifier
• sql - SQL statement that was missed
• prepare_time_us - Time taken to prepare the statement (microseconds)

pub fn is_cached(&self, conn_id: ConnectionId, sql: &str) -> bool

Check if a statement is cached for a connection

Arguments

• conn_id - Connection identifier
• sql - SQL statement to check

Returns

true if the statement is cached and doesn’t need refresh

pub async fn get_or_prepare( &self, conn: &Connection, sql: &str, ) -> Result<Statement, Error>

Get a prepared statement or prepare it if not cached

This is a convenience method that generates a new connection ID for each call. For proper connection-aware caching, use get_connection_id() and the connection-specific methods instead.

Arguments

• conn - Database connection to prepare on
• sql - SQL statement to prepare

Returns

The prepared statement

Errors

Returns error if statement preparation fails

pub fn clear_connection(&self, conn_id: ConnectionId) -> usize

Clear all cached statements for a specific connection

This should be called when a connection is returned to the pool or closed to prevent memory leaks.

Arguments

• conn_id - Connection identifier to clear

Returns

Number of statements cleared

pub fn clear(&self)

Clear all cached statements across all connections

pub fn stats(&self) -> PreparedCacheStats

Get current cache statistics

pub fn total_size(&self) -> usize

Get current total cache size (across all connections)

pub fn connection_size(&self, conn_id: ConnectionId) -> usize

Get cache size for a specific connection

pub fn is_empty(&self) -> bool

Check if cache is empty

pub fn connection_count(&self) -> usize

Get number of tracked connections

pub fn remove(&self, conn_id: ConnectionId, sql: &str) -> bool

Remove a specific statement from a connection’s cache

pub fn cleanup_idle_connections(&self, max_idle_duration: Duration) -> usize

Clean up idle connection caches

Removes connection caches that haven’t been accessed for longer than the threshold. This helps prevent memory leaks from abandoned connection IDs.

Arguments

• max_idle_duration - Maximum idle time before cleanup

Returns

Number of connections cleaned up

Trait Implementations

impl Default for PreparedStatementCache

fn default() -> Self

Returns the “default value” for a type.