tradedangerous 12.0.0__tar.gz → 12.0.2__tar.gz

{tradedangerous-12.0.0/tradedangerous.egg-info → tradedangerous-12.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradedangerous
-Version: 12.0.0
+Version: 12.0.2
 Summary: Trade-Dangerous is a set of powerful trading tools for Elite Dangerous, organized around one of the most powerful trade run optimizers available.
 Home-page: https://github.com/eyeonus/Trade-Dangerous
 Author: eyeonus
@@ -11,12 +11,13 @@ Project-URL: Documentation, https://github.com/eyeonus/Trade-Dangerous/wiki
 Project-URL: Source Code, https://github.com/eyeonus/Trade-Dangerous
 Keywords: trade,elite,elite-dangerous
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
 Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests
@@ -34,6 +35,7 @@ Dynamic: license
 Dynamic: license-file
 Dynamic: project-url
 Dynamic: requires-dist
+Dynamic: requires-python
 Dynamic: summary
 
 

tradedangerous-12.0.2/setup.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+# --------------------------------------------------------------------
+# Copyright (C) Oliver 'kfsone' Smith 2014 <oliver@kfs.org>:
+# Copyright (C) Bernd 'Gazelle' Gollesch 2016, 2017
+# Copyright (C) Stefan 'Tromador' Morrell 2025
+# Copyright (C) Jonathan 'eyeonus' Jones 2018 - 2025
+#
+# You are free to use, redistribute, or even print and eat a copy of
+# this software so long as you include this copyright notice.
+# I guarantee there is at least one bug neither of us knew about.
+# --------------------------------------------------------------------
+"""Setup for trade-dangerous"""
+import sys
+from setuptools import setup, find_packages
+
+try:
+    from semantic_release import setup_hook
+    setup_hook(sys.argv)
+except ImportError:
+    pass
+
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
+package = "tradedangerous"
+
+exec(open("tradedangerous/version.py").read())  # pylint: disable=W0122
+
+setup(
+    name=package,
+    version=__version__,  # pylint: disable=E0602
+    install_requires=["requests", "appJar", "ijson", "rich"],
+    setup_requires=["pytest-runner"],
+    tests_require=["pytest"],
+    packages=[
+        ".",
+        "tradedangerous",
+        "tradedangerous.commands",
+        "tradedangerous.mfd",
+        "tradedangerous.mfd.saitek",
+        "tradedangerous.misc",
+        "tradedangerous.plugins",
+        "tradedangerous.db",
+    ],
+    url="https://github.com/eyeonus/Trade-Dangerous",
+    project_urls={
+        "Bug Tracker": "https://github.com/eyeonus/Trade-Dangerous/issues",
+        "Documentation": "https://github.com/eyeonus/Trade-Dangerous/wiki",
+        "Source Code": "https://github.com/eyeonus/Trade-Dangerous",
+    },
+    author="eyeonus",
+    author_email="eyeonus@gmail.com",
+    description=(
+        "Trade-Dangerous is a set of powerful trading tools for Elite Dangerous, "
+        "organized around one of the most powerful trade run optimizers available."
+    ),
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    keywords=["trade", "elite", "elite-dangerous"],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
+        "Operating System :: OS Independent",
+    ],
+    license="MPL",
+    python_requires=">=3.10",
+    test_suite="tests",
+    package_data={
+        "tradedangerous": [
+            "templates/TradeDangerous.sql",
+            "templates/Added.csv",
+            "templates/Category.csv",
+            "templates/RareItem.csv",
+            "templates/database_changes.json",
+        ]
+    },
+    entry_points={
+        "console_scripts": [
+            "trade=trade:main",
+            "tradegui=tradegui:main",
+        ]
+    },
+    zip_safe=False,
+)

tradedangerous-12.0.2/tradedangerous/db/__init__.py

@@ -0,0 +1,27 @@
+"""TradeDangerous SQLAlchemy bootstrap package (Stage 3A, Part 1).
+
+Side-effect free on import. Provides a minimal, cross-platform API
+for config loading, path resolution, and engine/session bootstrap.
+
+Usage:
+    from tradedangerous.db import (
+        load_config, resolve_data_dir, resolve_tmp_dir, ensure_dir, resolve_db_config_path,
+        make_engine_from_config, get_session_factory, healthcheck,
+    )
+"""
+from .config import load_config
+from .paths import resolve_data_dir, resolve_tmp_dir, ensure_dir, resolve_db_config_path
+from .engine import make_engine_from_config, get_session_factory, healthcheck
+from .lifecycle import ensure_fresh_db
+
+__all__ = [
+    "load_config",
+    "resolve_data_dir",
+    "resolve_tmp_dir",
+    "ensure_dir",
+    "resolve_db_config_path",
+    "make_engine_from_config",
+    "get_session_factory",
+    "healthcheck",
+    "ensure_fresh_db",
+]

tradedangerous-12.0.2/tradedangerous/db/adapter.py

@@ -0,0 +1,191 @@
+# tradedangerous/db/adapter.py
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Dict, Generator, Iterable, Optional, Tuple
+
+from sqlalchemy import select, func
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session
+
+# Local engine + ORM (authoritative)
+from .engine import make_engine_from_config, get_session_factory  # uses env/CWD-resolved db_config.ini by default
+from .orm_models import System, Station, Item, StationItem  # canonical models
+from .paths import resolve_db_config_path
+
+# ---- Public factory ---------------------------------------------------------
+
+def get_adapter_if_enabled(cfg_path: Optional[str] = None) -> "TradeDBReadAdapter | None":
+    """
+    Return an adapter when [database] backend != 'sqlite', else None.
+    - No engine/session created at import: construction is lazy.
+    - This is called by tradedb.py (thin gate).
+    """
+    import configparser, os
+    if cfg_path is None:
+        cfg_path = str(resolve_db_config_path())
+    cfg = configparser.ConfigParser()
+    if not os.path.exists(cfg_path):
+        return None
+    with open(cfg_path, "r", encoding="utf-8") as fh:
+        cfg.read_file(fh)
+    backend = (cfg.get("database", "backend", fallback="sqlite") or "sqlite").strip().lower()
+    if backend == "sqlite":
+        return None
+
+    # Engine is created lazily via the property below to honour "no side-effects at import".
+    return TradeDBReadAdapter(cfg_path)
+
+# ---- Adapter (read-only) ----------------------------------------------------
+
+class TradeDBReadAdapter:
+    """
+    Very small, read-only façade over SQLAlchemy for legacy TradeDB reads:
+      - systems() list
+      - lookup system by name (case-insensitive)
+      - station by (system_id, station_name) (case-insensitive)
+      - average selling/buying prices (used by trade_cmd at detail>1)
+    """
+    def __init__(self, cfg_path: str):
+        self._cfg_path = cfg_path
+        self._engine: Optional[Engine] = None
+        self._Session = None  # sessionmaker
+
+    # Lazy engine/session factory (no import-time work)
+    @property
+    def Session(self):
+        if self._Session is None:
+            engine = make_engine_from_config(self._cfg_path)
+            self._engine = engine
+            self._Session = get_session_factory(engine)
+        return self._Session
+
+    @contextmanager
+    def session(self) -> Generator[Session, None, None]:
+        Session = self.Session
+        with Session() as s:
+            yield s
+
+    # ---- Reads mapped to ORM ------------------------------------------------
+
+    def list_system_rows(self) -> Iterable[Tuple[int, str, float, float, float, Optional[int]]]:
+        """
+        Shape matches legacy _loadSystems SELECT:
+        (system_id, name, pos_x, pos_y, pos_z, added_id)
+        """
+        with self.session() as s:
+            rows = s.execute(
+                select(
+                    System.system_id,
+                    System.name,
+                    System.pos_x,
+                    System.pos_y,
+                    System.pos_z,
+                    System.added_id,
+                )
+            )
+            for r in rows:
+                yield (r.system_id, r.name, r.pos_x, r.pos_y, r.pos_z, r.added_id)
+
+    def system_by_name(self, name_ci: str) -> Optional[Tuple[int, str, float, float, float, Optional[int]]]:
+        """
+        Case-insensitive name match for System.
+        """
+        with self.session() as s:
+            row = s.execute(
+                select(
+                    System.system_id, System.name, System.pos_x, System.pos_y, System.pos_z, System.added_id
+                ).where(func.upper(System.name) == func.upper(func.trim(func.cast(name_ci, System.name.type))))
+            ).first()
+            if not row:
+                return None
+            return (row.system_id, row.name, row.pos_x, row.pos_y, row.pos_z, row.added_id)
+
+    def station_by_system_and_name(
+        self, system_id: int, station_name_ci: str
+    ) -> Optional[Tuple[int, int, str, int, str, str, str, str, str, str, str, str, str, int]]:
+        """
+        Return the single Station row by system + name (CI).
+        Shape matches legacy _loadStations row consumed by Station(...):
+          (station_id, system_id, name,
+           ls_from_star, market, blackmarket, shipyard,
+           max_pad_size, outfitting, rearm, refuel, repair, planetary, type_id)
+        """
+        with self.session() as s:
+            r = s.execute(
+                select(
+                    Station.station_id,
+                    Station.system_id,
+                    Station.name,
+                    Station.ls_from_star,
+                    Station.market,
+                    Station.blackmarket,
+                    Station.shipyard,
+                    Station.max_pad_size,
+                    Station.outfitting,
+                    Station.rearm,
+                    Station.refuel,
+                    Station.repair,
+                    Station.planetary,
+                    Station.type_id,
+                ).where(
+                    Station.system_id == system_id,
+                    func.upper(Station.name) == func.upper(func.trim(func.cast(station_name_ci, Station.name.type))),
+                )
+            ).first()
+            if not r:
+                return None
+            return (
+                r.station_id,
+                r.system_id,
+                r.name,
+                r.ls_from_star,
+                r.market,
+                r.blackmarket,
+                r.shipyard,
+                r.max_pad_size,
+                r.outfitting,
+                r.rearm,
+                r.refuel,
+                r.repair,
+                r.planetary,
+                r.type_id,
+            )
+
+    def average_selling(self) -> Dict[int, int]:
+        """
+        {item_id: avg_supply_price>0}
+        Mirrors the legacy SQL used in TradeDB.getAverageSelling.
+        """
+        with self.session() as s:
+            rows = s.execute(
+                select(
+                    Item.item_id,
+                    func.IFNULL(func.avg(StationItem.supply_price), 0),
+                )
+                .select_from(Item.__table__.outerjoin(
+                    StationItem, (Item.item_id == StationItem.item_id) & (StationItem.supply_price > 0)
+                ))
+                .where(StationItem.supply_price > 0)
+                .group_by(Item.item_id)
+            )
+            return {int(item_id): int(avg_cr) for (item_id, avg_cr) in rows}
+
+    def average_buying(self) -> Dict[int, int]:
+        """
+        {item_id: avg_demand_price>0}
+        Mirrors the legacy SQL used in TradeDB.getAverageBuying.
+        """
+        with self.session() as s:
+            rows = s.execute(
+                select(
+                    Item.item_id,
+                    func.IFNULL(func.avg(StationItem.demand_price), 0),
+                )
+                .select_from(Item.__table__.outerjoin(
+                    StationItem, (Item.item_id == StationItem.item_id) & (StationItem.demand_price > 0)
+                ))
+                .where(StationItem.demand_price > 0)
+                .group_by(Item.item_id)
+            )
+            return {int(item_id): int(avg_cr) for (item_id, avg_cr) in rows}

tradedangerous-12.0.2/tradedangerous/db/config.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+import configparser
+from pathlib import Path
+from typing import Any, Dict
+
+DEFAULTS: Dict[str, Dict[str, Any]] = {
+    "database": {"backend": "sqlite"},
+    "mariadb": {
+        "host": "127.0.0.1",
+        "port": 3306,
+        "user": "",
+        "password": "",
+        "name": "tradedangerous",
+        "driver": "mariadbconnector",  # or 'pymysql'
+        "charset": "utf8mb4",
+    },
+    "sqlite": {"sqlite_filename": "TradeDangerous.db"},
+    "paths": {"data_dir": "./data", "tmp_dir": "./tmp"},
+    "engine": {
+        "pool_size": 10,
+        "max_overflow": 20,
+        "pool_timeout": 30,
+        "pool_recycle": 1800,
+        "isolation_level": "READ COMMITTED",
+        "echo": False,
+        "connect_timeout": 10,
+    },
+}
+# --- Runtime default path correction ----------------------------------------
+# Convert relative defaults ("./data", "./tmp") into absolute paths under the
+# current working directory. This prevents first-run installs from resolving
+# relative to the package install directory or venv when no db_config.ini exists.
+try:
+    _cwd = Path.cwd()
+    DEFAULTS["paths"]["data_dir"] = str((_cwd / "data").resolve())
+    DEFAULTS["paths"]["tmp_dir"]  = str((_cwd / "tmp").resolve())
+except Exception:
+    # Best effort; fall back to shipped defaults if CWD is inaccessible
+    pass
+# ---------------------------------------------------------------------------
+
+# Hardened parser: allow inline comments and disable interpolation
+CFG_KW = dict(inline_comment_prefixes=(";", "#"), interpolation=None)
+
+def _parse_bool(s: str) -> bool:
+    return str(s).strip().lower() in {"1", "true", "yes", "on"}
+
+def _as_int(s: str, default: int | None = None) -> int | None:
+    try:
+        return int(str(s).strip())
+    except (TypeError, ValueError):
+        return default
+
+def _coerce_types(d: Dict[str, Any]) -> Dict[str, Any]:
+    eng = d.get("engine", {})
+    if "echo" in eng:
+        eng["echo"] = _parse_bool(eng["echo"]) if isinstance(eng["echo"], str) else bool(eng["echo"])
+    for k in ("pool_size", "max_overflow", "pool_timeout", "pool_recycle", "connect_timeout"):
+        if k in eng:
+            eng[k] = _as_int(eng[k], DEFAULTS["engine"][k])
+    if "mariadb" in d and "port" in d["mariadb"]:
+        d["mariadb"]["port"] = _as_int(d["mariadb"]["port"], DEFAULTS["mariadb"]["port"])
+    return d
+
+def load_config(path: str | Path | None = None) -> Dict[str, Any]:
+    """Load configuration as a dict with typed values.
+    Search order:
+      1) explicit *path* if provided
+      2) TD_DB_CONFIG env (if file exists)
+      3) ./db_config.ini (cwd)
+      4) in-code DEFAULTS
+    """
+    cfg_path: Path | None = None
+    if path is not None:
+        p = Path(path)
+        if p.exists():
+            cfg_path = p
+    else:
+        # Prefer environment variable if it points to an existing file
+        try:
+            from .paths import resolve_db_config_path
+            env_candidate = resolve_db_config_path()
+            if env_candidate.exists():
+                cfg_path = env_candidate
+        except Exception:
+            # If anything goes wrong resolving the env, fall back to defaults below
+            pass
+
+        # Fall back to local file in CWD
+        if cfg_path is None:
+            p = Path.cwd() / "db_config.ini"
+            if p.exists():
+                cfg_path = p
+
+    # start with defaults
+    result: Dict[str, Any] = {k: (v.copy() if isinstance(v, dict) else v) for k, v in DEFAULTS.items()}
+
+    if cfg_path:
+        parser = configparser.ConfigParser(**CFG_KW)
+        with cfg_path.open("r", encoding="utf-8") as fh:
+            parser.read_file(fh)
+        for section in parser.sections():
+            result.setdefault(section, {})
+            for key, val in parser.items(section):
+                result[section][key] = val
+
+    return _coerce_types(result)

tradedangerous-12.0.2/tradedangerous/db/engine.py

@@ -0,0 +1,246 @@
+# tradedangerous/db/engine.py
+from __future__ import annotations
+import os, time
+from pathlib import Path
+from typing import Any, Dict, Mapping
+import configparser
+
+from sqlalchemy import create_engine, event, text
+from sqlalchemy.engine import Engine, URL
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import NullPool
+from sqlalchemy.exc import OperationalError
+
+from .paths import resolve_data_dir, resolve_tmp_dir, resolve_db_config_path
+
+# ---------- config normalization & helpers ----------
+
+def _ensure_default_config_file(target_path: Path | None) -> Path | None:
+    """
+    If *target_path* is provided and no file exists there, write a minimal db_config.ini
+    built from in-code DEFAULTS. Returns the path if created, else None.
+    """
+    if not target_path:
+        return None
+    if target_path.exists():
+        return target_path
+    # Build from DEFAULTS
+    from .config import DEFAULTS  # typed defaults live here
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    cp = configparser.ConfigParser()
+    for section, mapping in DEFAULTS.items():
+        cp[section] = {}
+        if isinstance(mapping, Mapping):
+            for k, v in mapping.items():
+                cp[section][k] = str(v)
+    with target_path.open("w", encoding="utf-8") as fh:
+        cp.write(fh)
+    return target_path
+
+
+def _cfg_to_dict(cfg: configparser.ConfigParser | Mapping[str, Any] | str | os.PathLike) -> Dict[str, Dict[str, Any]]:
+    """
+    Normalise configuration input into a dict-of-sections.
+
+    Accepted inputs:
+      * dict-like mapping → returned as {section: {key: value}}
+      * ConfigParser       → converted to nested dict (sections overlay DEFAULT section)
+      * str/Path           → if file exists, read it; if missing, fall back to load_config()
+
+    NOTE:
+    - We do NOT raise on a missing path; we delegate to load_config() to honour the
+      documented resolution order (ENV → CWD → DEFAULTS).
+    """
+    if isinstance(cfg, (str, os.PathLike)):
+        p = Path(cfg)
+        if p.exists():
+            cp = configparser.ConfigParser()
+            with p.open("r", encoding="utf-8") as fh:
+                cp.read_file(fh)
+            return _cfg_to_dict(cp)
+        # Missing provided path → use canonical loader with fallbacks
+        from .config import load_config
+        return load_config(None)
+
+    if isinstance(cfg, configparser.ConfigParser):
+        out: Dict[str, Dict[str, Any]] = {}
+        defaults = dict(cfg.defaults())
+        for sec in cfg.sections():
+            d = dict(defaults)
+            d.update({k: v for k, v in cfg.items(sec)})
+            out[sec] = d
+        for sec in ("database", "engine", "sqlite", "mariadb", "paths"):
+            out.setdefault(sec, dict(defaults))
+        return out
+
+    # Already a dict-like mapping of sections
+    return {k: dict(v) if isinstance(v, Mapping) else dict() for k, v in cfg.items()}  # type: ignore[arg-type]
+
+
+def _get(cfg: Dict[str, Any], section: str, key: str, default=None):
+    if section in cfg and key in cfg[section]:
+        return cfg[section][key]
+    if "database" in cfg and key in cfg["database"]:
+        return cfg["database"][key]
+    return default
+
+def _get_int(cfg: Dict[str, Any], section: str, key: str, default=None):
+    try:
+        return int(_get(cfg, section, key, default))
+    except (TypeError, ValueError):
+        return default
+
+def _get_bool(cfg: Dict[str, Any], section: str, key: str, default=None):
+    v = _get(cfg, section, key, default)
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, str):
+        return v.strip().lower() in {"1", "true", "yes", "on"}
+    return default
+
+# ---------- URL builders ----------
+
+def _redact(url: str) -> str:
+    if "://" not in url:
+        return url
+    head, rest = url.split("://", 1)
+    if "@" in rest and ":" in rest.split("@", 1)[0]:
+        user_pass, host = rest.split("@", 1)
+        user = user_pass.split(":", 1)[0]
+        return f"{head}://{user}:***@{host}"
+    return f"{head}://{rest}"
+
+def _make_mariadb_url(cfg: Dict[str, Any]) -> URL:
+    driver = str(_get(cfg, "mariadb", "driver", "mariadbconnector")).strip().lower()
+    drivername = "mariadb+" + driver if driver == "mariadbconnector" else "mysql+" + driver
+    return URL.create(
+        drivername=drivername,
+        username=str(_get(cfg, "mariadb", "user", "")),
+        password=str(_get(cfg, "mariadb", "password", "")),
+        host=str(_get(cfg, "mariadb", "host", "127.0.0.1")),
+        port=int(_get(cfg, "mariadb", "port", 3306)),
+        database=str(_get(cfg, "mariadb", "name", "tradedangerous")),
+        query={"charset": str(_get(cfg, "mariadb", "charset", "utf8mb4"))},
+    )
+
+def _make_sqlite_url(cfg: Dict[str, Any]) -> str:
+    data_dir = resolve_data_dir(cfg)
+    # Honour legacy filename
+    filename = str(_get(cfg, "sqlite", "sqlite_filename", "TradeDangerous.db"))
+    db_path = (data_dir / filename).resolve()
+    return f"sqlite+pysqlite:///{db_path.as_posix()}"
+
+# ---------- Engine construction ----------
+
+def make_engine_from_config(cfg_or_path: configparser.ConfigParser | Mapping[str, Any] | str | os.PathLike | None = None) -> Engine:
+    """
+    Build a SQLAlchemy Engine for either MariaDB or SQLite.
+
+    Accepts: ConfigParser, dict-like {section:{k:v}}, path to INI file, or None.
+    First-run behaviour:
+      - If a path is provided but missing, or if no path is provided and no config is found,
+        a default db_config.ini is CREATED in the resolved default location (CWD unless TD_DB_CONFIG
+        points elsewhere), then loaded.
+    """
+    ini_target: Path | None = None
+
+    # If caller gave a specific path, prefer to materialise a default file there.
+    if isinstance(cfg_or_path, (str, os.PathLike)):
+        ini_target = Path(cfg_or_path)
+        _ensure_default_config_file(ini_target)
+    else:
+        # No specific path: create (if missing) at the standard location
+        # (CWD/db_config.ini by default, or the file pointed to by TD_DB_CONFIG).
+        ini_target = resolve_db_config_path("db_config.ini")
+        _ensure_default_config_file(ini_target)
+
+    cfg = _cfg_to_dict(cfg_or_path if cfg_or_path is not None else str(ini_target))
+
+    # Ensure dirs exist (used by various parts of the app)
+    _ = resolve_data_dir(cfg)
+    _ = resolve_tmp_dir(cfg)
+
+    backend = str(_get(cfg, "database", "backend", "sqlite")).strip().lower()
+    echo = bool(_get_bool(cfg, "engine", "echo", False))
+    isolation = _get(cfg, "engine", "isolation_level", None)
+
+    if backend == "mariadb":
+        url = _make_mariadb_url(cfg)
+        connect_timeout = _get_int(cfg, "engine", "connect_timeout", 10) or 10
+        pool_size    = _get_int(cfg, "engine", "pool_size", 10) or 10
+        max_overflow = _get_int(cfg, "engine", "max_overflow", 20) or 20
+        pool_timeout = _get_int(cfg, "engine", "pool_timeout", 30) or 30
+        pool_recycle = _get_int(cfg, "engine", "pool_recycle", 1800) or 1800
+        engine = create_engine(
+            url,
+            echo=echo,
+            pool_pre_ping=True,
+            pool_size=pool_size,
+            max_overflow=max_overflow,
+            pool_timeout=pool_timeout,
+            pool_recycle=pool_recycle,
+            isolation_level=isolation or "READ COMMITTED",
+            connect_args={"connect_timeout": connect_timeout},
+        )
+    elif backend == "sqlite":
+        url = _make_sqlite_url(cfg)
+        engine = create_engine(
+            url,
+            echo=echo,
+            poolclass=NullPool,
+            connect_args={"check_same_thread": False},
+        )
+
+        @event.listens_for(engine, "connect")
+        def _set_sqlite_pragmas(dbapi_conn, _):
+            cur = dbapi_conn.cursor()
+            cur.execute("PRAGMA foreign_keys=ON")
+            cur.execute("PRAGMA synchronous=OFF")
+            cur.execute("PRAGMA temp_store=MEMORY")
+            cur.execute("PRAGMA auto_vacuum=INCREMENTAL")
+            cur.close()
+    else:
+        raise ValueError(f"Unsupported backend: {backend}")
+
+    try:
+        engine._td_redacted_url = _redact(str(url))  # type: ignore[attr-defined]
+    except Exception:
+        pass
+    return engine
+# ---------- Session factory ----------
+
+def get_session_factory(engine: Engine):
+    return sessionmaker(bind=engine, expire_on_commit=False, autoflush=True)
+
+# ---------- Health helpers ----------
+
+def healthcheck(engine: Engine, retries: int = 0) -> bool:
+    attempt = 0
+    delay = 0.25
+    while True:
+        try:
+            with engine.connect() as conn:
+                conn.execute(text("SELECT 1"))
+            return True
+        except OperationalError:
+            attempt += 1
+            if attempt > retries:
+                return False
+            time.sleep(delay)
+            delay *= 2
+
+def read_sqlite_pragmas(engine: Engine) -> Dict[str, Any]:
+    """
+    Return active PRAGMA values (SQLite only). Safe no-op for non-sqlite engines.
+    """
+    out: Dict[str, Any] = {}
+    with engine.connect() as conn:
+        if conn.dialect.name != "sqlite":
+            return out
+        def one(q: str) -> Any:
+            return conn.execute(text(q)).scalar()
+        out["foreign_keys"] = one("PRAGMA foreign_keys")
+        out["synchronous"]  = one("PRAGMA synchronous")
+        out["temp_store"]   = one("PRAGMA temp_store")
+        out["auto_vacuum"]  = one("PRAGMA auto_vacuum")
+    return out