tina4-python 3.13.23__tar.gz → 3.13.24__tar.gz

{tina4_python-3.13.23 → tina4_python-3.13.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.23
+Version: 3.13.24
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.13.23 → tina4_python-3.13.24}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.23"
+version = "3.13.24"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.23 → tina4_python-3.13.24}/tina4_python/CLAUDE.md

@@ -1457,10 +1457,17 @@ clear_cache()                  # flush all entries and reset stats
 ### Environment variables
 
 ```bash
+TINA4_CACHE_BACKEND=memory      # memory (default) | file | redis | valkey | memcached | mongodb | database
+TINA4_CACHE_URL=                # connection for redis/valkey/memcached/mongodb, OR a SQL URL for database (falls back to TINA4_DATABASE_URL)
+TINA4_CACHE_USERNAME=           # credentials (mirrors TINA4_DATABASE_USERNAME); may also be embedded in TINA4_CACHE_URL
+TINA4_CACHE_PASSWORD=           # e.g. redis://user:pass@host, redis://:pass@host, mongodb://user:pass@host. memcached is unauthenticated
 TINA4_CACHE_TTL=60              # Default TTL in seconds (default: 60)
 TINA4_CACHE_MAX_ENTRIES=1000    # Max cached entries (default: 1000)
+TINA4_CACHE_DIR=data/cache      # Directory for the file backend (default: data/cache)
 ```
 
+The response/KV cache supports seven backends, selected by `TINA4_CACHE_BACKEND`. **Graceful fallback**: if a configured backend's driver is missing or the service/credentials are unreachable or wrong, the cache logs a warning and falls back to the **file** backend — a real persistent cache, never a silent no-op.
+
 ## DI Container — Dependency Injection
 
 Lightweight, thread-safe dependency injection container with transient and singleton registrations.
@@ -1836,13 +1843,13 @@ async def dashboard(request, response):
 ## v3 Features Summary
 
 - **55 built-in features**, zero third-party dependencies
-- **2,866 tests** passing across all modules
+- **2,899 tests** passing across all modules
 - **Production server auto-detect**: `tina4python serve --production` auto-installs uvicorn
 - **`tina4python generate`**: model, route, migration, middleware scaffolding
-- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **on by default** (`TINA4_AUTO_CACHING=true`, TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical reads within a request and flushes on writes; persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s); `cache_stats()` reports `mode` (request/persistent/off), `cache_clear()`
+- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **on by default** (`TINA4_AUTO_CACHING=true`, TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical reads within a request and flushes on writes; persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL` so instances share one cache with global write-invalidation; `cache_stats()` reports `mode` (request/persistent/off) and `backend`, `cache_clear()`
 - **Sessions**: 4 backends (file, Redis/Valkey, MongoDB, database)
 - **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
-- **Cache**: memory/Redis/file backends
+- **Cache**: unified backend set — memory (default), file, redis, valkey, memcached, mongodb, database — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable
 - **Messenger**: .env driven SMTP/IMAP
 - **ORM relationships**: `has_many`, `has_one`, `belongs_to` with eager loading (`include=`)
 - **Frond pre-compilation**: 2.8x template render improvement, `Frond.clear_cache()`

{tina4_python-3.13.23 → tina4_python-3.13.24}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.13.23"
+__version__ = "3.13.24"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.13.23 → tina4_python-3.13.24}/tina4_python/cache/__init__.py

@@ -66,6 +66,12 @@ class _CacheBackend:
     def name(self) -> str:
         raise NotImplementedError
 
+    def is_available(self) -> bool:
+        """Whether this backend is actually usable (driver present + service
+        reachable). Local backends are always available; network/driver backends
+        override this so the factory can fall back to the file backend."""
+        return True
+
 
 # ── Memory backend ─────────────────────────────────────────────────
 
@@ -141,34 +147,58 @@ class _RedisBackend(_CacheBackend):
     """Redis / Valkey backend. Uses the ``redis`` package if available,
     otherwise falls back to raw RESP protocol over TCP."""
 
-    def __init__(self, url: str = "redis://localhost:6379", max_entries: int = 1000):
+    def __init__(self, url: str = "redis://localhost:6379", max_entries: int = 1000,
+                 name: str = "redis"):
         self._url = url
         self._max_entries = max_entries
+        self._name = name
         self._hits = 0
         self._misses = 0
         self._prefix = "tina4:cache:"
         self._client = None
         self._use_raw = False
 
-        # Parse URL
-        cleaned = url.replace("redis://", "")
-        parts = cleaned.split(":")
-        self._host = parts[0] or "localhost"
-        self._port = int(parts[1].split("/")[0]) if len(parts) > 1 else 6379
-        db_part = cleaned.split("/")
-        self._db = int(db_part[1]) if len(db_part) > 1 and db_part[1] else 0
+        # Parse URL: scheme://[user[:password]@]host[:port][/db]. Credentials may
+        # also be supplied via TINA4_CACHE_USERNAME / TINA4_CACHE_PASSWORD
+        # (mirrors TINA4_DATABASE_USERNAME / TINA4_DATABASE_PASSWORD).
+        from urllib.parse import urlparse, unquote
+        parsed = urlparse(url if "://" in url else "redis://" + url)
+        self._host = parsed.hostname or "localhost"
+        self._port = parsed.port or 6379
+        db_path = (parsed.path or "").lstrip("/")
+        self._db = int(db_path) if db_path.isdigit() else 0
+        self._username = (unquote(parsed.username) if parsed.username
+                          else os.environ.get("TINA4_CACHE_USERNAME", "")) or None
+        self._password = (unquote(parsed.password) if parsed.password
+                          else os.environ.get("TINA4_CACHE_PASSWORD", "")) or None
 
         # Try the redis package first
         try:
             import redis as redis_pkg
-            self._client = redis_pkg.Redis(
-                host=self._host, port=self._port, db=self._db,
-                decode_responses=True, socket_timeout=5,
-            )
+            kwargs = dict(host=self._host, port=self._port, db=self._db,
+                          decode_responses=True, socket_timeout=5)
+            if self._password:
+                kwargs["password"] = self._password
+            if self._username:
+                kwargs["username"] = self._username
+            self._client = redis_pkg.Redis(**kwargs)
             self._client.ping()
+            self._available = True
         except Exception:
             self._client = None
             self._use_raw = True
+            # No client — usable only if the server answers (and authenticates).
+            self._available = self._probe()
+
+    def _probe(self) -> bool:
+        # Real AUTH+PING handshake so wrong credentials also fall back to file.
+        try:
+            return self._resp_command("PING") == "PONG"
+        except Exception:
+            return False
+
+    def is_available(self) -> bool:
+        return self._available
 
     def _resp_command(self, *args) -> str | None:
         """Send a command using raw RESP protocol over TCP."""
@@ -181,6 +211,16 @@ class _RedisBackend(_CacheBackend):
             sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
             sock.settimeout(5)
             sock.connect((self._host, self._port))
+            if self._password:
+                if self._username:
+                    auth = (f"*3\r\n$4\r\nAUTH\r\n${len(self._username)}\r\n{self._username}\r\n"
+                            f"${len(self._password)}\r\n{self._password}\r\n")
+                else:
+                    auth = f"*2\r\n$4\r\nAUTH\r\n${len(self._password)}\r\n{self._password}\r\n"
+                sock.sendall(auth.encode())
+                if not sock.recv(1024).startswith(b"+"):
+                    sock.close()
+                    return None
             if self._db != 0:
                 select_cmd = f"*2\r\n$6\r\nSELECT\r\n${len(str(self._db))}\r\n{self._db}\r\n"
                 sock.sendall(select_cmd.encode())
@@ -280,11 +320,11 @@ class _RedisBackend(_CacheBackend):
             "hits": self._hits,
             "misses": self._misses,
             "size": size,
-            "backend": "redis",
+            "backend": self._name,
         }
 
     def name(self) -> str:
-        return "redis"
+        return self._name
 
 
 # ── File backend ───────────────────────────────────────────────────
@@ -386,6 +426,295 @@ class _FileBackend(_CacheBackend):
         return "file"
 
 
+# ── Valkey backend (Redis-protocol compatible) ─────────────────────
+
+
+class _ValkeyBackend(_RedisBackend):
+    """Valkey backend. Valkey speaks the Redis wire protocol, so it reuses the
+    Redis client / raw-RESP transport and only reports a different name."""
+
+    def __init__(self, url: str = "valkey://localhost:6379", max_entries: int = 1000):
+        super().__init__(url=url.replace("valkey://", "redis://"),
+                         max_entries=max_entries, name="valkey")
+
+
+# ── Memcached backend (zero-dependency text protocol) ──────────────
+
+
+class _MemcachedBackend(_CacheBackend):
+    """Memcached backend using the zero-dependency text protocol over TCP."""
+
+    def __init__(self, url: str = "memcached://localhost:11211", max_entries: int = 1000):
+        cleaned = url.replace("memcached://", "").replace("memcache://", "")
+        parts = cleaned.split("/")[0].split(":")
+        self._host = parts[0] or "localhost"
+        self._port = int(parts[1]) if len(parts) > 1 and parts[1] else 11211
+        self._max_entries = max_entries
+        self._prefix = "tina4:cache:"
+        self._hits = 0
+        self._misses = 0
+        self._available = self._command(b"version\r\n", b"\r\n").startswith(b"VERSION")
+
+    def is_available(self) -> bool:
+        return self._available
+
+    def _mc_key(self, key: str) -> str:
+        # Hash to a safe, bounded key (memcached keys: no spaces/control, <=250 chars)
+        return self._prefix + hashlib.sha256(key.encode()).hexdigest()
+
+    def _command(self, payload: bytes, terminator: bytes) -> bytes:
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(5)
+            sock.connect((self._host, self._port))
+            sock.sendall(payload)
+            buf = b""
+            while terminator not in buf:
+                chunk = sock.recv(4096)
+                if not chunk:
+                    break
+                buf += chunk
+            sock.close()
+            return buf
+        except Exception:
+            return b""
+
+    def get(self, key: str):
+        resp = self._command(f"get {self._mc_key(key)}\r\n".encode(), b"END\r\n")
+        if resp.startswith(b"VALUE"):
+            try:
+                header, rest = resp.split(b"\r\n", 1)
+                nbytes = int(header.split()[3])
+                self._hits += 1
+                return json.loads(rest[:nbytes].decode())
+            except Exception:
+                pass
+        self._misses += 1
+        return None
+
+    def set(self, key: str, value, ttl: int):
+        data = json.dumps(value, default=str).encode()
+        exptime = ttl if ttl > 0 else 0
+        payload = f"set {self._mc_key(key)} 0 {exptime} {len(data)}\r\n".encode() + data + b"\r\n"
+        self._command(payload, b"\r\n")
+
+    def delete(self, key: str) -> bool:
+        resp = self._command(f"delete {self._mc_key(key)}\r\n".encode(), b"\r\n")
+        return resp.startswith(b"DELETED")
+
+    def clear(self):
+        self._hits = 0
+        self._misses = 0
+        self._command(b"flush_all\r\n", b"\r\n")
+
+    def stats(self) -> dict:
+        size = 0
+        resp = self._command(b"stats\r\n", b"END\r\n")
+        for line in resp.split(b"\r\n"):
+            if line.startswith(b"STAT curr_items "):
+                try:
+                    size = int(line.split()[2])
+                except (ValueError, IndexError):
+                    pass
+        return {"hits": self._hits, "misses": self._misses, "size": size, "backend": "memcached"}
+
+    def name(self) -> str:
+        return "memcached"
+
+
+# ── MongoDB backend (TTL collection) ───────────────────────────────
+
+
+class _MongoBackend(_CacheBackend):
+    """MongoDB backend backed by a TTL collection. Requires ``pymongo``.
+
+    Reuses the same connection style as the Mongo session handler; the cache
+    lives in collection ``tina4_cache`` with a TTL index on ``expires_at``."""
+
+    def __init__(self, url: str = "mongodb://localhost:27017", max_entries: int = 1000):
+        self._max_entries = max_entries
+        self._hits = 0
+        self._misses = 0
+        self._coll = None
+        try:
+            import pymongo
+            mongo_kwargs = {"serverSelectionTimeoutMS": 5000}
+            # Credentials from env when not embedded in the URL (parity with DB layer).
+            if "@" not in url:
+                mu = os.environ.get("TINA4_CACHE_USERNAME")
+                mp = os.environ.get("TINA4_CACHE_PASSWORD")
+                if mu:
+                    mongo_kwargs["username"] = mu
+                if mp:
+                    mongo_kwargs["password"] = mp
+            client = pymongo.MongoClient(url, **mongo_kwargs)
+            try:
+                db = client.get_default_database()
+            except Exception:
+                db = None
+            if db is None:
+                db = client["tina4_cache"]
+            self._coll = db["tina4_cache"]
+            self._coll.create_index("expires_at", expireAfterSeconds=0)
+            client.admin.command("ping")
+        except Exception:
+            self._coll = None
+
+    def is_available(self) -> bool:
+        return self._coll is not None
+
+    def get(self, key: str):
+        if self._coll is None:
+            self._misses += 1
+            return None
+        try:
+            from datetime import datetime, timezone
+            doc = self._coll.find_one({"_id": key})
+            if not doc:
+                self._misses += 1
+                return None
+            exp = doc.get("expires_at")
+            if exp is not None and exp.replace(tzinfo=timezone.utc) < datetime.now(timezone.utc):
+                self._coll.delete_one({"_id": key})
+                self._misses += 1
+                return None
+            self._hits += 1
+            return json.loads(doc["value"])
+        except Exception:
+            self._misses += 1
+            return None
+
+    def set(self, key: str, value, ttl: int):
+        if self._coll is None:
+            return
+        try:
+            from datetime import datetime, timedelta, timezone
+            doc = {"_id": key, "value": json.dumps(value, default=str)}
+            if ttl > 0:
+                doc["expires_at"] = datetime.now(timezone.utc) + timedelta(seconds=ttl)
+            self._coll.replace_one({"_id": key}, doc, upsert=True)
+        except Exception:
+            pass
+
+    def delete(self, key: str) -> bool:
+        if self._coll is None:
+            return False
+        try:
+            return self._coll.delete_one({"_id": key}).deleted_count > 0
+        except Exception:
+            return False
+
+    def clear(self):
+        self._hits = 0
+        self._misses = 0
+        if self._coll is not None:
+            try:
+                self._coll.delete_many({})
+            except Exception:
+                pass
+
+    def stats(self) -> dict:
+        size = 0
+        if self._coll is not None:
+            try:
+                size = self._coll.count_documents({})
+            except Exception:
+                pass
+        return {"hits": self._hits, "misses": self._misses, "size": size, "backend": "mongodb"}
+
+    def name(self) -> str:
+        return "mongodb"
+
+
+# ── Database backend (cache table in any Tina4-supported DB) ───────
+
+
+class _DatabaseBackend(_CacheBackend):
+    """Database backend — stores entries in a ``tina4_cache`` table in any
+    Tina4-supported database. Zero extra infrastructure; reuses the Database
+    layer. Its own connection has query caching disabled to avoid recursion."""
+
+    def __init__(self, url: str | None = None, max_entries: int = 1000):
+        from tina4_python.database.connection import Database
+        self._max_entries = max_entries
+        self._hits = 0
+        self._misses = 0
+        self._db = None
+        self._available = False
+        # The database backend reads TINA4_CACHE_URL (interpreted as a SQL URL),
+        # falling back to the app's own TINA4_DATABASE_URL — cache in the DB you
+        # already run, no extra connection var needed.
+        url = (url or os.environ.get("TINA4_CACHE_URL")
+               or os.environ.get("TINA4_DATABASE_URL", "sqlite:///data/tina4.db"))
+        # The cache's own DB connection must not itself cache (no recursion).
+        prev_auto = os.environ.get("TINA4_AUTO_CACHING")
+        prev_db = os.environ.get("TINA4_DB_CACHE")
+        os.environ["TINA4_AUTO_CACHING"] = "false"
+        os.environ["TINA4_DB_CACHE"] = "false"
+        try:
+            self._db = Database(url)
+            self._db.execute(
+                "CREATE TABLE IF NOT EXISTS tina4_cache "
+                "(cache_key VARCHAR(255) PRIMARY KEY, value TEXT, expires_at DOUBLE PRECISION)"
+            )
+            self._available = True
+        except Exception:
+            self._available = False
+        finally:
+            for k, v in (("TINA4_AUTO_CACHING", prev_auto), ("TINA4_DB_CACHE", prev_db)):
+                if v is None:
+                    os.environ.pop(k, None)
+                else:
+                    os.environ[k] = v
+
+    def is_available(self) -> bool:
+        return self._available
+
+    def get(self, key: str):
+        row = self._db.fetch_one(
+            "SELECT value, expires_at FROM tina4_cache WHERE cache_key = ?", [key])
+        if not row:
+            self._misses += 1
+            return None
+        exp = row.get("expires_at")
+        if exp and float(exp) > 0 and time.time() > float(exp):
+            self._db.execute("DELETE FROM tina4_cache WHERE cache_key = ?", [key])
+            self._misses += 1
+            return None
+        self._hits += 1
+        try:
+            return json.loads(row["value"])
+        except (json.JSONDecodeError, TypeError):
+            return row["value"]
+
+    def set(self, key: str, value, ttl: int):
+        exp = (time.time() + ttl) if ttl > 0 else 0
+        serialized = json.dumps(value, default=str)
+        self._db.execute("DELETE FROM tina4_cache WHERE cache_key = ?", [key])
+        self._db.execute(
+            "INSERT INTO tina4_cache (cache_key, value, expires_at) VALUES (?, ?, ?)",
+            [key, serialized, exp])
+
+    def delete(self, key: str) -> bool:
+        existed = self._db.fetch_one(
+            "SELECT 1 AS x FROM tina4_cache WHERE cache_key = ?", [key]) is not None
+        self._db.execute("DELETE FROM tina4_cache WHERE cache_key = ?", [key])
+        return existed
+
+    def clear(self):
+        self._hits = 0
+        self._misses = 0
+        self._db.execute("DELETE FROM tina4_cache")
+
+    def stats(self) -> dict:
+        row = self._db.fetch_one("SELECT COUNT(*) AS c FROM tina4_cache")
+        size = int(row["c"]) if row and row.get("c") is not None else 0
+        return {"hits": self._hits, "misses": self._misses, "size": size, "backend": "database"}
+
+    def name(self) -> str:
+        return "database"
+
+
 # ── Backend factory ────────────────────────────────────────────────
 
 
@@ -395,20 +724,50 @@ def _create_backend(
     max_entries: int | None = None,
     cache_dir: str | None = None,
 ) -> _CacheBackend:
-    """Create a cache backend from explicit params or env vars."""
+    """Create a cache backend from explicit params or env vars.
+
+    Backends: memory (default), file, redis, valkey, memcached, mongodb, database.
+    """
     backend = backend or os.environ.get("TINA4_CACHE_BACKEND", "memory")
     max_entries = max_entries or int(os.environ.get("TINA4_CACHE_MAX_ENTRIES", "1000"))
 
     backend = backend.lower().strip()
     if backend == "redis":
         url = url or os.environ.get("TINA4_CACHE_URL", "redis://localhost:6379")
-        return _RedisBackend(url=url, max_entries=max_entries)
+        be = _RedisBackend(url=url, max_entries=max_entries)
+    elif backend == "valkey":
+        url = url or os.environ.get("TINA4_CACHE_URL", "valkey://localhost:6379")
+        be = _ValkeyBackend(url=url, max_entries=max_entries)
+    elif backend in ("memcached", "memcache"):
+        url = url or os.environ.get("TINA4_CACHE_URL", "memcached://localhost:11211")
+        be = _MemcachedBackend(url=url, max_entries=max_entries)
+    elif backend in ("mongodb", "mongo"):
+        url = url or os.environ.get("TINA4_CACHE_URL", "mongodb://localhost:27017")
+        be = _MongoBackend(url=url, max_entries=max_entries)
+    elif backend in ("database", "db"):
+        be = _DatabaseBackend(url=url, max_entries=max_entries)
     elif backend == "file":
         cache_dir = cache_dir or os.environ.get("TINA4_CACHE_DIR", "data/cache")
         return _FileBackend(cache_dir=cache_dir, max_entries=max_entries)
     else:
         return _MemoryBackend(max_entries=max_entries)
 
+    # Graceful degradation: if the configured backend's driver is missing or the
+    # service is unreachable, fall back to the file backend (persistent, zero-dep,
+    # always available) rather than silently degrading to a no-op cache.
+    if not be.is_available():
+        try:
+            from tina4_python.debug import Log
+            Log.warning(
+                f"Cache backend '{backend}' is unavailable "
+                f"(driver missing or service unreachable) — falling back to 'file'."
+            )
+        except Exception:
+            pass
+        cache_dir = cache_dir or os.environ.get("TINA4_CACHE_DIR", "data/cache")
+        return _FileBackend(cache_dir=cache_dir, max_entries=max_entries)
+    return be
+
 
 # ── Cache entry (for response cache) ──────────────────────────────
 

{tina4_python-3.13.23 → tina4_python-3.13.24}/tina4_python/database/connection.py

@@ -230,8 +230,40 @@ class Database:
         self._cache_hits: int = 0
         self._cache_misses: int = 0
         self._cache_lock = threading.Lock()
+        # Persistent mode uses the unified CacheBackend (memory/file/redis/valkey/
+        # mongodb/database via TINA4_DB_CACHE_BACKEND) so multiple instances can
+        # share one cache with global write-invalidation. Request-scoped mode keeps
+        # the in-process dict above (ephemeral, fastest, never serialized).
+        self._cache_backend = None
+        if self._cache_persistent:
+            try:
+                from tina4_python.cache import _create_backend
+                self._cache_backend = _create_backend(
+                    backend=os.environ.get("TINA4_DB_CACHE_BACKEND", "memory"),
+                    url=os.environ.get("TINA4_DB_CACHE_URL"),
+                )
+            except Exception:
+                self._cache_backend = None  # fall back to the in-process dict
         Database._instances.add(self)
 
+    @staticmethod
+    def _serialize_result(result) -> dict:
+        """Flatten a DatabaseResult to a JSON-friendly dict for shared backends."""
+        return {
+            "records": result.records, "count": result.count,
+            "limit": result.limit, "offset": result.offset,
+            "affected_rows": result.affected_rows, "last_id": result.last_id,
+        }
+
+    @staticmethod
+    def _deserialize_result(data: dict) -> DatabaseResult:
+        """Reconstruct a DatabaseResult from a backend-cached dict."""
+        return DatabaseResult(
+            records=data.get("records", []), count=data.get("count", 0),
+            limit=data.get("limit", 0), offset=data.get("offset", 0),
+            affected_rows=data.get("affected_rows", 0), last_id=data.get("last_id"),
+        )
+
     def _create_adapter(self) -> DatabaseAdapter:
         """Select adapter based on URL scheme."""
         parsed = urlparse(self.url)
@@ -324,6 +356,11 @@ class Database:
 
     def _cache_get(self, key: str):
         """Return cached result or None if miss/expired."""
+        # Persistent mode → shared CacheBackend (serialized DatabaseResult).
+        if self._cache_backend is not None:
+            raw = self._cache_backend.get(key)
+            return self._deserialize_result(raw) if isinstance(raw, dict) else None
+        # Request-scoped mode → in-process dict (stores the object directly).
         with self._cache_lock:
             entry = self._query_cache.get(key)
             if entry is None:
@@ -336,11 +373,17 @@ class Database:
 
     def _cache_set(self, key: str, result):
         """Store a result in the cache with TTL."""
+        if self._cache_backend is not None:
+            self._cache_backend.set(key, self._serialize_result(result), self._cache_ttl)
+            return
         with self._cache_lock:
             self._query_cache[key] = (time.monotonic() + self._cache_ttl, result)
 
     def _cache_invalidate(self):
         """Clear the entire query cache (called on writes)."""
+        if self._cache_backend is not None:
+            self._cache_backend.clear()
+            return
         with self._cache_lock:
             self._query_cache.clear()
 
@@ -370,6 +413,17 @@ class Database:
 
     def cache_stats(self) -> dict:
         """Return query cache statistics."""
+        if self._cache_backend is not None:
+            bs = self._cache_backend.stats()
+            return {
+                "enabled": True,
+                "mode": "persistent",
+                "hits": self._cache_hits,
+                "misses": self._cache_misses,
+                "size": bs.get("size", 0),
+                "ttl": self._cache_ttl,
+                "backend": bs.get("backend", self._cache_backend.name()),
+            }
         with self._cache_lock:
             return {
                 "enabled": self._cache_enabled,
@@ -379,6 +433,7 @@ class Database:
                 "misses": self._cache_misses,
                 "size": len(self._query_cache),
                 "ttl": self._cache_ttl,
+                "backend": "memory",
             }
 
     def cache_clear(self):