Skip to content

Caching & Hashing

from sqlspec.core import (
    CacheConfig,
    CachedQuery,
    CachedStatement,
    CacheKey,
    CacheStats,
    LRUCache,
    NamespacedCache,
    QueryCache,
    StatementCacheHolder,
    clear_all_caches,
    create_cache_key,
    get_cache,
    get_cache_config,
    get_cache_statistics,
    hash_expression,
    hash_parameters,
    hash_sql_statement,
    log_cache_stats,
    reset_stats_only,
    update_cache_config,
)

Coordinated L1/L2 LRU caching (StatementCacheHolder, QueryCache, NamespacedCache) and deterministic structural hashing for SQL statements, SQLGlot AST expressions, and parameter bindings. See the Performance Guide for tuning guidance.

Per-Config Fast-Path Cache

StatementCacheHolder

Shared per-config holder for statement caches, rebind processor, and execution hints.

QueryCache

LRU cache for compiled query metadata (L1 per-config fast-path cache).

CachedQuery

Cached query metadata for fast-path execution.

Cache Configuration & Statistics

CacheConfig

Global cache configuration for SQLSpec.

CacheStats

Cache statistics tracking.

Tracks cache metrics including hit rates, evictions, and memory usage.

CachedStatement

Immutable cached statement result.

This class stores compiled SQL and parameters in an immutable format that can be safely shared between different parts of the system without risk of mutation. List parameters are preserved for execute_many operations where drivers require list type.

CacheKey

Immutable cache key.

Parameters:

Name Type Description Default
key_data tuple[Any, ...]

Tuple of hashable values that uniquely identify the cached item

required

Cache Implementations

LRUCache

Cache with LRU eviction and TTL support.

Parameters:

Name Type Description Default
max_size int

Maximum number of items to cache (LRU eviction when exceeded)

DEFAULT_MAX_SIZE
ttl_seconds int | None

Time-to-live in seconds (None for no expiration)

DEFAULT_TTL_SECONDS

get

get(key)

Get value from cache.

Parameters:

Name Type Description Default
key CacheKey

Cache key to lookup

required

Returns:

Type Description
Any | None

Cached value or None if not found or expired

put

put(key, value)

Put value in cache.

Parameters:

Name Type Description Default
key CacheKey

Cache key

required
value Any

Value to cache

required

delete

delete(key)

Delete entry from cache.

Parameters:

Name Type Description Default
key CacheKey

Cache key to delete

required

Returns:

Type Description
bool

True if key was found and deleted, False otherwise

clear

clear()

Clear all cache entries.

get_stats

get_stats()

Get cache statistics.

NamespacedCache

Single cache with namespace isolation.

Uses per-namespace LRU caches sized by CacheConfig to keep memory usage predictable while avoiding stringly-typed cache access.

get_statement

get_statement(key, dialect=None)

Get cached statement data.

Parameters:

Name Type Description Default
key str

Cache key.

required
dialect str | None

Optional SQL dialect.

None

Returns:

Type Description
Any | None

Cached value or None if not found.

put_statement

put_statement(key, value, dialect=None)

Cache compiled statement data.

Parameters:

Name Type Description Default
key str

Cache key.

required
value Any

Value to cache.

required
dialect str | None

Optional SQL dialect.

None

get_expression

get_expression(key, dialect=None)

Get cached expression data.

Parameters:

Name Type Description Default
key str

Cache key.

required
dialect str | None

Optional SQL dialect.

None

Returns:

Type Description
Any | None

Cached value or None if not found.

put_expression

put_expression(key, value, dialect=None)

Cache parsed expression data.

Parameters:

Name Type Description Default
key str

Cache key.

required
value Any

Value to cache.

required
dialect str | None

Optional SQL dialect.

None

Cache Management & Hashing Functions

get_cache

get_cache()

Get the namespaced cache instance.

Returns:

Type Description
NamespacedCache

Singleton namespaced cache instance

create_cache_key

create_cache_key(namespace, key, dialect=None)

Create optimized cache key using string concatenation.

Parameters:

Name Type Description Default
namespace str

Cache namespace name.

required
key str

Base cache key.

required
dialect str | None

SQL dialect (optional).

None

Returns:

Type Description
str

Optimized cache key string.

get_cache_config

get_cache_config()

Get the global cache configuration.

Returns:

Type Description
CacheConfig

Current global cache configuration instance

update_cache_config

update_cache_config(config)

Update the global cache configuration.

Clears all existing caches when configuration changes.

Parameters:

Name Type Description Default
config CacheConfig

New cache configuration to apply globally

required

get_cache_statistics

get_cache_statistics()

Get statistics from all cache instances.

Returns:

Type Description
dict[str, CacheStats]

Dictionary mapping cache type to statistics

clear_all_caches

clear_all_caches()

Clear all L1 driver statement caches and L2 global caches.

reset_stats_only

reset_stats_only()

Reset cache statistics without evicting cached entries.

log_cache_stats

log_cache_stats()

Log cache statistics.

hash_sql_statement

hash_sql_statement(statement)

Generate cache key for a SQL statement.

Parameters:

Name Type Description Default
statement SQL

SQL statement object

required

Returns:

Type Description
str

Cache key string

hash_expression

hash_expression(expr, _seen=None)

Generate hash from AST structure.

Parameters:

Name Type Description Default
expr Expr | None

SQLGlot Expression to hash

required
_seen set[int] | None

Set of active ancestor object IDs to handle circular references

None

Returns:

Type Description
int

Hash of the AST structure

hash_parameters

hash_parameters(
    positional_parameters=None, named_parameters=None, original_parameters=None
)

Generate hash for SQL parameters.

Parameters:

Name Type Description Default
positional_parameters list[Any] | None

List of positional parameters

None
named_parameters dict[str, Any] | None

Dictionary of named parameters

None
original_parameters Any | None

Original parameters (for execute_many)

None

Returns:

Type Description
int

Combined hash of all parameters