Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

10.2 KB
Raw Blame
"""
SQLCipher compatibility module for cross-platform support.

Provides a unified interface for importing SQLCipher on different platforms:
- x86_64 Linux: Uses sqlcipher3-binary (pre-compiled wheel)
- ARM64 Linux: Uses sqlcipher3 (builds from source)
- Other platforms: Uses sqlcipher3
"""

from functools import lru_cache
import os
import threading


_lifecycle_lock = threading.RLock()


def _reset_lifecycle_lock():
    """A fork must not inherit a lock owned by a vanished parent thread."""
    global _lifecycle_lock
    _lifecycle_lock = threading.RLock()


if hasattr(os, "register_at_fork"):
    os.register_at_fork(after_in_child=_reset_lifecycle_lock)


# Driver entry points that refuse a foreign thread when a connection is
# opened with check_same_thread=True (pysqlite_check_thread in sqlcipher3).
_CONNECTION_THREAD_CHECKED = (
    "__call__",
    "commit",
    "create_aggregate",
    "create_collation",
    "create_function",
    "create_window_function",
    "enable_load_extension",
    "execute",
    "executemany",
    "executescript",
    "load_extension",
    "open_blob",
    "rollback",
    "set_authorizer",
    "set_busy_handler",
    "set_busy_timeout",
    "set_progress_handler",
    "set_trace_callback",
)
_CURSOR_THREAD_CHECKED = (
    "__next__",
    "close",
    "execute",
    "executemany",
    "executescript",
    "fetchall",
    "fetchmany",
    "fetchone",
)


def _check_owner_thread(connection):
    owner = getattr(connection, "_ldr_owner_thread", None)
    current = threading.get_ident()
    if owner is not None and owner != current:
        raise connection.ProgrammingError(
            "SQLite objects created in a thread can only be used in that "
            f"same thread. The object was created in thread id {owner} "
            f"and this is thread id {current}."
        )


def _owner_checked(native, connection_of):
    def method(self, *args, **kwargs):
        _check_owner_thread(connection_of(self))
        return native(self, *args, **kwargs)

    method.__name__ = native.__name__
    method.__doc__ = native.__doc__
    return method


def _same_object(connection):
    return connection


def _cursor_connection(cursor):
    return cursor.connection


@lru_cache(maxsize=8)
def _guarded_connection_type(connection_type, cursor_type, check_same_thread):
    class LifecycleConnection(connection_type):
        def __init__(self, *args, **kwargs):
            self._ldr_initialized = False
            self._ldr_owner_thread = (
                threading.get_ident() if check_same_thread else None
            )
            # The driver's close() refuses a foreign thread when its own
            # check_same_thread is on. A connection finalised on another
            # thread would then fall through to the native deallocator,
            # which closes it with no guard held. Open without the native
            # check so __del__ can always close under the guard; the
            # caller's requested check is enforced by this wrapper instead.
            if len(args) > 4:
                args = (*args[:4], False, *args[5:])
            else:
                kwargs["check_same_thread"] = False
            with _lifecycle_lock:
                super().__init__(*args, **kwargs)
                self._ldr_initialized = True

        def close(self):
            _check_owner_thread(self)
            return self._ldr_close()

        def _ldr_close(self):
            with _lifecycle_lock:
                return connection_type.close(self)

        def __del__(self):
            # The native deallocator also closes an abandoned connection.
            # Close it under the same guard first, from whichever thread
            # finalises it; the native close has no thread check here.
            # A failed constructor has no complete statement/blob lists, so
            # calling the driver's close() on it is unsafe.
            if getattr(self, "_ldr_initialized", False):
                try:
                    self._ldr_close()
                except Exception:  # allow: silent-exception
                    pass  # Finalization must not raise during interpreter exit.

    if check_same_thread:

        class ThreadCheckedCursor(cursor_type):
            pass

        for name in _CURSOR_THREAD_CHECKED:
            if hasattr(cursor_type, name):
                # bearer:disable python_lang_code_injection
                # ``name`` only ever comes from the hardcoded
                # _CURSOR_THREAD_CHECKED tuple above, never from input.
                setattr(
                    ThreadCheckedCursor,
                    name,
                    _owner_checked(
                        getattr(cursor_type, name), _cursor_connection
                    ),
                )
        for name in _CONNECTION_THREAD_CHECKED:
            if hasattr(connection_type, name):
                # bearer:disable python_lang_code_injection
                # ``name`` only ever comes from the hardcoded
                # _CONNECTION_THREAD_CHECKED tuple above, never from input.
                setattr(
                    LifecycleConnection,
                    name,
                    _owner_checked(
                        getattr(connection_type, name), _same_object
                    ),
                )

        def cursor(self, *args, **kwargs):
            _check_owner_thread(self)
            if not args and "factory" not in kwargs:
                kwargs["factory"] = ThreadCheckedCursor
            return connection_type.cursor(self, *args, **kwargs)

        LifecycleConnection.cursor = cursor

        # The only property setter the driver thread-checks: setting
        # isolation_level to None commits through the native commit, which
        # bypasses the wrapped commit() above. Other values and the getter
        # stay unchecked, as in the driver.
        native_isolation_level = connection_type.isolation_level

        def set_isolation_level(self, value):
            if value is None:
                _check_owner_thread(self)
            native_isolation_level.__set__(self, value)

        LifecycleConnection.isolation_level = property(
            native_isolation_level.__get__,
            set_isolation_level,
            native_isolation_level.__delete__,
            native_isolation_level.__doc__,
        )

    return LifecycleConnection


def wal_lifecycle_guard():
    """Return the lock that serializes the affected native WAL transitions.

    Hold it around statements that close a WAL inside SQLite's pager, such
    as ``PRAGMA journal_mode`` leaving WAL mode. Taking it is harmless on
    unaffected builds, where nothing else contends for it.
    """
    return _lifecycle_lock


def connect_sqlcipher(driver, database, **kwargs):
    """Open an application SQLCipher connection with native lifecycle safety.

    SQLite 3.51.0/3.51.1 can invert its inode and global VFS mutexes when a
    WAL connection closes while another connection opens. In sqlcipher3,
    close() also holds the GIL, so the whole interpreter can stop. Serialize
    these two native entry points for the affected POSIX builds; statements
    and transactions continue to run concurrently. SQLite fixed the mutex
    order in 3.51.2 (see the official 3.51.2 release notes). Leaving WAL
    mode closes the WAL the same way; see ``wal_lifecycle_guard``.

    A guarded connection closes under the guard even when another thread
    finalises it. To make that possible it is opened without the driver's
    own thread check. When the caller asks for ``check_same_thread`` (the
    driver default), the wrapper raises the driver's ProgrammingError for
    the connection methods the driver checks, for setting
    ``isolation_level`` to None (which commits), and for cursors from the
    default cursor factory. A blob is checked only when opened.

    Only opens and closes made through this function are serialized.
    ``ATTACH DATABASE`` opens a file and ``DETACH DATABASE`` closes it inside
    a statement, outside the guard. On the affected builds, attaching or
    detaching a file while another thread opens or closes the same file
    through this function can still deadlock; attaching a different file
    does not contend. The application attaches only its temporary backup
    file, which no other connection opens while it is attached.

    Explicit custom factories retain their own construction/cleanup behavior.
    Application connections use the default driver Connection factory.
    """
    if os.name == "posix" and getattr(driver, "sqlite_version_info", None) in (
        (3, 51, 0),
        (3, 51, 1),
    ):
        connection_type = driver.Connection
        if kwargs.get("factory", connection_type) is connection_type:
            kwargs["factory"] = _guarded_connection_type(
                connection_type,
                driver.Cursor,
                bool(kwargs.get("check_same_thread", True)),
            )
    connection = driver.connect(database, **kwargs)
    # Native SQLCipher errors are written by the C library straight to
    # stderr, bypassing Python/Loguru sinks and their redaction, and can
    # disclose account activity (e.g. a failed key) to container logs. Keep
    # them disabled; callers still receive the database exception. Older
    # versions without this PRAGMA ignore it, as SQLite does for unknown
    # PRAGMAs.
    from ..utilities.resource_utils import safe_close

    cursor = None
    try:
        cursor = connection.cursor()
        cursor.execute("PRAGMA cipher_log_level = NONE")
    except BaseException:
        safe_close(cursor, "SQLCipher privacy cursor", allow_none=True)
        safe_close(connection, "SQLCipher connection")
        raise
    else:
        safe_close(cursor, "SQLCipher privacy cursor")
    return connection


def get_sqlcipher_module():
    """
    Get the appropriate SQLCipher module for the current platform.

    Returns the sqlcipher3 module (either sqlcipher3-binary or sqlcipher3
    depending on platform and what's installed).

    Returns:
        module: The sqlcipher module with dbapi2 attribute

    Raises:
        ImportError: If sqlcipher3 is not available
    """
    try:
        import sqlcipher3

        return sqlcipher3
    except ImportError:
        raise ImportError(
            "sqlcipher3 is not installed. "
            "Ensure SQLCipher system library is installed, then run: pdm install"
        )