localvectordb.sqlite_tuning module

SQLite performance tuning and optimization for LocalVectorDB.

This module provides comprehensive SQLite tuning capabilities including: - Predefined performance profiles for different workloads - Safe pragma application with validation - System resource analysis for intelligent tuning - Maintenance utilities for database optimization

Classes

SQLitePragmaProfile

Configuration profile containing pragma settings

SystemInfo

System resource information for tuning decisions

WorkloadProfile

User workload characteristics for auto-tuning

TuningRecommendation

Auto-tuner recommendation with profile and overrides

AutoTuner

Intelligent profile selection based on system and workload

class localvectordb.sqlite_tuning.WorkloadType(*values)

Bases: Enum

Workload type enumeration for auto-tuning.

READ_HEAVY = 'read_heavy'
WRITE_HEAVY = 'write_heavy'
BALANCED = 'balanced'
BATCH_INGEST = 'batch_ingest'
REAL_TIME = 'real_time'
class localvectordb.sqlite_tuning.DurabilityLevel(*values)

Bases: Enum

Data durability importance levels.

CRITICAL = 'critical'
HIGH = 'high'
NORMAL = 'normal'
LOW = 'low'
class localvectordb.sqlite_tuning.SQLitePragmaProfile(name: str, description: str = '', pragmas: Dict[str, ~typing.Any]=<factory>)

Bases: object

SQLite pragma configuration profile.

Parameters:

  • name (str) – Profile name identifier

  • description (str) – Human-readable description of the profile

  • pragmas (Dict[str, Any]) – Dictionary of pragma key-value pairs

name: str
description: str = ''
pragmas: Dict[str, Any]
__init__(name: str, description: str = '', pragmas: Dict[str, ~typing.Any]=<factory>) → None
localvectordb.sqlite_tuning.is_valid_sqlite_pragma_profile(profile: Literal['balanced', 'fast_ingest', 'read_optimized', 'durable', 'memory_saver']) → bool
localvectordb.sqlite_tuning.get_sqlite_pragma_profile(profile: Literal['balanced', 'fast_ingest', 'read_optimized', 'durable', 'memory_saver'], *, default: Literal['balanced', 'fast_ingest', 'read_optimized', 'durable', 'memory_saver'] | None = None) → SQLitePragmaProfile | None
localvectordb.sqlite_tuning.validate_pragma_key(key: str) → bool

Validate pragma key for safety.

Parameters:

key (str) – Pragma key to validate

Returns:

True if key is safe, False otherwise

Return type:

bool

localvectordb.sqlite_tuning.format_pragma_value(value: Any) → str

Format pragma value for SQL execution.

Parameters:

value (Any) – Pragma value to format

Returns:

Formatted value safe for SQL

Return type:

str

localvectordb.sqlite_tuning.apply_pragmas(conn: Connection, pragmas: Dict[str, Any]) → None

Apply pragma settings to a SQLite connection.

Parameters:

  • conn (sqlite3.Connection) – SQLite database connection

  • pragmas (Dict[str, Any]) – Dictionary of pragma key-value pairs to apply

async localvectordb.sqlite_tuning.apply_pragmas_async(conn: Connection, pragmas: Dict[str, Any]) → None

Apply pragma settings to an async SQLite connection.

Parameters:

  • conn (aiosqlite.Connection) – Async SQLite database connection

  • pragmas (Dict[str, Any]) – Dictionary of pragma key-value pairs to apply

class localvectordb.sqlite_tuning.SystemInfo(total_ram_mb: int, available_ram_mb: int, cpu_cores: int, disk_type: str, disk_free_gb: float, os_type: str)

Bases: object

System resource information for tuning decisions.

Parameters:

  • total_ram_mb (int) – Total system RAM in megabytes

  • available_ram_mb (int) – Available system RAM in megabytes

  • cpu_cores (int) – Number of CPU cores

  • disk_type (str) – Disk type (SSD/HDD/Unknown)

  • disk_free_gb (float) – Free disk space in gigabytes

  • os_type (str) – Operating system type

total_ram_mb: int
available_ram_mb: int
cpu_cores: int
disk_type: str
disk_free_gb: float
os_type: str
__init__(total_ram_mb: int, available_ram_mb: int, cpu_cores: int, disk_type: str, disk_free_gb: float, os_type: str) → None
class localvectordb.sqlite_tuning.WorkloadProfile(workload_type: WorkloadType, document_size: str, concurrent_users: int, durability_level: DurabilityLevel, memory_constraint: str)

Bases: object

User workload characteristics for auto-tuning.

Parameters:

  • workload_type (WorkloadType) – Primary workload pattern

  • document_size (str) – Typical document size (small/medium/large)

  • concurrent_users (int) – Expected number of concurrent users

  • durability_level (DurabilityLevel) – Data persistence importance

  • memory_constraint (str) – Memory availability (generous/moderate/limited)

workload_type: WorkloadType
document_size: str
concurrent_users: int
durability_level: DurabilityLevel
memory_constraint: str
__init__(workload_type: WorkloadType, document_size: str, concurrent_users: int, durability_level: DurabilityLevel, memory_constraint: str) → None
class localvectordb.sqlite_tuning.TuningRecommendation(profile_name: str, pragma_overrides: Dict[str, Any], reasoning: List[str], estimated_memory_mb: int)

Bases: object

Auto-tuner recommendation result.

Parameters:

  • profile_name (str) – Recommended base profile name

  • pragma_overrides (Dict[str, Any]) – Custom pragma overrides for the profile

  • reasoning (List[str]) – Explanation of the recommendation

  • estimated_memory_mb (int) – Estimated memory usage with these settings

profile_name: str
pragma_overrides: Dict[str, Any]
reasoning: List[str]
estimated_memory_mb: int
__init__(profile_name: str, pragma_overrides: Dict[str, Any], reasoning: List[str], estimated_memory_mb: int) → None
class localvectordb.sqlite_tuning.AutoTuner

Bases: object

Intelligent SQLite tuning based on system resources and workload.

This class analyzes system resources and user requirements to recommend optimal SQLite pragma settings for LocalVectorDB.

static analyze_system() → SystemInfo

Analyze system resources for tuning decisions.

Returns:

System resource information

Return type:

SystemInfo

static recommend_profile(system: SystemInfo, workload: WorkloadProfile) → TuningRecommendation

Recommend optimal tuning profile based on system and workload.

Parameters:
Returns:

Recommended profile and settings

Return type:

TuningRecommendation

static interview_user_cli() → WorkloadProfile

Interactive CLI interview to gather workload information.

Returns:

User’s workload characteristics

Return type:

WorkloadProfile

localvectordb.sqlite_tuning.get_profile_description(profile_name: str) → str

Get human-readable description of a profile.

Parameters:

profile_name (str) – Name of the profile

Returns:

Profile description

Return type:

str

localvectordb.sqlite_tuning.list_profiles() → List[Tuple[str, str]]

List all available tuning profiles.

Returns:

List of (name, description) tuples

Return type:

List[Tuple[str, str]]