pz-cli 5.0.0__py3-none-any.whl

pz_foundation/db/database.py

@@ -0,0 +1,1291 @@
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass, field
+import importlib
+import json
+import os
+from os import PathLike
+from pathlib import Path
+import re
+import sqlite3
+from threading import RLock
+from typing import Any, Protocol
+from urllib.parse import parse_qs, quote, unquote, urlencode, urlparse
+
+import pz_settings_center.public as settings_center
+from pz_core.assembly.project import resolve_project_context
+
+from .lifecycle_status import DBConnectionLifecycleStatus, connection_lifecycle_status
+from .tortoise_manager import tortoise_manager
+
+
+@dataclass(frozen=True, slots=True)
+class FoundationDatabaseSettings:
+    enabled: bool = False
+    driver: str = "sqlite"
+    path: str = ""
+    urls: tuple[str, ...] = ()
+    host: str = ""
+    port: int = 0
+    hosts: tuple[str, ...] = ()
+    ports: tuple[int, ...] = ()
+    user: str = ""
+    password: str = ""
+    database: str = ""
+    min_size: int = 1
+    max_size: int = 10
+    connect_timeout: float = 5.0
+    pool_acquire_timeout: float = 5.0
+    statement_timeout_ms: int = 30000
+    idle_in_transaction_session_timeout_ms: int = 30000
+    pool_max_lifetime: float = 3600.0
+    pool_max_idle: float = 600.0
+    reconnect_timeout: float = 30.0
+    health_check_interval: float = 60.0
+    ssl_mode: str = ""
+    ssl_root_cert: str = ""
+    ssl_cert: str = ""
+    ssl_key: str = ""
+    ssl_password: str = ""
+    target_session_attrs: str = ""
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+class FoundationDatabase(Protocol):
+    settings: FoundationDatabaseSettings
+    driver: str
+
+    def create_session(self): ...
+
+    def readiness_probe(self): ...
+
+    def executescript(self, script: str) -> None: ...
+
+    def close(self) -> None: ...
+
+
+def _resolved_settings(*, project_dir: str | PathLike[str] | None = None):
+    if project_dir is None:
+        return settings_center.settings
+    return settings_center.resolve_settings(project_dir=str(Path(project_dir).resolve()))
+
+
+def _project_settings(*, project_dir: str | PathLike[str] | None = None):
+    try:
+        return _resolved_settings(project_dir=project_dir).project
+    except Exception:
+        return None
+
+
+def _foundation_settings_section(
+    name: str,
+    *,
+    project_dir: str | PathLike[str] | None = None,
+):
+    section_name = str(name or "").strip()
+    try:
+        resolved = _resolved_settings(project_dir=project_dir)
+        if hasattr(resolved, "app_settings"):
+            foundation_payload = resolved.app_settings("pz_foundation")
+            if isinstance(foundation_payload, dict):
+                section = foundation_payload.get(section_name, {})
+                if section not in (None, {}):
+                    return section
+        foundation_settings = getattr(resolved, "pz_foundation", None)
+        if isinstance(foundation_settings, dict):
+            return foundation_settings.get(section_name, {})
+        if foundation_settings is None:
+            return {}
+        return getattr(foundation_settings, section_name, {})
+    except Exception:
+        return {}
+
+
+@dataclass(slots=True)
+class SQLiteFoundationSession:
+    connection: Any
+    driver: str = "sqlite"
+    _transaction_active: bool = False
+    _lock: RLock | None = None
+
+    def begin(self) -> SQLiteFoundationTransaction:
+        if self._transaction_active:
+            raise RuntimeError("nested foundation transactions are not supported")
+        if self._lock is not None:
+            self._lock.acquire()
+        try:
+            executor = getattr(self.connection, "execute", None)
+            if callable(executor):
+                executor("BEGIN")
+            else:
+                self.connection.cursor().execute("BEGIN")
+            self._transaction_active = True
+        except Exception:
+            if self._lock is not None:
+                self._lock.release()
+            raise
+        return SQLiteFoundationTransaction(self, self.connection, lock=self._lock)
+
+    def execute(self, statement: str, *args: Any, **kwargs: Any) -> Any:
+        acquired_lock = False
+        if not self._transaction_active and self._lock is not None:
+            self._lock.acquire()
+            acquired_lock = True
+        try:
+            cursor = self.connection.cursor()
+            sql, params = _prepare_statement(self.driver, statement, args, kwargs)
+            if params is not None:
+                cursor.execute(sql, params)
+            else:
+                cursor.execute(sql)
+            description = getattr(cursor, "description", None)
+            if description:
+                rows = cursor.fetchall()
+                if rows and isinstance(rows[0], sqlite3.Row):
+                    if not self._transaction_active:
+                        self.connection.commit()
+                    return rows
+                if not self._transaction_active:
+                    self.connection.commit()
+                return [_coerce_dbapi_row(description, row) for row in rows]
+            if not self._transaction_active:
+                self.connection.commit()
+            return int(getattr(cursor, "rowcount", 0) or 0)
+        except Exception:
+            if not self._transaction_active:
+                with contextlib.suppress(Exception):
+                    self.connection.rollback()
+            raise
+        finally:
+            if acquired_lock and self._lock is not None:
+                self._lock.release()
+
+
+@dataclass(slots=True)
+class SQLiteFoundationTransaction:
+    session: SQLiteFoundationSession
+    connection: Any
+    lock: RLock | None = None
+    _active: bool = True
+
+    def commit(self) -> None:
+        if not self._active:
+            return
+        self.connection.commit()
+        self._active = False
+        self.session._transaction_active = False
+        if self.lock is not None:
+            self.lock.release()
+
+    def rollback(self) -> None:
+        if not self._active:
+            return
+        self.connection.rollback()
+        self._active = False
+        self.session._transaction_active = False
+        if self.lock is not None:
+            self.lock.release()
+
+
+@dataclass(slots=True)
+class FoundationDBAPINonTransactionalReadinessProbe:
+    connection: Any
+
+    def check_ready(self) -> bool:
+        try:
+            executor = getattr(self.connection, "execute", None)
+            if callable(executor):
+                executor("SELECT 1")
+            else:
+                self.connection.cursor().execute("SELECT 1")
+        except Exception:
+            return False
+        return True
+
+
+SQLiteFoundationReadinessProbe = FoundationDBAPINonTransactionalReadinessProbe
+
+
+@dataclass(slots=True)
+class SQLiteFoundationDatabase:
+    settings: FoundationDatabaseSettings
+    _connection: Any = field(init=False, repr=False)
+    _lock: RLock = field(default_factory=RLock, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if not self.settings.enabled:
+            raise RuntimeError("foundation database is disabled")
+        driver = _normalize_driver(self.settings.driver, url=_primary_database_url(self.settings))
+        if driver != "sqlite":
+            raise RuntimeError(f"unsupported foundation database driver: {self.settings.driver!r}")
+        db_path = Path(self.settings.path).expanduser()
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._connection = sqlite3.connect(db_path, check_same_thread=False)
+        self._connection.row_factory = sqlite3.Row
+
+    @property
+    def driver(self) -> str:
+        return "sqlite"
+
+    def create_session(self) -> SQLiteFoundationSession:
+        return SQLiteFoundationSession(self._connection, driver="sqlite", _lock=self._lock)
+
+    def readiness_probe(self) -> FoundationDBAPINonTransactionalReadinessProbe:
+        return FoundationDBAPINonTransactionalReadinessProbe(self._connection)
+
+    def executescript(self, script: str) -> None:
+        self._connection.executescript(script)
+        self._connection.commit()
+
+    def close(self) -> None:
+        with contextlib.suppress(Exception):
+            self._connection.close()
+
+
+@dataclass(slots=True)
+class _DBAPIFoundationDatabase:
+    settings: FoundationDatabaseSettings
+    _connection: Any = field(init=False, repr=False)
+    _lock: RLock = field(default_factory=RLock, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if not self.settings.enabled:
+            raise RuntimeError("foundation database is disabled")
+        self._connection = self._open_connection()
+
+    @property
+    def driver(self) -> str:
+        return _normalize_driver(self.settings.driver, url=_primary_database_url(self.settings))
+
+    def create_session(self) -> SQLiteFoundationSession:
+        return SQLiteFoundationSession(
+            self._connection,
+            driver=_normalize_driver(self.settings.driver, url=_primary_database_url(self.settings)),
+            _lock=self._lock,
+        )
+
+    def readiness_probe(self) -> FoundationDBAPINonTransactionalReadinessProbe:
+        return FoundationDBAPINonTransactionalReadinessProbe(self._connection)
+
+    def executescript(self, script: str) -> None:
+        for statement in _split_sql_statements(script):
+            if not statement:
+                continue
+            self.create_session().execute(statement)
+
+    def close(self) -> None:
+        with contextlib.suppress(Exception):
+            self._connection.close()
+
+    def _open_connection(self) -> Any:
+        raise NotImplementedError
+
+
+@dataclass(slots=True)
+class MySQLFoundationDatabase(_DBAPIFoundationDatabase):
+    def _open_connection(self) -> Any:
+        settings = _resolve_database_settings(self.settings)
+        host, port = _primary_endpoint(settings, default_port=3306)
+        if not host:
+            raise RuntimeError("foundation mysql host is not configured")
+        try:
+            module = importlib.import_module("pymysql")
+        except Exception as exc:
+            raise RuntimeError("pymysql is required for foundation mysql driver") from exc
+        kwargs: dict[str, Any] = {
+            "host": host,
+            "port": port,
+            "user": settings.user,
+            "password": settings.password,
+            "database": settings.database,
+            "charset": "utf8mb4",
+        }
+        cursor_cls = getattr(getattr(module, "cursors", None), "DictCursor", None)
+        if cursor_cls is not None:
+            kwargs["cursorclass"] = cursor_cls
+        if settings.connect_timeout > 0:
+            kwargs["connect_timeout"] = int(max(1, settings.connect_timeout))
+        kwargs.update(dict(settings.options or {}))
+        kwargs["autocommit"] = True
+        return module.connect(**kwargs)
+
+
+@dataclass(slots=True)
+class PostgreSQLFoundationDatabase(_DBAPIFoundationDatabase):
+    def _open_connection(self) -> Any:
+        settings = _resolve_database_settings(self.settings)
+        try:
+            module = importlib.import_module("psycopg")
+        except Exception as exc:
+            raise RuntimeError("psycopg is required for foundation postgresql driver") from exc
+        kwargs: dict[str, Any] = {}
+        with contextlib.suppress(Exception):
+            rows_module = importlib.import_module("psycopg.rows")
+            kwargs["row_factory"] = rows_module.dict_row
+        if settings.connect_timeout > 0:
+            kwargs["connect_timeout"] = int(max(1, settings.connect_timeout))
+        kwargs.update(_build_postgresql_ssl_kwargs(settings))
+        kwargs.update(dict(settings.options or {}))
+        kwargs["autocommit"] = True
+        return module.connect(_build_postgresql_dsn(settings), **kwargs)
+
+
+_DATABASE_SINGLETONS: dict[str, FoundationDatabase] = {}
+_NAMED_PARAM_PATTERN = re.compile(r"(?<!:):([A-Za-z_][A-Za-z0-9_]*)")
+
+
+def load_foundation_database_settings(
+    *,
+    project_dir: str | PathLike[str] | None = None,
+) -> FoundationDatabaseSettings:
+    return _resolve_foundation_database_settings(project_dir=project_dir)
+
+
+def _database_binding_configured(settings: FoundationDatabaseSettings) -> bool:
+    if not settings.enabled:
+        return False
+    if tuple(getattr(settings, "urls", ()) or ()):
+        return True
+    driver = _normalize_driver(settings.driver, url=_primary_database_url(settings))
+    if driver == "sqlite":
+        return bool(str(settings.path or "").strip())
+    if driver in {"mysql", "postgresql"}:
+        return bool(str(settings.host or "").strip() or settings.hosts) and bool(
+            str(settings.database or "").strip()
+        )
+    return False
+
+
+def describe_foundation_database_binding(
+    *,
+    project_dir: str | PathLike[str] | None = None,
+    settings: FoundationDatabaseSettings | None = None,
+) -> dict[str, Any]:
+    resolved = settings or _resolve_foundation_database_settings(project_dir=project_dir)
+    configured = _database_binding_configured(resolved)
+    return {
+        "enabled": bool(resolved.enabled),
+        "configured": configured,
+        "driver": resolved.driver,
+        "path": resolved.path,
+        "urls": tuple(resolved.urls),
+        "host": resolved.host,
+        "port": resolved.port,
+        "hosts": tuple(resolved.hosts),
+        "ports": tuple(resolved.ports),
+        "database": resolved.database,
+        "user": resolved.user,
+        "target_session_attrs": resolved.target_session_attrs,
+        "operational": False,
+        "degraded": False,
+        "ready": False,
+        "error": None,
+        "probe_deferred": True,
+    }
+
+
+def probe_foundation_database_binding(
+    *,
+    project_dir: str | PathLike[str] | None = None,
+    settings: FoundationDatabaseSettings | None = None,
+) -> dict[str, Any]:
+    status = describe_foundation_database_binding(project_dir=project_dir, settings=settings)
+    if not status["enabled"] or not status["configured"]:
+        status["probe_deferred"] = False
+        return status
+    try:
+        lifecycle = connection_lifecycle_status(tortoise_manager)
+        status["lifecycle"] = _lifecycle_status_payload(lifecycle)
+        if lifecycle.default_ready:
+            status["ready"] = True
+            status["operational"] = True
+            status["probe_deferred"] = False
+        else:
+            status["probe_deferred"] = True
+        return status
+    except Exception as exc:
+        status["error"] = str(exc)
+        status["probe_deferred"] = False
+        return status
+
+
+def _lifecycle_status_payload(lifecycle: DBConnectionLifecycleStatus) -> dict[str, Any]:
+    return {
+        "initialized": lifecycle.initialized,
+        "loop_matches": lifecycle.loop_matches,
+        "default_configured": lifecycle.default_configured,
+        "default_open": lifecycle.default_open,
+        "read_only_configured": lifecycle.read_only_configured,
+        "read_only_open": lifecycle.read_only_open,
+        "default_status": lifecycle.alias_status("default"),
+        "read_only_status": lifecycle.alias_status("read_only"),
+    }
+
+
+def normalize_foundation_database_settings(settings: FoundationDatabaseSettings) -> FoundationDatabaseSettings:
+    return _resolve_database_settings(settings)
+
+
+def _resolve_foundation_database_settings(
+    *,
+    project_dir: str | PathLike[str] | None = None,
+) -> FoundationDatabaseSettings:
+    database_payload = _database_snapshot(project_dir=project_dir)
+    urls = _read_str_sequence(database_payload, "urls")
+    raw_driver = _read_str_value(database_payload, "driver")
+    driver = _normalize_driver(raw_driver or "", url="" if raw_driver else (urls[0] if urls else ""))
+    enabled = _read_bool_value(database_payload, "enabled", False)
+    explicit_path = _read_str_value(database_payload, "path")
+    sqlite_path = _sqlite_path_from_url(urls[0] if urls else "")
+    default_sqlite_path = str(
+        resolve_project_context(_resolve_project_dir(project_dir)).asset_dir / "foundation" / "foundation.sqlite3"
+    )
+    path = explicit_path or sqlite_path
+    if driver == "sqlite" and not path:
+        path = default_sqlite_path
+    host = _read_str_value(database_payload, "host")
+    raw_port = _read_str_value(database_payload, "port")
+    ports = _coerce_port_values(raw_port)
+    port = ports[0] if ports else 0
+    user = _read_str_value(database_payload, "user")
+    password = _read_str_value(database_payload, "password")
+    database_name = _read_str_value(database_payload, "database")
+    min_size = _read_alias_int(database_payload, ("min_size",), 1)
+    max_size = _read_alias_int(database_payload, ("max_size",), 10)
+    connect_timeout = _read_alias_float(database_payload, ("connect_timeout",), 5.0)
+    pool_acquire_timeout = _read_alias_float(database_payload, ("pool_acquire_timeout", "pool_timeout"), 5.0)
+    statement_timeout_ms = _read_alias_int(database_payload, ("statement_timeout_ms",), 30000)
+    idle_in_transaction_session_timeout_ms = _read_alias_int(
+        database_payload,
+        ("idle_in_transaction_session_timeout_ms",),
+        30000,
+    )
+    pool_max_lifetime = _read_alias_float(database_payload, ("pool_max_lifetime",), 3600.0)
+    pool_max_idle = _read_alias_float(database_payload, ("pool_max_idle",), 600.0)
+    reconnect_timeout = _read_alias_float(database_payload, ("reconnect_timeout",), 30.0)
+    health_check_interval = _read_alias_float(database_payload, ("health_check_interval",), 60.0)
+    ssl_mode = _read_str_value(database_payload, "ssl_mode")
+    ssl_root_cert = _read_str_value(database_payload, "ssl_root_cert")
+    ssl_cert = _read_str_value(database_payload, "ssl_cert")
+    ssl_key = _read_str_value(database_payload, "ssl_key")
+    ssl_password = _read_str_value(database_payload, "ssl_password")
+    target_session_attrs = _read_str_value(database_payload, "target_session_attrs")
+    settings = FoundationDatabaseSettings(
+        enabled=enabled,
+        driver=driver,
+        path=path,
+        urls=urls,
+        host=host,
+        port=port,
+        ports=ports,
+        user=user,
+        password=password,
+        database=database_name,
+        min_size=min_size,
+        max_size=max_size,
+        connect_timeout=connect_timeout,
+        pool_acquire_timeout=pool_acquire_timeout,
+        statement_timeout_ms=statement_timeout_ms,
+        idle_in_transaction_session_timeout_ms=idle_in_transaction_session_timeout_ms,
+        pool_max_lifetime=pool_max_lifetime,
+        pool_max_idle=pool_max_idle,
+        reconnect_timeout=reconnect_timeout,
+        health_check_interval=health_check_interval,
+        ssl_mode=ssl_mode,
+        ssl_root_cert=ssl_root_cert,
+        ssl_cert=ssl_cert,
+        ssl_key=ssl_key,
+        ssl_password=ssl_password,
+        target_session_attrs=target_session_attrs,
+    )
+    return _resolve_database_settings(settings)
+
+
+def get_foundation_database(
+    *,
+    project_dir: str | PathLike[str] | None = None,
+    settings: FoundationDatabaseSettings | None = None,
+) -> FoundationDatabase:
+    resolved_settings = _resolve_database_settings(
+        settings or _resolve_foundation_database_settings(project_dir=project_dir)
+    )
+    key = _database_singleton_key(resolved_settings)
+    database = _DATABASE_SINGLETONS.get(key)
+    if database is None:
+        if resolved_settings.driver == "sqlite":
+            database = SQLiteFoundationDatabase(resolved_settings)
+        elif resolved_settings.driver == "mysql":
+            database = MySQLFoundationDatabase(resolved_settings)
+        elif resolved_settings.driver == "postgresql":
+            database = PostgreSQLFoundationDatabase(resolved_settings)
+        else:
+            raise RuntimeError(f"unsupported foundation database driver: {resolved_settings.driver!r}")
+        _DATABASE_SINGLETONS[key] = database
+    return database
+
+
+def get_foundation_database_if_enabled(
+    *,
+    project_dir: str | PathLike[str] | None = None,
+    settings: FoundationDatabaseSettings | None = None,
+) -> FoundationDatabase | None:
+    resolved_settings = _resolve_database_settings(
+        settings or _resolve_foundation_database_settings(project_dir=project_dir)
+    )
+    if not resolved_settings.enabled:
+        return None
+    return get_foundation_database(project_dir=project_dir, settings=resolved_settings)
+
+
+def reset_foundation_databases() -> None:
+    for database in list(_DATABASE_SINGLETONS.values()):
+        with contextlib.suppress(Exception):
+            database.close()
+    _DATABASE_SINGLETONS.clear()
+
+
+def _database_snapshot(
+    *,
+    project_dir: str | PathLike[str] | None = None,
+):
+    try:
+        payload = _payload_dict(_foundation_settings_section("database", project_dir=project_dir))
+    except Exception:
+        payload = {}
+    return payload
+
+
+def _resolve_project_dir(project_dir: str | PathLike[str] | None) -> Path:
+    if project_dir is not None:
+        return resolve_project_context(project_dir).project_dir.resolve()
+    try:
+        project = _project_settings()
+        return resolve_project_context(str(getattr(project, "project_dir", ".") or ".")).project_dir.resolve()
+    except Exception:
+        return resolve_project_context().project_dir.resolve()
+
+
+def _primary_database_url(settings: FoundationDatabaseSettings) -> str:
+    urls = tuple(getattr(settings, "urls", ()) or ())
+    return str(urls[0] or "").strip() if urls else ""
+
+
+def _payload_dict(payload: Any) -> dict[str, Any]:
+    if isinstance(payload, dict):
+        return dict(payload)
+    if hasattr(payload, "to_dict") and callable(payload.to_dict):
+        try:
+            value = payload.to_dict()
+        except Exception:
+            value = None
+        if isinstance(value, dict):
+            return dict(value)
+    return dict(getattr(payload, "__dict__", {}) or {})
+
+
+def _read_bool_value(payload: Any, key: str, default: bool) -> bool:
+    value = payload.get(key, default) if isinstance(payload, dict) else getattr(payload, key, default)
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _read_str_value(payload: Any, key: str) -> str:
+    value = payload.get(key) if isinstance(payload, dict) else getattr(payload, key, None)
+    text = str(value or "").strip()
+    if text in {'""', "''"}:
+        return ""
+    return text
+
+
+def _read_alias_int(payload: Any, keys: tuple[str, ...], default: int) -> int:
+    for key in keys:
+        value = payload.get(key) if isinstance(payload, dict) else getattr(payload, key, None)
+        if value is None or str(value).strip() == "":
+            continue
+        try:
+            return int(value)
+        except Exception:
+            continue
+    return int(default)
+
+
+def _resolve_database_settings(settings: FoundationDatabaseSettings) -> FoundationDatabaseSettings:
+    raw_driver = str(settings.driver or "").strip()
+    urls = _coerce_database_url_values(getattr(settings, "urls", ()))
+    driver = _normalize_driver(raw_driver, url="" if raw_driver else (urls[0] if urls else ""))
+    host = settings.host
+    port = int(settings.port or 0)
+    hosts = _coerce_host_values(getattr(settings, "hosts", ()))
+    ports = _coerce_port_values(getattr(settings, "ports", ()))
+    user = settings.user
+    password = settings.password
+    database_name = settings.database
+    min_size = int(getattr(settings, "min_size", 1) or 1)
+    max_size = int(getattr(settings, "max_size", 10) or 10)
+    pool_acquire_timeout = float(getattr(settings, "pool_acquire_timeout", 5.0) or 0.0)
+    statement_timeout_ms = int(getattr(settings, "statement_timeout_ms", 30000) or 0)
+    idle_in_transaction_session_timeout_ms = int(
+        getattr(settings, "idle_in_transaction_session_timeout_ms", 30000) or 0
+    )
+    pool_max_lifetime = float(getattr(settings, "pool_max_lifetime", 3600.0) or 0.0)
+    pool_max_idle = float(getattr(settings, "pool_max_idle", 600.0) or 0.0)
+    reconnect_timeout = float(getattr(settings, "reconnect_timeout", 30.0) or 0.0)
+    health_check_interval = float(getattr(settings, "health_check_interval", 60.0) or 0.0)
+    path = settings.path
+    ssl_mode = settings.ssl_mode
+    ssl_root_cert = settings.ssl_root_cert
+    ssl_cert = settings.ssl_cert
+    ssl_key = settings.ssl_key
+    ssl_password = settings.ssl_password
+    target_session_attrs = str(getattr(settings, "target_session_attrs", "") or "").strip()
+    options = dict(settings.options or {})
+    url_sources = urls
+    parsed_url_payloads: list[dict[str, Any]] = []
+    for url_value in url_sources:
+        try:
+            parsed_url_payloads.append(_parse_database_url(url_value))
+        except Exception:
+            raise
+    if parsed_url_payloads:
+        first = parsed_url_payloads[0]
+        parsed_driver = _normalize_driver(first["driver"])
+        if raw_driver and parsed_driver != driver:
+            urls = ()
+            parsed_url_payloads = []
+        else:
+            parsed_hosts: list[str] = []
+            parsed_ports: list[int] = []
+            for parsed_payload in parsed_url_payloads:
+                if _normalize_driver(parsed_payload["driver"]) != parsed_driver:
+                    continue
+                parsed_hosts.extend(parsed_payload["hosts"])
+                parsed_ports.extend(parsed_payload["ports"])
+                for key, value in dict(parsed_payload.get("options", {}) or {}).items():
+                    if key not in options:
+                        options[key] = value
+            if not host:
+                host = ",".join(parsed_hosts) or first["host"]
+            if not port:
+                port = parsed_ports[0] if parsed_ports else first["port"]
+            if not hosts:
+                hosts = tuple(parsed_hosts) or first["hosts"]
+            if not ports:
+                ports = tuple(parsed_ports) or first["ports"]
+            if not user:
+                user = first["user"]
+            if not password:
+                password = first["password"]
+            if not database_name:
+                database_name = first["database"]
+            if not path:
+                path = first["path"]
+            if not ssl_mode:
+                ssl_mode = first["ssl_mode"]
+            if not ssl_root_cert:
+                ssl_root_cert = first["ssl_root_cert"]
+            if not ssl_cert:
+                ssl_cert = first["ssl_cert"]
+            if not ssl_key:
+                ssl_key = first["ssl_key"]
+            if not ssl_password:
+                ssl_password = first["ssl_password"]
+            if not target_session_attrs:
+                target_session_attrs = first["target_session_attrs"]
+            if not raw_driver:
+                driver = parsed_driver
+    host, port, hosts, ports = _normalize_network_settings(
+        driver=driver,
+        host=host,
+        port=port,
+        hosts=hosts,
+        ports=ports,
+    )
+    if driver == "sqlite":
+        port = 0
+        host = ""
+        hosts = ()
+        ports = ()
+        user = ""
+        password = ""
+        database_name = database_name or Path(path or "").name
+        ssl_mode = ""
+        ssl_root_cert = ""
+        ssl_cert = ""
+        ssl_key = ""
+        ssl_password = ""
+        target_session_attrs = ""
+        urls = ()
+    elif driver == "mysql":
+        port = port or 3306
+    elif driver == "postgresql":
+        port = port or 5432
+    min_size = max(1, min_size)
+    max_size = max(min_size, max_size)
+    pool_acquire_timeout = max(0.1, pool_acquire_timeout or 5.0)
+    statement_timeout_ms = max(0, statement_timeout_ms)
+    idle_in_transaction_session_timeout_ms = max(0, idle_in_transaction_session_timeout_ms)
+    pool_max_lifetime = max(0.0, pool_max_lifetime)
+    pool_max_idle = max(0.0, pool_max_idle)
+    reconnect_timeout = max(0.0, reconnect_timeout)
+    health_check_interval = max(1.0, health_check_interval or 60.0)
+    return FoundationDatabaseSettings(
+        enabled=settings.enabled,
+        driver=driver,
+        path=path,
+        urls=urls,
+        host=host,
+        port=port,
+        hosts=hosts,
+        ports=ports,
+        user=user,
+        password=password,
+        database=database_name,
+        min_size=min_size,
+        max_size=max_size,
+        connect_timeout=float(settings.connect_timeout or 0.0),
+        pool_acquire_timeout=pool_acquire_timeout,
+        statement_timeout_ms=statement_timeout_ms,
+        idle_in_transaction_session_timeout_ms=idle_in_transaction_session_timeout_ms,
+        pool_max_lifetime=pool_max_lifetime,
+        pool_max_idle=pool_max_idle,
+        reconnect_timeout=reconnect_timeout,
+        health_check_interval=health_check_interval,
+        ssl_mode=ssl_mode,
+        ssl_root_cert=ssl_root_cert,
+        ssl_cert=ssl_cert,
+        ssl_key=ssl_key,
+        ssl_password=ssl_password,
+        target_session_attrs=target_session_attrs,
+        options=options,
+    )
+
+
+def _parse_database_url(url: str) -> dict[str, Any]:
+    parsed = urlparse(url)
+    driver = _normalize_driver(parsed.scheme, url=url)
+    query = parse_qs(parsed.query or "", keep_blank_values=False)
+    if driver == "sqlite":
+        return {
+            "driver": "sqlite",
+            "host": "",
+            "port": 0,
+            "hosts": (),
+            "ports": (),
+            "user": "",
+            "password": "",
+            "database": Path(_sqlite_path_from_url(url) or "").name,
+            "path": _sqlite_path_from_url(url),
+            "ssl_mode": "",
+            "ssl_root_cert": "",
+            "ssl_cert": "",
+            "ssl_key": "",
+            "ssl_password": "",
+            "target_session_attrs": "",
+            "options": {},
+        }
+    userinfo, hostspec = _split_database_netloc(parsed.netloc or "")
+    user, password = _parse_database_userinfo(userinfo)
+    hosts, ports = _split_hosts_and_ports(hostspec, _default_port_for_driver(driver))
+    return {
+        "driver": driver,
+        "host": ",".join(hosts),
+        "port": ports[0] if ports else 0,
+        "hosts": hosts,
+        "ports": ports,
+        "user": user,
+        "password": password,
+        "database": unquote((parsed.path or "").lstrip("/")),
+        "path": "",
+        "ssl_mode": _first_query_value(query, "sslmode"),
+        "ssl_root_cert": _first_query_value(query, "sslrootcert"),
+        "ssl_cert": _first_query_value(query, "sslcert"),
+        "ssl_key": _first_query_value(query, "sslkey"),
+        "ssl_password": _first_query_value(query, "sslpassword"),
+        "target_session_attrs": _first_query_value(query, "target_session_attrs"),
+        "options": _extra_query_options(query),
+    }
+
+
+def _extra_query_options(query: dict[str, list[str]]) -> dict[str, str]:
+    reserved = {"sslmode", "sslrootcert", "sslcert", "sslkey", "sslpassword", "target_session_attrs"}
+    options: dict[str, str] = {}
+    for key in query:
+        if key in reserved:
+            continue
+        value = _first_query_value(query, key)
+        if value:
+            options[key] = value
+    return options
+
+
+def _sqlite_path_from_url(url: str) -> str:
+    raw = str(url or "").strip()
+    if not raw.lower().startswith("sqlite:"):
+        return ""
+    if raw.lower().startswith("sqlite:///:memory:"):
+        return ":memory:"
+    if raw.lower().startswith("sqlite:////"):
+        return raw[len("sqlite:///") :]
+    if raw.lower().startswith("sqlite:///"):
+        return raw[len("sqlite:///") :]
+    if raw.lower().startswith("sqlite://"):
+        return raw[len("sqlite://") :]
+    return ""
+
+
+def _default_port_for_driver(driver: str) -> int:
+    normalized = _normalize_driver(driver)
+    if normalized == "postgresql":
+        return 5432
+    if normalized == "mysql":
+        return 3306
+    return 0
+
+
+def _coerce_host_values(values: Any) -> tuple[str, ...]:
+    if isinstance(values, str):
+        items = values.split(",")
+    else:
+        items = values or ()
+    out: list[str] = []
+    for item in items:
+        value = str(item or "").strip()
+        if value:
+            out.append(value)
+    return tuple(out)
+
+
+def _coerce_port_values(values: Any) -> tuple[int, ...]:
+    if isinstance(values, str):
+        items = values.split(",")
+    else:
+        items = values or ()
+    out: list[int] = []
+    for item in items:
+        value = str(item or "").strip()
+        if not value:
+            continue
+        try:
+            parsed = int(value)
+        except Exception:
+            continue
+        if parsed > 0:
+            out.append(parsed)
+    return tuple(out)
+
+
+def _coerce_database_url_values(values: Any) -> tuple[str, ...]:
+    if values in (None, ""):
+        return ()
+    if isinstance(values, str):
+        return _split_database_url_list_string(values)
+    if isinstance(values, (list, tuple, set)):
+        out: list[str] = []
+        for item in values:
+            if isinstance(item, str):
+                out.extend(_split_database_url_list_string(item))
+                continue
+            value = str(item or "").strip()
+            if value:
+                out.append(value)
+        return tuple(out)
+    value = str(values or "").strip()
+    return (value,) if value else ()
+
+
+def _split_database_url_list_string(value: str) -> tuple[str, ...]:
+    text = str(value or "").strip()
+    if not text:
+        return ()
+    if text.startswith("["):
+        try:
+            decoded = json.loads(text)
+        except Exception:
+            decoded = None
+        if isinstance(decoded, list):
+            return _coerce_database_url_values(decoded)
+    if "\n" in text or ";" in text or "|" in text:
+        parts = re.split(r"[\n;|]+", text)
+    else:
+        parts = re.split(r"\s*,\s*(?=[A-Za-z][A-Za-z0-9+.-]*://)", text)
+    return tuple(part.strip() for part in parts if part.strip())
+
+
+def _split_database_netloc(netloc: str) -> tuple[str, str]:
+    text = str(netloc or "").strip()
+    if "@" not in text:
+        return "", text
+    userinfo, hostspec = text.rsplit("@", 1)
+    return userinfo, hostspec
+
+
+def _parse_database_userinfo(userinfo: str) -> tuple[str, str]:
+    if not userinfo:
+        return "", ""
+    user, _, password = str(userinfo).partition(":")
+    return unquote(user or ""), unquote(password or "")
+
+
+def _split_hosts_and_ports(hostspec: str, default_port: int) -> tuple[tuple[str, ...], tuple[int, ...]]:
+    hosts: list[str] = []
+    ports: list[int] = []
+    for raw_entry in str(hostspec or "").split(","):
+        host, port = _split_host_entry(raw_entry, default_port)
+        if not host:
+            continue
+        hosts.append(host)
+        ports.append(port)
+    return tuple(hosts), tuple(ports)
+
+
+def _split_host_entry(raw_entry: str, default_port: int) -> tuple[str, int]:
+    entry = str(raw_entry or "").strip()
+    if not entry:
+        return "", default_port
+    if entry.startswith("["):
+        closing = entry.find("]")
+        if closing > 0:
+            host = entry[1:closing].strip()
+            remainder = entry[closing + 1 :].strip()
+            if remainder.startswith(":"):
+                try:
+                    return host, int(remainder[1:] or default_port)
+                except Exception:
+                    return host, default_port
+            return host, default_port
+    if entry.count(":") == 1:
+        host, raw_port = entry.rsplit(":", 1)
+        try:
+            return host.strip(), int(raw_port or default_port)
+        except Exception:
+            return host.strip(), default_port
+    return entry, default_port
+
+
+def _format_host_for_uri(host: str) -> str:
+    value = str(host or "").strip()
+    if ":" in value and not (value.startswith("[") and value.endswith("]")):
+        return f"[{value}]"
+    return value
+
+
+def _expand_ports(ports: tuple[int, ...], *, count: int, fallback: int) -> tuple[int, ...]:
+    if count <= 0:
+        return ()
+    valid = tuple(int(item) for item in ports if int(item) > 0)
+    if len(valid) >= count:
+        return valid[:count]
+    if len(valid) == 1:
+        return tuple(valid[0] for _ in range(count))
+    if valid:
+        fill = valid[0]
+        return (*valid, *(fill for _ in range(count - len(valid))))
+    return tuple(int(fallback) for _ in range(count))
+
+
+def _normalize_network_settings(
+    *,
+    driver: str,
+    host: str,
+    port: int,
+    hosts: tuple[str, ...],
+    ports: tuple[int, ...],
+) -> tuple[str, int, tuple[str, ...], tuple[int, ...]]:
+    normalized_driver = _normalize_driver(driver)
+    if normalized_driver not in {"mysql", "postgresql"}:
+        return str(host or "").strip(), int(port or 0), (), ()
+    default_port = _default_port_for_driver(normalized_driver)
+    parsed_hosts = _coerce_host_values(hosts)
+    embedded_ports: tuple[int, ...] = ()
+    if parsed_hosts:
+        parsed_hosts, embedded_ports = _split_hosts_and_ports(",".join(parsed_hosts), default_port)
+    elif str(host or "").strip():
+        parsed_hosts, embedded_ports = _split_hosts_and_ports(str(host or ""), default_port)
+    if not parsed_hosts:
+        return "", int(port or default_port), (), ()
+    explicit_ports = _coerce_port_values(ports)
+    if explicit_ports:
+        port_values = explicit_ports
+    elif port:
+        port_values = (int(port),)
+    else:
+        port_values = embedded_ports
+    normalized_ports = _expand_ports(port_values, count=len(parsed_hosts), fallback=default_port)
+    return ",".join(parsed_hosts), normalized_ports[0], parsed_hosts, normalized_ports
+
+
+def _primary_endpoint(settings: FoundationDatabaseSettings, *, default_port: int) -> tuple[str, int]:
+    host = str(settings.host or "").strip()
+    port = int(settings.port or 0)
+    hosts, ports = _coerce_host_values(getattr(settings, "hosts", ())), _coerce_port_values(getattr(settings, "ports", ()))
+    normalized_host, normalized_port, normalized_hosts, normalized_ports = _normalize_network_settings(
+        driver=settings.driver,
+        host=host,
+        port=port,
+        hosts=hosts,
+        ports=ports,
+    )
+    if normalized_hosts:
+        return normalized_hosts[0], normalized_ports[0]
+    return normalized_host, normalized_port or default_port
+
+
+def _build_postgresql_dsn(settings: FoundationDatabaseSettings) -> str:
+    hosts = _coerce_host_values(getattr(settings, "hosts", ()))
+    ports = _coerce_port_values(getattr(settings, "ports", ()))
+    if not hosts:
+        normalized_host, _normalized_port, hosts, ports = _normalize_network_settings(
+            driver="postgresql",
+            host=settings.host,
+            port=settings.port,
+            hosts=hosts,
+            ports=ports,
+        )
+        if not hosts and normalized_host:
+            hosts = _coerce_host_values((normalized_host,))
+    if not hosts:
+        raise RuntimeError("foundation postgresql host is not configured")
+    user = settings.user or ""
+    password = settings.password or ""
+    auth = user
+    if password:
+        auth = f"{auth}:{password}" if auth else f":{password}"
+    if auth:
+        if ":" in auth:
+            raw_user, raw_password = auth.split(":", 1)
+            auth = f"{quote(raw_user, safe='')}:{quote(raw_password, safe='')}@"
+        else:
+            auth = f"{quote(auth, safe='')}@"
+    port_list = _expand_ports(
+        ports,
+        count=len(hosts),
+        fallback=_default_port_for_driver("postgresql"),
+    )
+    host = ",".join(f"{_format_host_for_uri(host_item)}:{port_item}" for host_item, port_item in zip(hosts, port_list))
+    name = quote(settings.database or "", safe="")
+    query: dict[str, str] = {}
+    if settings.ssl_mode:
+        query["sslmode"] = settings.ssl_mode
+    if settings.ssl_root_cert:
+        query["sslrootcert"] = settings.ssl_root_cert
+    if settings.ssl_cert:
+        query["sslcert"] = settings.ssl_cert
+    if settings.ssl_key:
+        query["sslkey"] = settings.ssl_key
+    if settings.ssl_password:
+        query["sslpassword"] = settings.ssl_password
+    target_session_attrs = str(getattr(settings, "target_session_attrs", "") or "").strip()
+    if not target_session_attrs and len(hosts) > 1:
+        target_session_attrs = "read-write"
+    if target_session_attrs:
+        query["target_session_attrs"] = target_session_attrs
+    for key, value in dict(settings.options or {}).items():
+        if key == "options" or key in query:
+            continue
+        if isinstance(value, (str, int, float, bool)) and str(value).strip():
+            query[key] = str(value)
+    dsn = f"postgresql://{auth}{host}/{name}"
+    if query:
+        dsn = f"{dsn}?{urlencode(query)}"
+    return dsn
+
+
+def _database_singleton_key(settings: FoundationDatabaseSettings) -> str:
+    return "|".join(
+        (
+            settings.driver,
+            settings.path,
+            ",".join(getattr(settings, "urls", ()) or ()),
+            settings.host,
+            str(settings.port),
+            ",".join(getattr(settings, "hosts", ()) or ()),
+            ",".join(str(item) for item in (getattr(settings, "ports", ()) or ())),
+            settings.user,
+            settings.database,
+            str(settings.connect_timeout),
+            str(settings.min_size),
+            str(settings.max_size),
+            str(settings.pool_acquire_timeout),
+            str(settings.statement_timeout_ms),
+            str(settings.idle_in_transaction_session_timeout_ms),
+            str(settings.pool_max_lifetime),
+            str(settings.pool_max_idle),
+            str(settings.reconnect_timeout),
+            str(settings.health_check_interval),
+            settings.ssl_mode,
+            settings.ssl_root_cert,
+            settings.ssl_cert,
+            settings.ssl_key,
+            settings.ssl_password,
+            settings.target_session_attrs,
+            repr(sorted(dict(settings.options or {}).items())),
+        )
+    )
+
+
+def _build_postgresql_ssl_kwargs(settings: FoundationDatabaseSettings) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {}
+    if settings.ssl_mode:
+        kwargs["sslmode"] = settings.ssl_mode
+    if settings.ssl_root_cert:
+        kwargs["sslrootcert"] = settings.ssl_root_cert
+    if settings.ssl_cert:
+        kwargs["sslcert"] = settings.ssl_cert
+    if settings.ssl_key:
+        kwargs["sslkey"] = settings.ssl_key
+    if settings.ssl_password:
+        kwargs["sslpassword"] = settings.ssl_password
+    return kwargs
+
+
+def _split_sql_statements(script: str) -> list[str]:
+    statements: list[str] = []
+    buffer: list[str] = []
+    in_single = False
+    in_double = False
+    escaped = False
+    for char in str(script or ""):
+        buffer.append(char)
+        if escaped:
+            escaped = False
+            continue
+        if char == "\\":
+            escaped = True
+            continue
+        if char == "'" and not in_double:
+            in_single = not in_single
+            continue
+        if char == '"' and not in_single:
+            in_double = not in_double
+            continue
+        if char == ";" and not in_single and not in_double:
+            statement = "".join(buffer).strip().rstrip(";").strip()
+            if statement:
+                statements.append(statement)
+            buffer = []
+    tail = "".join(buffer).strip()
+    if tail:
+        statements.append(tail.rstrip(";").strip())
+    return [item for item in statements if item]
+
+
+def _coerce_dbapi_row(description: Any, row: Any) -> dict[str, Any]:
+    if isinstance(row, dict):
+        return dict(row)
+    names = [str(item[0]) for item in description or ()]
+    if hasattr(row, "keys") and callable(row.keys):
+        return {str(key): row[key] for key in row.keys()}
+    return {name: row[index] for index, name in enumerate(names)}
+
+
+def _prepare_statement(driver: str, statement: str, args: tuple[Any, ...], kwargs: dict[str, Any]) -> tuple[str, Any]:
+    params: Any
+    if kwargs:
+        params = kwargs
+    elif len(args) == 1 and isinstance(args[0], (tuple, list, dict)):
+        params = args[0]
+    elif args:
+        params = args
+    else:
+        params = None
+    normalized = _normalize_driver(driver)
+    if params is None or normalized == "sqlite":
+        return statement, params
+    if isinstance(params, dict):
+        return _NAMED_PARAM_PATTERN.sub(r"%(\1)s", statement), params
+    return statement, params
+
+
+def _normalize_driver(driver: str, *, url: str = "") -> str:
+    raw = str(driver or "").strip().lower()
+    if not raw and url:
+        raw = urlparse(url).scheme.lower()
+    if "+" in raw:
+        raw = raw.split("+", 1)[0]
+    if raw in {"postgres", "postgresql", "psql"}:
+        return "postgresql"
+    if raw in {"mysql", "mariadb"}:
+        return "mysql"
+    if raw in {"sqlite", "sqlite3"}:
+        return "sqlite"
+    return raw or "sqlite"
+
+
+def _read_str(payload: Any, key: str) -> str:
+    def _normalize(raw: Any) -> str:
+        value = str(raw or "").strip()
+        if value in {'""', "''"}:
+            return ""
+        return value
+
+    if isinstance(payload, dict):
+        return _normalize(payload.get(key))
+    return _normalize(getattr(payload, key, ""))
+
+
+def _read_alias_str(payload: Any, *keys: str) -> str:
+    for key in keys:
+        value = _read_str(payload, key)
+        if value:
+            return value
+    return ""
+
+
+def _read_str_sequence(payload: Any, key: str) -> tuple[str, ...]:
+    value = payload.get(key) if isinstance(payload, dict) else getattr(payload, key, None)
+    return _coerce_database_url_values(value)
+
+
+def _read_alias_int(payload: Any, keys: tuple[str, ...], default: int) -> int:
+    for key in keys:
+        value = payload.get(key) if isinstance(payload, dict) else getattr(payload, key, None)
+        if value in {None, ""}:
+            continue
+        try:
+            return int(value)
+        except Exception:
+            return default
+    return default
+
+
+def _read_alias_float(payload: Any, keys: tuple[str, ...], default: float) -> float:
+    for key in keys:
+        value = payload.get(key) if isinstance(payload, dict) else getattr(payload, key, None)
+        if value in {None, ""}:
+            continue
+        try:
+            return float(value)
+        except Exception:
+            return default
+    return default
+
+
+def _first_query_value(query: dict[str, list[str]], key: str) -> str:
+    values = query.get(key) or []
+    if not values:
+        return ""
+    return str(values[0] or "").strip()
+
+
+
+
+__all__ = [
+    "describe_foundation_database_binding",
+    "FoundationDatabase",
+    "FoundationDatabaseSettings",
+    "MySQLFoundationDatabase",
+    "normalize_foundation_database_settings",
+    "PostgreSQLFoundationDatabase",
+    "SQLiteFoundationDatabase",
+    "SQLiteFoundationReadinessProbe",
+    "SQLiteFoundationSession",
+    "SQLiteFoundationTransaction",
+    "get_foundation_database",
+    "load_foundation_database_settings",
+    "probe_foundation_database_binding",
+    "reset_foundation_databases",
+]