sqliter-py 0.9.0__py3-none-any.whl → 0.16.0__py3-none-any.whl

sqliter/sqliter.py

@@ -10,13 +10,16 @@ from __future__ import annotations
 
 import logging
 import sqlite3
+import sys
 import time
-from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union, cast
 
 from typing_extensions import Self
 
 from sqliter.exceptions import (
     DatabaseConnectionError,
+    ForeignKeyConstraintError,
     InvalidIndexError,
     RecordDeletionError,
     RecordFetchError,
@@ -28,15 +31,16 @@ from sqliter.exceptions import (
     TableDeletionError,
 )
 from sqliter.helpers import infer_sqlite_type
-from sqliter.model.unique import Unique
+from sqliter.model.foreign_key import ForeignKeyInfo, get_foreign_key_info
+from sqliter.model.model import BaseDBModel
 from sqliter.query.query import QueryBuilder
 
 if TYPE_CHECKING:  # pragma: no cover
     from types import TracebackType
 
-    from sqliter.model.model import BaseDBModel
+    from pydantic.fields import FieldInfo
 
-T = TypeVar("T", bound="BaseDBModel")
+T = TypeVar("T", bound=BaseDBModel)
 
 
 class SqliterDB:
@@ -64,6 +68,10 @@ class SqliterDB:
         logger: Optional[logging.Logger] = None,
         reset: bool = False,
         return_local_time: bool = True,
+        cache_enabled: bool = False,
+        cache_max_size: int = 1000,
+        cache_ttl: Optional[int] = None,
+        cache_max_memory_mb: Optional[int] = None,
     ) -> None:
         """Initialize a new SqliterDB instance.
 
@@ -76,6 +84,12 @@ class SqliterDB:
             reset: Whether to reset the database on initialization. This will
                 basically drop all existing tables.
             return_local_time: Whether to return local time for datetime fields.
+            cache_enabled: Whether to enable query result caching. Default is
+                False.
+            cache_max_size: Maximum number of cached queries per table (LRU).
+            cache_ttl: Optional time-to-live for cache entries in seconds.
+            cache_max_memory_mb: Optional maximum memory usage for cache in
+                megabytes. When exceeded, oldest entries are evicted.
 
         Raises:
             ValueError: If no filename is provided for a non-memory database.
@@ -99,6 +113,38 @@ class SqliterDB:
 
         self._in_transaction = False
 
+        # Initialize cache
+        self._cache_enabled = cache_enabled
+        self._cache_max_size = cache_max_size
+        self._cache_ttl = cache_ttl
+        self._cache_max_memory_mb = cache_max_memory_mb
+
+        # Validate cache parameters
+        if self._cache_max_size <= 0:
+            msg = "cache_max_size must be greater than 0"
+            raise ValueError(msg)
+        if self._cache_ttl is not None and self._cache_ttl < 0:
+            msg = "cache_ttl must be non-negative"
+            raise ValueError(msg)
+        if (
+            self._cache_max_memory_mb is not None
+            and self._cache_max_memory_mb <= 0
+        ):
+            msg = "cache_max_memory_mb must be greater than 0"
+            raise ValueError(msg)
+        self._cache: OrderedDict[
+            str,
+            OrderedDict[
+                str,
+                tuple[
+                    Union[BaseDBModel, list[BaseDBModel], None],
+                    Optional[float],
+                ],
+            ],
+        ] = OrderedDict()  # {table: {cache_key: (result, expiration)}}
+        self._cache_hits = 0
+        self._cache_misses = 0
+
         if self.debug:
             self._setup_logger()
 
@@ -237,10 +283,215 @@ class SqliterDB:
         if not self.conn:
             try:
                 self.conn = sqlite3.connect(self.db_filename)
+                # Enable foreign key constraint enforcement
+                self.conn.execute("PRAGMA foreign_keys = ON")
             except sqlite3.Error as exc:
                 raise DatabaseConnectionError(self.db_filename) from exc
         return self.conn
 
+    def _cache_get(
+        self,
+        table_name: str,
+        cache_key: str,
+    ) -> tuple[bool, Any]:
+        """Get cached result if valid and not expired.
+
+        Args:
+            table_name: The name of the table.
+            cache_key: The cache key for the query.
+
+        Returns:
+            A tuple of (hit, result) where hit is True if cache hit,
+            False if miss. Result is the cached value (which may be None
+            or an empty list) on a hit, or None on a miss.
+        """
+        if not self._cache_enabled:
+            return False, None
+        if table_name not in self._cache:
+            self._cache_misses += 1
+            return False, None
+        if cache_key not in self._cache[table_name]:
+            self._cache_misses += 1
+            return False, None
+
+        result, expiration = self._cache[table_name][cache_key]
+
+        # Check TTL expiration
+        if expiration is not None and time.time() > expiration:
+            self._cache_misses += 1
+            del self._cache[table_name][cache_key]
+            return False, None
+
+        # Mark as recently used (LRU)
+        self._cache[table_name].move_to_end(cache_key)
+        self._cache_hits += 1
+        return True, result
+
+    def _cache_set(
+        self,
+        table_name: str,
+        cache_key: str,
+        result: Any,  # noqa: ANN401
+        ttl: Optional[int] = None,
+    ) -> None:
+        """Store result in cache with optional expiration.
+
+        Args:
+            table_name: The name of the table.
+            cache_key: The cache key for the query.
+            result: The result to cache.
+            ttl: Optional TTL override for this specific entry.
+        """
+        if not self._cache_enabled:
+            return
+
+        if table_name not in self._cache:
+            self._cache[table_name] = OrderedDict()
+
+        # Calculate expiration (use query-specific TTL if provided)
+        expiration = None
+        effective_ttl = ttl if ttl is not None else self._cache_ttl
+        if effective_ttl is not None:
+            expiration = time.time() + effective_ttl
+
+        self._cache[table_name][cache_key] = (result, expiration)
+        # Mark as most-recently-used
+        self._cache[table_name].move_to_end(cache_key)
+
+        # Enforce memory limit if set
+        if self._cache_max_memory_mb is not None:
+            max_bytes = self._cache_max_memory_mb * 1024 * 1024
+            # Evict LRU entries until under the memory limit
+            while (
+                table_name in self._cache
+                and self._get_table_memory_usage(table_name) > max_bytes
+            ):
+                self._cache[table_name].popitem(last=False)
+
+        # Enforce LRU by size
+        if len(self._cache[table_name]) > self._cache_max_size:
+            self._cache[table_name].popitem(last=False)
+
+    def _cache_invalidate_table(self, table_name: str) -> None:
+        """Clear all cached queries for a specific table.
+
+        Args:
+            table_name: The name of the table to invalidate.
+        """
+        if not self._cache_enabled:
+            return
+        self._cache.pop(table_name, None)
+
+    def _get_table_memory_usage(  # noqa: C901
+        self, table_name: str
+    ) -> int:
+        """Calculate the actual memory usage for a table's cache.
+
+        This method recalculates memory usage on-demand by measuring the
+        size of all cached entries including tuple and dict overhead.
+
+        Args:
+            table_name: The name of the table.
+
+        Returns:
+            The memory usage in bytes.
+        """
+        if table_name not in self._cache:
+            return 0
+
+        total = 0
+        seen: dict[int, int] = {}
+
+        for key, (result, _expiration) in self._cache[table_name].items():
+            # Measure the tuple (result, expiration)
+            total += sys.getsizeof((result, _expiration))
+
+            # Measure the dict key (cache_key string)
+            total += sys.getsizeof(key)
+
+            # Dict entry overhead (approximately 72 bytes for a dict entry)
+            total += 72
+
+            # Recursively measure the result object
+            def measure_size(obj: Any) -> int:  # noqa: C901, ANN401
+                """Recursively measure object size with memoization."""
+                obj_id = id(obj)
+                if obj_id in seen:
+                    return 0  # Already counted
+
+                size = sys.getsizeof(obj)
+                seen[obj_id] = size
+
+                # Handle lists
+                if isinstance(obj, list):
+                    for item in obj:
+                        size += measure_size(item)
+
+                # Handle Pydantic models - measure their fields
+                elif hasattr(type(obj), "model_fields"):
+                    for field_name in type(obj).model_fields:
+                        field_value = getattr(obj, field_name, None)
+                        if field_value is not None:
+                            size += measure_size(field_value)
+                    # Also measure __dict__ if present
+                    if hasattr(obj, "__dict__"):
+                        size += measure_size(obj.__dict__)
+
+                # Handle dicts
+                elif isinstance(obj, dict):
+                    for k, v in obj.items():
+                        size += measure_size(k)
+                        size += measure_size(v)
+
+                # Handle sets and tuples
+                elif isinstance(obj, (set, tuple)):
+                    for item in obj:
+                        size += measure_size(item)
+
+                return size
+
+            total += measure_size(result)
+
+        return total
+
+    def get_cache_stats(self) -> dict[str, int | float]:
+        """Get cache performance statistics.
+
+        Returns:
+            A dictionary containing cache statistics with keys:
+            - hits: Number of cache hits
+            - misses: Number of cache misses
+            - total: Total number of cache lookups
+            - hit_rate: Cache hit rate as a percentage (0-100)
+        """
+        total = self._cache_hits + self._cache_misses
+        hit_rate = (self._cache_hits / total * 100) if total > 0 else 0.0
+        return {
+            "hits": self._cache_hits,
+            "misses": self._cache_misses,
+            "total": total,
+            "hit_rate": round(hit_rate, 2),
+        }
+
+    def clear_cache(self) -> None:
+        """Clear all cached query results.
+
+        This method removes all cached data from memory, freeing up resources
+        and forcing subsequent queries to fetch fresh data from the database.
+
+        Use this when you want to:
+        - Free memory used by the cache
+        - Force fresh queries after external data changes
+
+        Note:
+            Cache statistics (hits/misses) are preserved. To reset statistics,
+            create a new database connection.
+
+        Example:
+            >>> db.clear_cache()
+        """
+        self._cache.clear()
+
     def close(self) -> None:
         """Close the database connection.
 
@@ -252,6 +503,9 @@ class SqliterDB:
             self._maybe_commit()
             self.conn.close()
             self.conn = None
+        self._cache.clear()
+        self._cache_hits = 0
+        self._cache_misses = 0
 
     def commit(self) -> None:
         """Commit the current transaction.
@@ -261,6 +515,94 @@ class SqliterDB:
         if self.conn:
             self.conn.commit()
 
+    def _build_field_definitions(
+        self,
+        model_class: type[BaseDBModel],
+        primary_key: str,
+    ) -> tuple[list[str], list[str], list[str]]:
+        """Build SQL field definitions for table creation.
+
+        Args:
+            model_class: The Pydantic model class.
+            primary_key: The name of the primary key field.
+
+        Returns:
+            A tuple of (fields, foreign_keys, fk_columns) where:
+            - fields: List of column definitions
+            - foreign_keys: List of FK constraint definitions
+            - fk_columns: List of FK column names for index creation
+        """
+        fields = [f'"{primary_key}" INTEGER PRIMARY KEY AUTOINCREMENT']
+        foreign_keys: list[str] = []
+        fk_columns: list[str] = []
+
+        for field_name, field_info in model_class.model_fields.items():
+            if field_name == primary_key:
+                continue
+
+            fk_info = get_foreign_key_info(field_info)
+            if fk_info is not None:
+                col, constraint = self._build_fk_field(field_name, fk_info)
+                fields.append(col)
+                foreign_keys.append(constraint)
+                fk_columns.append(fk_info.db_column or field_name)
+            else:
+                fields.append(self._build_regular_field(field_name, field_info))
+
+        return fields, foreign_keys, fk_columns
+
+    def _build_fk_field(
+        self, field_name: str, fk_info: ForeignKeyInfo
+    ) -> tuple[str, str]:
+        """Build FK column definition and constraint.
+
+        Args:
+            field_name: The name of the field.
+            fk_info: The ForeignKeyInfo metadata.
+
+        Returns:
+            A tuple of (column_def, fk_constraint).
+        """
+        column_name = fk_info.db_column or field_name
+        null_str = "" if fk_info.null else "NOT NULL"
+        unique_str = "UNIQUE" if fk_info.unique else ""
+
+        field_def = f'"{column_name}" INTEGER {null_str} {unique_str}'
+        column_def = " ".join(field_def.split())
+
+        target_table = fk_info.to_model.get_table_name()
+        fk_constraint = (
+            f'FOREIGN KEY ("{column_name}") '
+            f'REFERENCES "{target_table}"("pk") '
+            f"ON DELETE {fk_info.on_delete} "
+            f"ON UPDATE {fk_info.on_update}"
+        )
+
+        return column_def, fk_constraint
+
+    def _build_regular_field(
+        self, field_name: str, field_info: FieldInfo
+    ) -> str:
+        """Build a regular (non-FK) column definition.
+
+        Args:
+            field_name: The name of the field.
+            field_info: The Pydantic field info.
+
+        Returns:
+            The column definition string.
+        """
+        sqlite_type = infer_sqlite_type(field_info.annotation)
+        unique_constraint = ""
+        if (
+            hasattr(field_info, "json_schema_extra")
+            and field_info.json_schema_extra
+            and isinstance(field_info.json_schema_extra, dict)
+            and field_info.json_schema_extra.get("unique", False)
+        ):
+            unique_constraint = "UNIQUE"
+        return f'"{field_name}" {sqlite_type} {unique_constraint}'.strip()
+
     def create_table(
         self,
         model_class: type[BaseDBModel],
@@ -288,26 +630,20 @@ class SqliterDB:
             drop_table_sql = f"DROP TABLE IF EXISTS {table_name}"
             self._execute_sql(drop_table_sql)
 
-        fields = [f'"{primary_key}" INTEGER PRIMARY KEY AUTOINCREMENT']
+        fields, foreign_keys, fk_columns = self._build_field_definitions(
+            model_class, primary_key
+        )
 
-        # Add remaining fields
-        for field_name, field_info in model_class.model_fields.items():
-            if field_name != primary_key:
-                sqlite_type = infer_sqlite_type(field_info.annotation)
-                unique_constraint = (
-                    "UNIQUE" if isinstance(field_info, Unique) else ""
-                )
-                fields.append(
-                    f"{field_name} {sqlite_type} {unique_constraint}".strip()
-                )
+        # Combine field definitions and FK constraints
+        all_definitions = fields + foreign_keys
 
         create_str = (
             "CREATE TABLE IF NOT EXISTS" if exists_ok else "CREATE TABLE"
         )
 
         create_table_sql = f"""
-        {create_str} {table_name} (
-            {", ".join(fields)}
+        {create_str} "{table_name}" (
+            {", ".join(all_definitions)}
         )
         """
 
@@ -322,6 +658,14 @@ class SqliterDB:
         except sqlite3.Error as exc:
             raise TableCreationError(table_name) from exc
 
+        # Create indexes for FK columns
+        for column_name in fk_columns:
+            index_sql = (
+                f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_{column_name}" '
+                f'ON "{table_name}" ("{column_name}")'
+            )
+            self._execute_sql(index_sql)
+
         # Create regular indexes
         if hasattr(model_class.Meta, "indexes"):
             self._create_indexes(
@@ -373,11 +717,14 @@ class SqliterDB:
             index_postfix = "_unique" if unique else ""
             index_type = " UNIQUE " if unique else " "
 
+            # Quote field names for index creation
+            quoted_fields = ", ".join(f'"{field}"' for field in fields)
+
             create_index_sql = (
                 f"CREATE{index_type}INDEX IF NOT EXISTS "
                 f"idx_{model_class.get_table_name()}"
                 f"_{index_name}{index_postfix} "
-                f"ON {model_class.get_table_name()} ({', '.join(fields)})"
+                f'ON "{model_class.get_table_name()}" ({quoted_fields})'
             )
             self._execute_sql(create_index_sql)
 
@@ -433,6 +780,64 @@ class SqliterDB:
         if not self._in_transaction and self.auto_commit and self.conn:
             self.conn.commit()
 
+    def _set_insert_timestamps(
+        self, model_instance: T, *, timestamp_override: bool
+    ) -> None:
+        """Set created_at and updated_at timestamps for insert.
+
+        Args:
+            model_instance: The model instance to update.
+            timestamp_override: If True, respect provided non-zero values.
+        """
+        current_timestamp = int(time.time())
+
+        if not timestamp_override:
+            model_instance.created_at = current_timestamp
+            model_instance.updated_at = current_timestamp
+        else:
+            if model_instance.created_at == 0:
+                model_instance.created_at = current_timestamp
+            if model_instance.updated_at == 0:
+                model_instance.updated_at = current_timestamp
+
+    def _create_instance_from_data(
+        self,
+        model_class: type[T],
+        data: dict[str, Any],
+        pk: Optional[int] = None,
+    ) -> T:
+        """Create a model instance from deserialized data.
+
+        Handles ORM-specific field exclusions and db_context setup.
+
+        Args:
+            model_class: The model class to instantiate.
+            data: Raw data dictionary from the database.
+            pk: Optional primary key value to set.
+
+        Returns:
+            A new model instance with db_context set if applicable.
+        """
+        # Deserialize each field before creating the model instance
+        deserialized_data: dict[str, Any] = {}
+        for field_name, value in data.items():
+            deserialized_data[field_name] = model_class.deserialize_field(
+                field_name, value, return_local_time=self.return_local_time
+            )
+        # For ORM mode, exclude FK descriptor fields from data
+        for fk_field in getattr(model_class, "fk_descriptors", {}):
+            deserialized_data.pop(fk_field, None)
+
+        if pk is not None:
+            instance = model_class(pk=pk, **deserialized_data)
+        else:
+            instance = model_class(**deserialized_data)
+
+        # Set db_context for ORM lazy loading and reverse relationships
+        if hasattr(instance, "db_context"):
+            instance.db_context = self
+        return instance
+
     def insert(
         self, model_instance: T, *, timestamp_override: bool = False
     ) -> T:
@@ -455,20 +860,9 @@ class SqliterDB:
         model_class = type(model_instance)
         table_name = model_class.get_table_name()
 
-        # Always set created_at and updated_at timestamps
-        current_timestamp = int(time.time())
-
-        # Handle the case where timestamp_override is False
-        if not timestamp_override:
-            # Always override both timestamps with the current time
-            model_instance.created_at = current_timestamp
-            model_instance.updated_at = current_timestamp
-        else:
-            # Respect provided values, but set to current time if they are 0
-            if model_instance.created_at == 0:
-                model_instance.created_at = current_timestamp
-            if model_instance.updated_at == 0:
-                model_instance.updated_at = current_timestamp
+        self._set_insert_timestamps(
+            model_instance, timestamp_override=timestamp_override
+        )
 
         # Get the data from the model
         data = model_instance.model_dump()
@@ -494,31 +888,50 @@ class SqliterDB:
         """  # noqa: S608
 
         try:
-            with self.connect() as conn:
-                cursor = conn.cursor()
-                cursor.execute(insert_sql, values)
-                self._maybe_commit()
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute(insert_sql, values)
+            self._maybe_commit()
 
+        except sqlite3.IntegrityError as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
+            # Check for foreign key constraint violation
+            if "FOREIGN KEY constraint failed" in str(exc):
+                fk_operation = "insert"
+                fk_reason = "does not exist in referenced table"
+                raise ForeignKeyConstraintError(
+                    fk_operation, fk_reason
+                ) from exc
+            raise RecordInsertionError(table_name) from exc
         except sqlite3.Error as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
             raise RecordInsertionError(table_name) from exc
         else:
+            self._cache_invalidate_table(table_name)
             data.pop("pk", None)
-            # Deserialize each field before creating the model instance
-            deserialized_data = {}
-            for field_name, value in data.items():
-                deserialized_data[field_name] = model_class.deserialize_field(
-                    field_name, value, return_local_time=self.return_local_time
-                )
-            return model_class(pk=cursor.lastrowid, **deserialized_data)
+            return self._create_instance_from_data(
+                model_class, data, pk=cursor.lastrowid
+            )
 
     def get(
-        self, model_class: type[BaseDBModel], primary_key_value: int
-    ) -> BaseDBModel | None:
+        self,
+        model_class: type[T],
+        primary_key_value: int,
+        *,
+        bypass_cache: bool = False,
+        cache_ttl: Optional[int] = None,
+    ) -> T | None:
         """Retrieve a single record from the database by its primary key.
 
         Args:
             model_class: The Pydantic model class representing the table.
             primary_key_value: The value of the primary key to look up.
+            bypass_cache: If True, skip reading/writing cache for this call.
+            cache_ttl: Optional TTL override for this specific lookup.
 
         Returns:
             An instance of the model class if found, None otherwise.
@@ -526,8 +939,18 @@ class SqliterDB:
         Raises:
             RecordFetchError: If there's an error fetching the record.
         """
+        if cache_ttl is not None and cache_ttl < 0:
+            msg = "cache_ttl must be non-negative"
+            raise ValueError(msg)
+
         table_name = model_class.get_table_name()
         primary_key = model_class.get_primary_key()
+        cache_key = f"pk:{primary_key_value}"
+
+        if not bypass_cache:
+            hit, cached = self._cache_get(table_name, cache_key)
+            if hit:
+                return cast("Optional[T]", cached)
 
         fields = ", ".join(model_class.model_fields)
 
@@ -536,30 +959,29 @@ class SqliterDB:
         """  # noqa: S608
 
         try:
-            with self.connect() as conn:
-                cursor = conn.cursor()
-                cursor.execute(select_sql, (primary_key_value,))
-                result = cursor.fetchone()
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute(select_sql, (primary_key_value,))
+            result = cursor.fetchone()
 
             if result:
                 result_dict = {
                     field: result[idx]
                     for idx, field in enumerate(model_class.model_fields)
                 }
-                # Deserialize each field before creating the model instance
-                deserialized_data = {}
-                for field_name, value in result_dict.items():
-                    deserialized_data[field_name] = (
-                        model_class.deserialize_field(
-                            field_name,
-                            value,
-                            return_local_time=self.return_local_time,
-                        )
+                instance = self._create_instance_from_data(
+                    model_class, result_dict
+                )
+                if not bypass_cache:
+                    self._cache_set(
+                        table_name, cache_key, instance, ttl=cache_ttl
                     )
-                return model_class(**deserialized_data)
+                return instance
         except sqlite3.Error as exc:
             raise RecordFetchError(table_name) from exc
         else:
+            if not bypass_cache:
+                self._cache_set(table_name, cache_key, None, ttl=cache_ttl)
             return None
 
     def update(self, model_instance: BaseDBModel) -> None:
@@ -582,6 +1004,7 @@ class SqliterDB:
 
         # Get the data and serialize any datetime/date fields
         data = model_instance.model_dump()
+
         for field_name, value in list(data.items()):
             data[field_name] = model_instance.serialize_field(value)
 
@@ -599,21 +1022,30 @@ class SqliterDB:
         """  # noqa: S608
 
         try:
-            with self.connect() as conn:
-                cursor = conn.cursor()
-                cursor.execute(update_sql, (*values, primary_key_value))
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute(update_sql, (*values, primary_key_value))
 
-                # Check if any rows were updated
-                if cursor.rowcount == 0:
-                    raise RecordNotFoundError(primary_key_value)
+            # Check if any rows were updated
+            if cursor.rowcount == 0:
+                raise RecordNotFoundError(primary_key_value)  # noqa: TRY301
 
-                self._maybe_commit()
+            self._maybe_commit()
+            self._cache_invalidate_table(table_name)
 
+        except RecordNotFoundError:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
+            raise
         except sqlite3.Error as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
             raise RecordUpdateError(table_name) from exc
 
     def delete(
-        self, model_class: type[BaseDBModel], primary_key_value: str
+        self, model_class: type[BaseDBModel], primary_key_value: Union[int, str]
     ) -> None:
         """Delete a record from the database by its primary key.
 
@@ -634,22 +1066,43 @@ class SqliterDB:
         """  # noqa: S608
 
         try:
-            with self.connect() as conn:
-                cursor = conn.cursor()
-                cursor.execute(delete_sql, (primary_key_value,))
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute(delete_sql, (primary_key_value,))
 
-                if cursor.rowcount == 0:
-                    raise RecordNotFoundError(primary_key_value)
-                self._maybe_commit()
+            if cursor.rowcount == 0:
+                raise RecordNotFoundError(primary_key_value)  # noqa: TRY301
+            self._maybe_commit()
+            self._cache_invalidate_table(table_name)
+        except RecordNotFoundError:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
+            raise
+        except sqlite3.IntegrityError as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
+            # Check for foreign key constraint violation (RESTRICT)
+            if "FOREIGN KEY constraint failed" in str(exc):
+                fk_operation = "delete"
+                fk_reason = "is still referenced by other records"
+                raise ForeignKeyConstraintError(
+                    fk_operation, fk_reason
+                ) from exc
+            raise RecordDeletionError(table_name) from exc
         except sqlite3.Error as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
             raise RecordDeletionError(table_name) from exc
 
     def select(
         self,
-        model_class: type[BaseDBModel],
+        model_class: type[T],
         fields: Optional[list[str]] = None,
         exclude: Optional[list[str]] = None,
-    ) -> QueryBuilder:
+    ) -> QueryBuilder[T]:
         """Create a QueryBuilder instance for selecting records.
 
         Args:
@@ -660,7 +1113,7 @@ class SqliterDB:
         Returns:
             A QueryBuilder instance for further query construction.
         """
-        query_builder = QueryBuilder(self, model_class, fields)
+        query_builder: QueryBuilder[T] = QueryBuilder(self, model_class, fields)
 
         # If exclude is provided, apply the exclude method
         if exclude:
@@ -722,3 +1175,7 @@ class SqliterDB:
                 self.conn.close()
                 self.conn = None
                 self._in_transaction = False
+        # Clear cache when exiting context
+        self._cache.clear()
+        self._cache_hits = 0
+        self._cache_misses = 0