ping-dataexport 0.1.0__py3-none-any.whl

ping_dataexport/__init__.py

@@ -0,0 +1,11 @@
+"""Ping Python Data Export — universal database export to CSV/TXT/Parquet.
+
+Universal Data Export for data platforms. Row-streaming only: data flows
+cursor -> writer preserving native driver types. Pandas/numpy are banned in this
+project (they silently coerce column types).
+
+The package uses relative imports only and has no import-time side effects, so
+the directory can be copied into any project and imported directly.
+"""
+
+__version__ = "0.1.0"

ping_dataexport/__main__.py

@@ -0,0 +1,54 @@
+"""CLI entry point — the ONLY place exceptions become exit codes.
+
+Exit codes: 0 success (all jobs in parallel mode), 1 on any
+validation/config/export failure. No arguments prints help and exits 0.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+from .api import run_cli_args, run_jobfile
+from .applogger import AppLogger
+from .cli import build_parser, parse_args
+from .errors import PingExportError
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    if not argv:
+        build_parser().print_help()
+        return 0
+
+    args = parse_args(argv)
+    logger = AppLogger()
+    try:
+        if args.parallel is not None and not args.job:
+            results = run_jobfile(
+                jobfile=args.jobfile,
+                configfile=args.configfile,
+                workers=args.parallel or None,
+                test=args.test,
+                logger=logger,
+            )
+            return 0 if all(r.ok for r in results) else 1
+
+        if args.parallel is not None and args.job:
+            logger.warning("VALIDATION", "PARALLEL", "--parallel is ignored with --job")
+
+        run_cli_args(args, logger)
+        return 0
+    except PingExportError as exc:
+        logger.error("RESULT", "FAILED", str(exc))
+        return 1
+    except KeyboardInterrupt:
+        logger.error("RESULT", "INTERRUPTED", "cancelled by user")
+        return 130
+    finally:
+        logger.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ping_dataexport/api.py

@@ -0,0 +1,164 @@
+"""Public library API — the entry point for local scripts and Airflow.
+
+    from ping_dataexport.api import run_job, run_jobfile
+
+    result = run_job("DailySales", jobfile="job.ini", configfile="config.ini")
+
+- run_job / run_cli_args raise PingExportError subclasses on failure (Airflow-friendly:
+  the exception fails the task). No sys.exit anywhere in library code.
+- run_jobfile (parallel dispatch) never lets one job stop the others: it returns an
+  ExportResult per section; check .status.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Dict, List, Optional, Union
+
+from .applogger import AppLogger
+from .cli import CliArgs
+from .config import ConfigReader
+from .errors import ConfigError
+from .job.executor import JobExecutor
+from .job.shared_context import SharedContext
+from .job.spec import JobSpecBuilder
+from .job.validator import JobValidator
+
+COMPLETED = "COMPLETED"
+FAILED = "FAILED"
+
+
+@dataclass(frozen=True)
+class ExportResult:
+    name: str
+    status: str  # COMPLETED | FAILED
+    partitions: int = 0
+    rows: int = 0
+    files: List[str] = field(default_factory=list)
+    seconds: float = 0.0
+    error: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.status == COMPLETED
+
+
+def run_cli_args(args: CliArgs, logger: Optional[AppLogger] = None) -> ExportResult:
+    """Build -> validate -> execute one job from a CliArgs bundle. Raises on failure."""
+    logger = logger or AppLogger()
+    ctx = SharedContext(args.configfile, logger)
+    job_reader = ConfigReader(args.jobfile) if args.job else None
+    spec = JobSpecBuilder(args, ctx.main, job_reader).build(args.job)
+    JobValidator.validate(spec)
+    started = time.monotonic()
+    stats = JobExecutor(ctx).execute(spec)
+    return ExportResult(
+        name=spec.name,
+        status=COMPLETED,
+        partitions=stats.partitions,
+        rows=stats.rows,
+        files=[str(f) for f in stats.files],
+        seconds=time.monotonic() - started,
+    )
+
+
+def run_export(
+    source: str,
+    query: str,
+    *,
+    configfile: Union[str, Path] = "config.ini",
+    logger: Optional[AppLogger] = None,
+    **options: object,
+) -> ExportResult:
+    """Ad-hoc export: run_export("DB01", "SELECT ...", output="out.csv", gzip=True).
+
+    `options` accepts any CliArgs field (output, outputdir, basename, mode, column, …).
+    """
+    args = CliArgs(source=source, query=query, configfile=str(configfile), **options)
+    return run_cli_args(args, logger)
+
+
+run = run_export
+export = run_export
+
+
+def run_job(
+    job: str,
+    *,
+    jobfile: Union[str, Path] = "job.ini",
+    configfile: Union[str, Path] = "config.ini",
+    test: bool = False,
+    overrides: Optional[Dict[str, object]] = None,
+    logger: Optional[AppLogger] = None,
+) -> ExportResult:
+    """Run one job.ini section. `overrides` are CliArgs fields that win over the section."""
+    args = CliArgs(
+        job=job, jobfile=str(jobfile), configfile=str(configfile), test=test,
+        **(overrides or {}),
+    )
+    return run_cli_args(args, logger)
+
+
+def run_jobfile(
+    *,
+    jobfile: Union[str, Path] = "job.ini",
+    configfile: Union[str, Path] = "config.ini",
+    workers: Optional[int] = None,
+    test: bool = False,
+    logger: Optional[AppLogger] = None,
+) -> List[ExportResult]:
+    """Parallel mode: every section of the job file, each through the same
+    build -> validate -> resolve -> execute pipeline. One failure never stops the
+    others; the caller checks statuses (the CLI exits 1 if any failed)."""
+    logger = logger or AppLogger()
+    ctx = SharedContext(configfile, logger)
+    job_reader = ConfigReader(jobfile)
+    sections = job_reader.sections()
+    if not sections:
+        raise ConfigError(f"no job sections found in {jobfile}")
+
+    jobfile_base = Path(jobfile).stem
+    logs_dir: Optional[Path] = None
+    if ctx.main.export_folder:
+        logs_dir = Path(ctx.main.export_folder).expanduser() / "logs"
+        logger.open_master_file(logs_dir / f"log_{jobfile_base}.txt")
+
+    worker_count = min(workers if workers and workers > 0 else (os.cpu_count() or 1),
+                       len(sections))
+    logger.master("INFO", "PARALLEL", "START",
+                  f"{len(sections)} job(s), {worker_count} worker(s)")
+
+    def run_section(section: str) -> ExportResult:
+        started = time.monotonic()
+        try:
+            args = CliArgs(job=section, jobfile=str(jobfile), configfile=str(configfile),
+                           test=test)
+            spec = JobSpecBuilder(args, ctx.main, job_reader).build(section)
+            if logs_dir is not None:
+                spec = replace(spec, logfile=str(logs_dir / f"log_{jobfile_base}_{section}.txt"))
+            JobValidator.validate(spec)
+            stats = JobExecutor(ctx).execute(spec)
+            logger.master("INFO", "PARALLEL", "COMPLETED", section)
+            return ExportResult(
+                name=spec.name, status=COMPLETED, partitions=stats.partitions,
+                rows=stats.rows, files=[str(f) for f in stats.files],
+                seconds=time.monotonic() - started,
+            )
+        except Exception as exc:  # one failure never stops the others
+            logger.master("ERROR", "PARALLEL", "FAILED", f"{section}: {exc}")
+            return ExportResult(name=section, status=FAILED, error=str(exc),
+                                seconds=time.monotonic() - started)
+
+    try:
+        with ThreadPoolExecutor(max_workers=worker_count) as pool:
+            results = list(pool.map(run_section, sections))
+        succeeded = sum(1 for r in results if r.ok)
+        logger.master("INFO", "PARALLEL", "SUMMARY",
+                      f"{succeeded}/{len(results)} job(s) succeeded")
+        return results
+    finally:
+        logger.close_master_file()

ping_dataexport/applogger.py

@@ -0,0 +1,104 @@
+"""Structured logger — one fixed line format for every run.
+
+Line format (6 fields): timestamp | jobname | LEVEL | TYPE | OP | detail
+  - stdout: " | " separated
+  - file:   tab separated
+
+Instance-based (no singleton). The current job name and per-job log file live in
+contextvars, so parallel jobs on worker threads write to their own file while the
+dispatcher writes PARALLEL lines to a master file. Passwords must be masked by the
+caller (DBConfig.safe_items()).
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+from contextvars import ContextVar
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, TextIO, Union
+
+INFO = "INFO"
+WARN = "WARN"
+ERROR = "ERROR"
+
+_TS_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+class AppLogger:
+    def __init__(self, stdout: Optional[TextIO] = None):
+        self._stdout = stdout if stdout is not None else sys.stdout
+        self._job_name: ContextVar[str] = ContextVar("ping_job_name", default="-")
+        self._job_file: ContextVar[Optional[TextIO]] = ContextVar("ping_job_file", default=None)
+        self._master_file: Optional[TextIO] = None
+        self._lock = threading.Lock()
+
+    # -- context ------------------------------------------------------------
+
+    def set_job_name(self, name: str) -> None:
+        self._job_name.set(name)
+
+    def job_name(self) -> str:
+        return self._job_name.get()
+
+    def open_job_file(self, path: Union[str, Path]) -> None:
+        """Open (append) the per-job log file for the current thread/context."""
+        self.close_job_file()
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        self._job_file.set(open(p, "a", encoding="utf-8", newline="\n"))
+
+    def close_job_file(self) -> None:
+        fh = self._job_file.get()
+        if fh is not None:
+            try:
+                fh.close()
+            finally:
+                self._job_file.set(None)
+
+    def open_master_file(self, path: Union[str, Path]) -> None:
+        self.close_master_file()
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        self._master_file = open(p, "a", encoding="utf-8", newline="\n")
+
+    def close_master_file(self) -> None:
+        if self._master_file is not None:
+            try:
+                self._master_file.close()
+            finally:
+                self._master_file = None
+
+    def close(self) -> None:
+        self.close_job_file()
+        self.close_master_file()
+
+    # -- emit ---------------------------------------------------------------
+
+    def log(self, level: str, type_: str, op: str, detail: str = "") -> None:
+        """Write to stdout + the current context's job file."""
+        self._emit(level, type_, op, detail, self._job_file.get())
+
+    def master(self, level: str, type_: str, op: str, detail: str = "") -> None:
+        """Write to stdout + the master file (parallel-dispatch lines)."""
+        self._emit(level, type_, op, detail, self._master_file)
+
+    def info(self, type_: str, op: str, detail: str = "") -> None:
+        self.log(INFO, type_, op, detail)
+
+    def warning(self, type_: str, op: str, detail: str = "") -> None:
+        self.log(WARN, type_, op, detail)
+
+    def error(self, type_: str, op: str, detail: str = "") -> None:
+        self.log(ERROR, type_, op, detail)
+
+    def _emit(self, level: str, type_: str, op: str, detail: str, fh: Optional[TextIO]) -> None:
+        fields = [datetime.now().strftime(_TS_FORMAT), self._job_name.get(), level, type_, op]
+        if detail != "":
+            fields.append(detail)
+        with self._lock:
+            print(" | ".join(fields), file=self._stdout)
+            if fh is not None:
+                fh.write("\t".join(fields) + "\n")
+                fh.flush()

ping_dataexport/cli.py

@@ -0,0 +1,101 @@
+"""argparse CLI — the short/long option names are a stable public surface.
+
+Flags default to None (not False) so the JobSpecBuilder can tell "absent on CLI"
+from "explicitly off" when layering CLI > job.ini > [Main] > defaults.
+"""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import List, Optional
+
+PROG = "python -m ping_dataexport"
+
+MODES = ("groupby", "date", "relativedate", "splitrow", "watermark", "monthbydate")
+FORMATS = ("csv", "txt", "parquet")
+STRIP_NEWLINE_MODES = ("space", "blank", "escape", "doubleescape")
+
+
+@dataclass(frozen=True)
+class CliArgs:
+    source: Optional[str] = None
+    query: Optional[str] = None
+    output: Optional[str] = None
+    outputdir: Optional[str] = None
+    basename: Optional[str] = None
+    format: Optional[str] = None
+    gzip: Optional[bool] = None
+    quote: Optional[str] = None
+    sep: Optional[str] = None
+    stripnewline: Optional[str] = None
+    stripmetachar: Optional[bool] = None
+    fetchsize: Optional[int] = None
+    mode: Optional[str] = None
+    column: Optional[str] = None
+    row: Optional[int] = None
+    datefrom: Optional[str] = None
+    dateto: Optional[str] = None
+    daysrelative: Optional[int] = None
+    monthsrelative: Optional[int] = None
+    removeexisting: Optional[str] = None
+    configfile: str = "config.ini"
+    jobfile: str = "job.ini"
+    job: Optional[str] = None
+    name: Optional[str] = None
+    logfile: Optional[str] = None
+    test: bool = False
+    parallel: Optional[int] = None  # None = off, 0 = default worker count, >0 = workers
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog=PROG,
+        description="Universal database data export to CSV/TXT/Parquet.",
+        allow_abbrev=False,
+    )
+    p.add_argument("-s", "--source", help="DB config section name (e.g. DB01)")
+    p.add_argument("-q", "--query", help="SQL query (required unless --job is used)")
+
+    p.add_argument("-o", "--output", help="single output file path")
+    p.add_argument("-od", "--outputdir", help="output directory (required with --mode)")
+    p.add_argument("-bn", "--basename", help="base filename for mode exports")
+
+    p.add_argument("-f", "--format", choices=FORMATS, help="output format (auto from extension)")
+    p.add_argument("-gz", "--gzip", action="store_true", default=None,
+                   help="gzip compress output (csv/txt only)")
+
+    p.add_argument("-quo", "--quote", help='quote character (default ")')
+    p.add_argument("-sp", "--sep", help="field separator (default ,) — \\t maps to tab")
+    p.add_argument("-stnl", "--stripnewline", choices=STRIP_NEWLINE_MODES,
+                   help="newline handling in text columns")
+    p.add_argument("-stmc", "--stripmetachar", action="store_true", default=None,
+                   help="strip invisible/control chars from text columns")
+    p.add_argument("-fs", "--fetchsize", type=int, help="cursor fetch/array size")
+
+    p.add_argument("-m", "--mode", choices=MODES, help="export mode")
+    p.add_argument("-col", "--column", help="column name for the mode")
+    p.add_argument("-row", "--row", type=int, help="rows per file (splitrow)")
+    p.add_argument("-df", "--datefrom", help="start date yyyy-MM-dd")
+    p.add_argument("-dt", "--dateto", help="end date yyyy-MM-dd")
+    p.add_argument("-dr", "--daysrelative", type=int, help="days before datefrom (relativedate)")
+    p.add_argument("-mr", "--monthsrelative", type=int,
+                   help="months before datefrom (monthbydate)")
+    p.add_argument("-rm", "--removeexisting", metavar="YES",
+                   help="Yes/True: clear resolved outputdir before export")
+
+    p.add_argument("-cf", "--configfile", default="config.ini", help="config INI path")
+    p.add_argument("-jf", "--jobfile", default="job.ini", help="job INI path")
+    p.add_argument("-j", "--job", help="job section name")
+    p.add_argument("-n", "--name", help="job name")
+    p.add_argument("-lf", "--logfile", help="log file path")
+    p.add_argument("-t", "--test", action="store_true", default=False,
+                   help="test mode: preview only, no files")
+    p.add_argument("-pl", "--parallel", nargs="?", const=0, type=int, metavar="N",
+                   help="run ALL job sections in parallel with N workers (default: CPU count)")
+    return p
+
+
+def parse_args(argv: List[str]) -> CliArgs:
+    ns = build_parser().parse_args(argv)
+    return CliArgs(**vars(ns))

ping_dataexport/config.py

@@ -0,0 +1,233 @@
+"""INI configuration layer: ConfigReader + MainConfig + DBConfig.
+
+- RawConfigParser with NO interpolation: values legitimately contain % and $.
+- Keys are case-preserving on read, case-insensitive on lookup.
+- Inline comments are NOT stripped: ConnectionString values contain ';'.
+- UTF-8 with BOM tolerance.
+"""
+
+from __future__ import annotations
+
+import base64
+import configparser
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Union
+
+from .errors import ConfigError
+
+_TRUE_VALUES = {"yes", "true", "1", "y", "on"}
+_FALSE_VALUES = {"no", "false", "0", "n", "off"}
+
+#: DB section Type values understood by the connector factory (db/connector.py).
+KNOWN_DB_TYPES = frozenset(
+    {"sqlite", "mssql-odbc", "freetds", "oracle-odbc", "odbc", "oracle", "sqlalchemy"}
+)
+
+MAIN_SECTION = "Main"
+
+
+def parse_bool(value: str, *, section: str, key: str) -> bool:
+    v = value.strip().lower()
+    if v in _TRUE_VALUES:
+        return True
+    if v in _FALSE_VALUES:
+        return False
+    raise ConfigError(f"[{section}] {key}: expected Yes/No or True/False, got {value!r}")
+
+
+def parse_int(value: str, *, section: str, key: str) -> int:
+    try:
+        return int(value.strip())
+    except ValueError:
+        raise ConfigError(f"[{section}] {key}: expected an integer, got {value!r}") from None
+
+
+class ConfigReader:
+    """Reads one INI file (config.ini or job.ini) with case-insensitive lookups."""
+
+    def __init__(self, path: Union[str, Path]):
+        self.path = Path(path)
+        if not self.path.is_file():
+            raise ConfigError(f"config file not found: {self.path}")
+        parser = configparser.RawConfigParser()
+        parser.optionxform = str  # preserve key case
+        try:
+            with open(self.path, "r", encoding="utf-8-sig") as fh:
+                parser.read_file(fh, source=str(self.path))
+        except OSError as exc:
+            raise ConfigError(f"cannot read {self.path}: {exc}") from exc
+        except (configparser.Error, UnicodeDecodeError) as exc:
+            raise ConfigError(f"cannot parse {self.path}: {exc}") from exc
+
+        # section lower-name -> (original name, {key lower -> (original key, value)})
+        self._sections: Dict[str, Tuple[str, Dict[str, Tuple[str, str]]]] = {}
+        for sec in parser.sections():
+            items: Dict[str, Tuple[str, str]] = {}
+            for key, value in parser.items(sec):
+                items[key.lower()] = (key, value)
+            self._sections[sec.lower()] = (sec, items)
+
+    def sections(self) -> List[str]:
+        """Section names in file order, original case."""
+        return [orig for orig, _ in self._sections.values()]
+
+    def has_section(self, section: str) -> bool:
+        return section.lower() in self._sections
+
+    def section_items(self, section: str) -> Dict[str, str]:
+        """Ordered {original-case key: value} for a section; ConfigError if missing."""
+        entry = self._sections.get(section.lower())
+        if entry is None:
+            raise ConfigError(f"section [{section}] not found in {self.path}")
+        return {orig_key: value for orig_key, value in entry[1].values()}
+
+    def get(self, section: str, key: str, default: Optional[str] = None) -> Optional[str]:
+        entry = self._sections.get(section.lower())
+        if entry is None:
+            return default
+        item = entry[1].get(key.lower())
+        return item[1] if item is not None else default
+
+    def get_required(self, section: str, key: str) -> str:
+        value = self.get(section, key)
+        if value is None or value.strip() == "":
+            raise ConfigError(f"[{section}] {key} is required in {self.path}")
+        return value
+
+
+@dataclass(frozen=True)
+class MainConfig:
+    """config.ini [Main] defaults. A missing [Main] section yields all defaults."""
+
+    export_folder: Optional[str] = None
+    temp_folder: Optional[str] = None
+    fetch_size: int = 10000
+    preview_row: int = 10
+    force_make_dir: bool = True
+    row_id_column: Optional[str] = None
+    data_date_column: Optional[str] = None
+    log_file: Optional[str] = None
+
+    @classmethod
+    def from_reader(cls, reader: ConfigReader) -> "MainConfig":
+        if not reader.has_section(MAIN_SECTION):
+            return cls()
+
+        def opt(key: str) -> Optional[str]:
+            value = reader.get(MAIN_SECTION, key)
+            return value.strip() if value is not None and value.strip() != "" else None
+
+        kwargs: Dict[str, object] = {}
+        if opt("ExportFolder") is not None:
+            kwargs["export_folder"] = opt("ExportFolder")
+        if opt("TempFolder") is not None:
+            kwargs["temp_folder"] = opt("TempFolder")
+        if opt("FetchSize") is not None:
+            kwargs["fetch_size"] = parse_int(opt("FetchSize"), section=MAIN_SECTION, key="FetchSize")
+        if opt("PreviewRow") is not None:
+            kwargs["preview_row"] = parse_int(opt("PreviewRow"), section=MAIN_SECTION, key="PreviewRow")
+        if opt("ForceMakeDir") is not None:
+            kwargs["force_make_dir"] = parse_bool(
+                opt("ForceMakeDir"), section=MAIN_SECTION, key="ForceMakeDir"
+            )
+        if opt("RowIDColumn") is not None:
+            kwargs["row_id_column"] = opt("RowIDColumn")
+        if opt("DataDateColumn") is not None:
+            kwargs["data_date_column"] = opt("DataDateColumn")
+        if opt("LogFile") is not None:
+            kwargs["log_file"] = opt("LogFile")
+        cfg = cls(**kwargs)  # type: ignore[arg-type]
+        if cfg.fetch_size <= 0:
+            raise ConfigError(f"[{MAIN_SECTION}] FetchSize must be > 0, got {cfg.fetch_size}")
+        if cfg.preview_row <= 0:
+            raise ConfigError(f"[{MAIN_SECTION}] PreviewRow must be > 0, got {cfg.preview_row}")
+        return cfg
+
+
+_MASK = "******"
+
+
+@dataclass(frozen=True)
+class DBConfig:
+    """One DB section of config.ini. Password is excluded from repr; use safe_items() for logs."""
+
+    section: str
+    name: str
+    type: str
+    connection_string: Optional[str] = None
+    dsn: Optional[str] = None
+    host: Optional[str] = None
+    port: Optional[int] = None
+    database: Optional[str] = None
+    service: Optional[str] = None
+    sid: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = field(default=None, repr=False)
+    encoding: Optional[str] = None
+    driver: Optional[str] = None  # ODBC driver name override, e.g. "ODBC Driver 17 for SQL Server"
+
+    @classmethod
+    def from_reader(cls, reader: ConfigReader, section: str) -> "DBConfig":
+        if not reader.has_section(section):
+            raise ConfigError(f"DB section [{section}] not found in {reader.path}")
+        if section.lower() == MAIN_SECTION.lower():
+            raise ConfigError(f"[{MAIN_SECTION}] is not a DB section")
+
+        def opt(key: str) -> Optional[str]:
+            value = reader.get(section, key)
+            return value.strip() if value is not None and value.strip() != "" else None
+
+        connection_string = opt("ConnectionString")
+        dsn = opt("DSN")
+        raw_type = opt("Type")
+        if raw_type is not None:
+            db_type = raw_type.lower()
+            if db_type not in KNOWN_DB_TYPES:
+                raise ConfigError(
+                    f"[{section}] Type={raw_type!r} is not supported "
+                    f"(known: {', '.join(sorted(KNOWN_DB_TYPES))})"
+                )
+        elif connection_string is not None or dsn is not None:
+            db_type = "odbc"
+        else:
+            raise ConfigError(f"[{section}] Type is required (or provide ConnectionString/DSN)")
+
+        # Password wins over PasswordBase64 when both are present.
+        password = opt("Password")
+        password_b64 = opt("PasswordBase64")
+        if password is None and password_b64 is not None:
+            try:
+                password = base64.b64decode(password_b64, validate=True).decode("utf-8")
+            except (ValueError, UnicodeDecodeError) as exc:
+                raise ConfigError(
+                    f"[{section}] PasswordBase64 is not valid base64-encoded UTF-8: {exc}"
+                ) from None
+
+        port_value = opt("Port")
+        return cls(
+            section=section,
+            name=opt("Name") or section,
+            type=db_type,
+            connection_string=connection_string,
+            dsn=dsn,
+            host=opt("Host"),
+            port=parse_int(port_value, section=section, key="Port") if port_value else None,
+            database=opt("Database"),
+            service=opt("Service"),
+            sid=opt("SID"),
+            username=opt("Username"),
+            password=password,
+            encoding=opt("Encoding"),
+            driver=opt("Driver"),
+        )
+
+    def safe_items(self) -> List[Tuple[str, str]]:
+        """(key, value) pairs for DATABASE | PROPERTY logging, password masked, Nones skipped."""
+        out: List[Tuple[str, str]] = []
+        for f in fields(self):
+            value = getattr(self, f.name)
+            if value is None:
+                continue
+            out.append((f.name, _MASK if f.name == "password" else str(value)))
+        return out