lorebase-scribe 0.2.3__py3-none-any.whl

lorebase_scribe/sources/records.py

@@ -0,0 +1,298 @@
+"""Readers of Sources whose rows are records: JSON documents, JSON Lines and Parquet files.
+
+The connection's value is a local path (or a `file:` URL) under the `allowed_roots` of the
+connector's settings section, opened through the guards of `access` (no symbolic link
+followed after the roots check, regular files only).
+
+- `json`: the document is parsed whole (at most `scribe.sources.json_files.max_bytes`); its
+  records are the array at `records_path` (dotted keys, `data.items`), or the document itself
+  when it is an array. Locators are `file.json:<record number>`.
+- `jsonl`: one object per line, streamed; lines are at most `max_line_bytes`, blank lines are
+  skipped. Locators are `file.jsonl:<line number>`.
+- `parquet`: needs pyarrow (`lorebase-scribe[parquet]`); the file is streamed in batches of
+  `scribe.sources.parquet.batch_rows` rows, never read whole. Locators are
+  `file.parquet:<row number>`.
+
+Values keep their JSON (or Arrow) types: nested objects and arrays are JSON values, which a
+`json` Attribute stores as they are and textual Attributes receive as canonical JSON text. With
+`flatten_separator`, nested objects become columns named `parent<separator>child` instead
+(arrays stay values). Records have no fixed columns: a key missing from a record is null
+there (Parquet columns come from the file schema). Incremental reads compare the watermark
+column with the previous watermark natively, or as text when the types differ.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import AsyncIterator, Iterator, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from lorebase_core.model import Source
+from lorebase_scribe.settings import JsonSourceSettings, ParquetSourceSettings
+from lorebase_scribe.sources.access import (
+    READ_CHUNK,
+    SourceReadError,
+    local_path,
+    open_local,
+    read_bounded,
+    resolve_location,
+)
+from lorebase_scribe.sources.mapping import Row, SourceDefinitionError, text_of
+
+JSON_SECTION = "scribe.sources.json_files"
+PARQUET_SECTION = "scribe.sources.parquet"
+PARQUET_EXTRA = "lorebase-scribe[parquet]"
+
+
+# Record helpers -------------------------------------------------------------------------------
+
+
+def value_at(document: Any, path: str) -> Any:
+    """The value at a dotted path of nested objects; `KeyError` when a step is missing."""
+    node = document
+    for part in path.split("."):
+        if not isinstance(node, dict) or part not in node:
+            raise KeyError(path)
+        node = node[part]
+    return node
+
+
+def records_at(document: Any, path: str | None, where: str) -> list[Mapping[str, Any]]:
+    """The records of a parsed document: the array at `path`, or the document itself."""
+    node = document
+    if path is not None:
+        try:
+            node = value_at(document, path)
+        except KeyError:
+            raise SourceDefinitionError(f"{where}: no {path!r} in the document") from None
+        if node is None:
+            return []
+    if not isinstance(node, list):
+        what = "the document" if path is None else repr(path)
+        hint = "" if path is not None else " (set records_path)"
+        raise SourceDefinitionError(f"{where}: {what} is not an array of records{hint}")
+    for index, record in enumerate(node, start=1):
+        if not isinstance(record, dict):
+            raise SourceDefinitionError(f"{where}: record {index} is not an object")
+    return node
+
+
+def flatten(record: Mapping[str, Any], separator: str | None) -> dict[str, Any]:
+    """The record with nested objects as `parent<separator>child` columns; unchanged (a copy)
+    without a separator. Empty objects and arrays stay values."""
+    if separator is None:
+        return dict(record)
+    flat: dict[str, Any] = {}
+
+    def walk(prefix: str, node: Mapping[str, Any]) -> None:
+        for key, value in node.items():
+            name = f"{prefix}{separator}{key}" if prefix else str(key)
+            if isinstance(value, dict) and value:
+                walk(name, value)
+            else:
+                flat[name] = value
+
+    walk("", record)
+    return flat
+
+
+def after(value: Any, since: Any) -> bool:
+    """Whether a watermark value is greater than `since` (natively, else as text)."""
+    if value is None or value == "":
+        return False
+    try:
+        return bool(value > since)
+    except TypeError:
+        return text_of(value) > text_of(since)
+
+
+def keep(row: Row, source: Source, since: Any) -> bool:
+    """Whether an incremental read keeps the row (always, without a previous watermark)."""
+    column = source.watermark_column
+    return since is None or column is None or after(row.get(column), since)
+
+
+# JSON and JSON Lines --------------------------------------------------------------------------
+
+
+@dataclass
+class JsonConnector:
+    """A JSON document holding an array of records."""
+
+    source: Source
+    settings: JsonSourceSettings
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return ()
+
+    def _read(self, path: Path) -> bytes:
+        descriptor = open_local(path, self.settings.allowed_roots, JSON_SECTION)
+        try:
+            return read_bounded(
+                descriptor, path.name, self.settings.max_bytes, f"{JSON_SECTION}.max_bytes"
+            )
+        except OSError as error:
+            raise SourceReadError(f"{path.name}: {error.strerror}") from None
+        finally:
+            os.close(descriptor)
+
+    async def rows(self, since: Any) -> AsyncIterator[tuple[str, Row]]:
+        path = local_path(resolve_location(self.source), "JSON")
+        data = await asyncio.to_thread(self._read, path)
+        try:
+            document = json.loads(data)
+        except ValueError as error:
+            raise SourceDefinitionError(f"{path.name}: not valid JSON ({error})") from None
+        separator = self.source.flatten_separator
+        records = records_at(document, self.source.records_path, path.name)
+        for number, record in enumerate(records, start=1):
+            row = flatten(record, separator)
+            if keep(row, self.source, since):
+                yield f"{path.name}:{number}", row
+
+
+@dataclass
+class JsonLinesConnector:
+    """A JSON Lines file: one object per line, streamed."""
+
+    source: Source
+    settings: JsonSourceSettings
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return ()
+
+    async def _lines(self, descriptor: int, name: str) -> AsyncIterator[tuple[int, bytes]]:
+        """Numbered lines, read `READ_CHUNK` bytes at a time; none longer than the limit."""
+        limit = self.settings.max_line_bytes
+        buffer = b""
+        number = 0
+        while True:
+            try:
+                chunk = await asyncio.to_thread(os.read, descriptor, READ_CHUNK)
+            except OSError as error:
+                raise SourceReadError(f"{name}: {error.strerror}") from None
+            if not chunk:
+                if buffer:  # a last line without a newline
+                    yield number + 1, buffer
+                return
+            *complete, buffer = (buffer + chunk).split(b"\n")
+            for line in complete:
+                number += 1
+                if len(line) > limit:
+                    raise self._too_long(name, number)
+                yield number, line
+            if len(buffer) > limit:
+                raise self._too_long(name, number + 1)
+
+    def _too_long(self, name: str, number: int) -> SourceDefinitionError:
+        return SourceDefinitionError(
+            f"{name}: line {number} is longer than the {self.settings.max_line_bytes} bytes "
+            f"allowed by {JSON_SECTION}.max_line_bytes"
+        )
+
+    async def rows(self, since: Any) -> AsyncIterator[tuple[str, Row]]:
+        path = local_path(resolve_location(self.source), "JSON Lines")
+        descriptor = await asyncio.to_thread(
+            open_local, path, self.settings.allowed_roots, JSON_SECTION
+        )
+        separator = self.source.flatten_separator
+        try:
+            async for number, line in self._lines(descriptor, path.name):
+                if number == 1:
+                    line = line.removeprefix(b"\xef\xbb\xbf")
+                if not line.strip():
+                    continue
+                try:
+                    record = json.loads(line)
+                except ValueError:
+                    raise SourceDefinitionError(
+                        f"{path.name}: line {number} is not valid JSON"
+                    ) from None
+                if not isinstance(record, dict):
+                    raise SourceDefinitionError(f"{path.name}: line {number} is not an object")
+                row = flatten(record, separator)
+                if keep(row, self.source, since):
+                    yield f"{path.name}:{number}", row
+        finally:
+            os.close(descriptor)
+
+
+# Parquet --------------------------------------------------------------------------------------
+
+
+def _pyarrow() -> tuple[ModuleType, ModuleType]:
+    """`pyarrow` and `pyarrow.parquet`, or a definition error naming the extra."""
+    try:
+        import pyarrow  # type: ignore[import-untyped]
+        import pyarrow.parquet as parquet  # type: ignore[import-untyped]
+    except ImportError:
+        raise SourceDefinitionError(
+            f"parquet Sources need pyarrow: install {PARQUET_EXTRA}"
+        ) from None
+    return pyarrow, parquet
+
+
+def _column_names(pyarrow: ModuleType, schema: Any, separator: str | None) -> tuple[str, ...]:
+    """Column names of an Arrow schema; struct fields flattened as rows are."""
+
+    def names(field: Any, prefix: str) -> Iterator[str]:
+        name = f"{prefix}{separator}{field.name}" if prefix else str(field.name)
+        if separator is not None and pyarrow.types.is_struct(field.type) and field.type.num_fields:
+            for index in range(field.type.num_fields):
+                yield from names(field.type.field(index), name)
+        else:
+            yield name
+
+    return tuple(name for field in schema for name in names(field, ""))
+
+
+@dataclass
+class ParquetConnector:
+    """A Parquet file, read batch by batch."""
+
+    source: Source
+    settings: ParquetSourceSettings
+    _columns: tuple[str, ...] = ()
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return self._columns
+
+    async def rows(self, since: Any) -> AsyncIterator[tuple[str, Row]]:
+        pyarrow, parquet = _pyarrow()
+        path = local_path(resolve_location(self.source), "Parquet")
+        descriptor = await asyncio.to_thread(
+            open_local, path, self.settings.allowed_roots, PARQUET_SECTION
+        )
+        separator = self.source.flatten_separator
+        with os.fdopen(descriptor, "rb") as handle:
+            try:
+                file = parquet.ParquetFile(handle)
+                self._columns = _column_names(pyarrow, file.schema_arrow, separator)
+                batches = file.iter_batches(batch_size=self.settings.batch_rows)
+            except ValueError as error:  # pyarrow.ArrowInvalid: not a Parquet file
+                raise SourceDefinitionError(f"{path.name}: not a Parquet file ({error})") from None
+            except OSError as error:
+                raise SourceReadError(f"{path.name}: {error}") from None
+            number = 0
+            while True:
+                try:
+                    batch = await asyncio.to_thread(next, batches, None)
+                except ValueError as error:
+                    raise SourceDefinitionError(f"{path.name}: {error}") from None
+                except OSError as error:
+                    raise SourceReadError(f"{path.name}: {error}") from None
+                if batch is None:
+                    return
+                for record in batch.to_pylist():
+                    number += 1
+                    row = flatten(record, separator)
+                    if keep(row, self.source, since):
+                        yield f"{path.name}:{number}", row

lorebase_scribe/sources/sql.py

@@ -0,0 +1,332 @@
+"""MySQL, MariaDB and SQL Server Sources: the `table` or `query` of the Source, filtered by
+`scope_filter`, read like a Postgres Source (see `connectors`) and fetched `fetch_rows` at a
+time. Locators are `table:<row number>` (the table name), or `query:<row number>`.
+
+- `mysql_table`, `mysql_query`: MySQL 5.7+ and MariaDB 10.x through asyncmy (Apache-2.0, async,
+  prebuilt wheels), installed with `lorebase-scribe[mysql]`. The session is read-only and
+  bounded by `max_execution_time` (`max_statement_time` on MariaDB). The connection value is
+  `mysql://user:password@host:3306/database` (`mariadb://` works too).
+- `mssql_table`, `mssql_query`: SQL Server 2017+ and Azure SQL through pymssql (LGPL-2.1,
+  FreeTDS bundled in the wheels, so no ODBC driver is needed), installed with
+  `lorebase-scribe[mssql]`. pymssql is blocking: every driver call runs in a worker thread.
+  SQL Server has no read-only transaction, so the login must only be able to read. The
+  connection value is `mssql://user:password@host:1433/database`.
+
+A `query` is wrapped as `SELECT * FROM (<query>) AS lorebase_source` and a trailing `;` is
+removed. SQL Server refuses an `ORDER BY` in a derived table unless it has `TOP` or `OFFSET`, so
+a query of that kind whose top level ends in `ORDER BY` without either gets `OFFSET 0 ROWS`
+appended (valid from SQL Server 2012, and it does not limit the rows).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import math
+import re
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextlib import contextmanager
+from datetime import datetime
+from typing import Any, ClassVar
+
+from sqlalchemy import URL, create_engine, make_url, text
+from sqlalchemy.exc import ArgumentError, DBAPIError
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.pool import NullPool
+
+from lorebase_core.model import Source
+from lorebase_core.model.source import SourceType
+from lorebase_scribe.sources.access import SourceReadError, resolve_location
+from lorebase_scribe.sources.mapping import Row, SourceDefinitionError
+
+__all__ = ["MssqlConnector", "MysqlConnector", "quote_identifier"]
+
+APPLICATION_NAME = "lorebase-scribe"
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_$]*$")
+_MAX_ERROR_CHARS = 300
+
+
+def quote_identifier(name: str, opening: str = '"', closing: str = '"') -> str:
+    """A dotted SQL identifier, each part checked and quoted."""
+    parts = name.split(".")
+    if not parts or any(_IDENTIFIER.fullmatch(part) is None for part in parts):
+        raise SourceDefinitionError(f"not a plain SQL identifier: {name!r}")
+    return ".".join(f"{opening}{part}{closing}" for part in parts)
+
+
+_WORD = re.compile(r"[A-Za-z_][A-Za-z0-9_$#@]*")
+_OPAQUE = re.compile(
+    r"'(?:[^']|'')*'|\[(?:[^\]]|\]\])*\]|\"(?:[^\"]|\"\")*\"|--[^\n]*|/\*.*?\*/", re.S
+)
+
+
+def top_level_words(query: str) -> list[tuple[str, int]]:
+    """Upper-cased keywords of `query` with their offsets, outside parentheses, string
+    literals, quoted identifiers and comments; a name after a dot (`t.top`) is not one."""
+    words: list[tuple[str, int]] = []
+    depth = 0
+    index = 0
+    while index < len(query):
+        quoted = _OPAQUE.match(query, index)
+        if quoted is not None:
+            index = quoted.end()
+            continue
+        char = query[index]
+        if char == "(":
+            depth += 1
+        elif char == ")":
+            depth = max(0, depth - 1)
+        elif depth == 0 and (word := _WORD.match(query, index)) is not None:
+            if index == 0 or query[index - 1] != ".":
+                words.append((word.group().upper(), index))
+            index = word.end()
+            continue
+        index += 1
+    return words
+
+
+_SET_OPERATORS = frozenset({"UNION", "INTERSECT", "EXCEPT"})
+
+
+def _has_top(names: list[str]) -> bool:
+    """Whether the (single) SELECT of the query has a `TOP` clause: the word right after
+    `SELECT` and `DISTINCT` or `ALL`, so an alias named top does not count."""
+    if "SELECT" not in names:
+        return False
+    position = names.index("SELECT") + 1
+    while position < len(names) and names[position] in ("DISTINCT", "ALL"):
+        position += 1
+    return position < len(names) and names[position] == "TOP"
+
+
+def mssql_orderable(query: str) -> str:
+    """`query` made valid as a derived table: a top-level trailing `ORDER BY` gets
+    `OFFSET 0 ROWS`, which keeps the order and all the rows. Left alone: a query without that
+    clause, one with `TOP` (without a set operator, whose `ORDER BY` covers all its SELECTs),
+    and one with `OFFSET`, `FETCH` or `FOR` after the `ORDER BY`. A trailing `OPTION (...)`
+    stays last."""
+    words = top_level_words(query)
+    names = [name for name, _ in words]
+    last = next(
+        (i for i in range(len(names) - 1, 0, -1) if names[i - 1 : i + 1] == ["ORDER", "BY"]), None
+    )
+    if last is None:
+        return query
+    if not _SET_OPERATORS.intersection(names) and _has_top(names):
+        return query
+    after = names[last + 1 :]
+    if {"OFFSET", "FETCH", "FOR"}.intersection(after):
+        return query
+    if "OPTION" in after:
+        at = words[last + 1 + after.index("OPTION")][1]
+        return f"{query[:at].rstrip()}\nOFFSET 0 ROWS {query[at:]}"
+    return f"{query}\nOFFSET 0 ROWS"
+
+
+def _require_driver(module: str, extra: str, label: str) -> None:
+    try:
+        importlib.import_module(module)
+    except ImportError:
+        raise SourceDefinitionError(
+            f"{label} Sources need {module}: install lorebase-scribe[{extra}]"
+        ) from None
+
+
+def _driver_url(location: str, schemes: frozenset[str], driver: str, hint: str) -> URL:
+    """The URL of `location` on `driver`; refuses other schemes without echoing the value."""
+    try:
+        parsed = make_url(location)
+    except ArgumentError:
+        raise SourceDefinitionError("connection: not a valid database URL") from None
+    if parsed.drivername not in schemes:
+        raise SourceDefinitionError(
+            f"connection: unsupported database driver {parsed.drivername!r}; use {hint}://"
+        )
+    return parsed.set(drivername=driver)
+
+
+@contextmanager
+def _read_errors(name: str) -> Iterator[None]:
+    """Driver and network failures as `SourceReadError`, naming no connection value."""
+    try:
+        yield
+    except DBAPIError as error:
+        detail = " ".join(str(error.orig).split())[:_MAX_ERROR_CHARS]
+        raise SourceReadError(f"{name}: {type(error.orig).__name__}: {detail}") from None
+    except (OSError, TimeoutError) as error:
+        raise SourceReadError(f"{name}: {type(error).__name__}: {error}") from None
+
+
+class _SqlConnector:
+    """Statement building shared by the SQL connectors; subclasses read."""
+
+    #: `mysql` or `mssql`: the URL scheme to use, the extra to install, the settings name.
+    label: ClassVar[str]
+    query_type: ClassVar[SourceType]
+    opening: ClassVar[str]
+    closing: ClassVar[str]
+    schemes: ClassVar[frozenset[str]]
+    driver: ClassVar[str]
+    #: Replaced by tests to read through a fake engine.
+    engine_factory: ClassVar[Callable[..., Any]]
+
+    def __init__(self, source: Source, settings: Any) -> None:
+        self.source = source
+        self.settings = settings
+        self._columns: tuple[str, ...] = ()
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return self._columns
+
+    def _quote(self, name: str) -> str:
+        return quote_identifier(name, self.opening, self.closing)
+
+    def _derived(self, query: str) -> str:
+        """The query as the body of a derived table (unchanged unless a dialect needs more)."""
+        return query
+
+    def statement(self, since: Any) -> tuple[str, dict[str, Any], str]:
+        """SQL text, parameters and the relation name used in row locators."""
+        source = self.source
+        if source.type is self.query_type:
+            query = (source.query or "").strip().rstrip(";").rstrip()
+            if not query:
+                raise SourceDefinitionError(f"{self.query_type.value} Sources need a query")
+            body = f"SELECT * FROM ({self._derived(query)}) AS lorebase_source"
+            name = "query"
+        else:
+            name = source.table or source.api_name.rsplit(".", 1)[-1]
+            body = f"SELECT * FROM {self._quote(name)} AS lorebase_source"
+        conditions: list[str] = []
+        parameters: dict[str, Any] = {}
+        if source.scope_filter:
+            conditions.append(f"({source.scope_filter})")
+        order = ""
+        if source.watermark_column is not None:
+            column = self._quote(source.watermark_column)
+            if since is not None:
+                conditions.append(f"{column} > :since")
+                parameters["since"] = since
+            order = f" ORDER BY {column}"
+        where = f" WHERE {' AND '.join(conditions)}" if conditions else ""
+        return body + where + order, parameters, name
+
+    def _url(self) -> URL:
+        _require_driver(self.driver, self.label, self.label)
+        return _driver_url(
+            resolve_location(self.source),
+            self.schemes,
+            f"{self.label}+{self.driver}",
+            self.label,
+        )
+
+
+class MysqlConnector(_SqlConnector):
+    """A MySQL or MariaDB table or query, streamed through a server-side cursor in a
+    read-only session."""
+
+    label = "mysql"
+    query_type = SourceType.MYSQL_QUERY
+    opening = closing = "`"
+    driver = "asyncmy"
+    schemes = frozenset({"mysql", "mariadb", "mysql+asyncmy", "mariadb+asyncmy"})
+    engine_factory = staticmethod(create_async_engine)
+
+    async def rows(self, since: Any) -> AsyncIterator[tuple[str, Row]]:
+        sql, parameters, name = self.statement(since)
+        url = self._url()
+        settings = self.settings
+        connect_args: dict[str, Any] = {
+            "connect_timeout": settings.connect_timeout_s,
+            "program_name": APPLICATION_NAME,
+        }
+        if "charset" not in url.query:
+            connect_args["charset"] = "utf8mb4"
+        engine = self.engine_factory(url, poolclass=NullPool, connect_args=connect_args)
+        try:
+            with _read_errors(name):
+                async with engine.connect() as connection:
+                    # Session-wide, so that it holds for the transaction below; the implicit
+                    # transaction the first statement opens is ended before the read.
+                    await connection.execute(text("SET SESSION TRANSACTION READ ONLY"))
+                    timeout = int(settings.statement_timeout_ms)
+                    if getattr(connection.dialect, "is_mariadb", False):
+                        seconds = math.ceil(timeout / 1000)
+                        limit = f"SET SESSION max_statement_time = {seconds}"
+                    else:
+                        limit = f"SET SESSION max_execution_time = {timeout}"
+                    await connection.execute(text(limit))
+                    await connection.rollback()
+                    async with connection.begin():
+                        result = await connection.stream(text(sql), parameters)
+                        self._columns = tuple(result.keys())
+                        number = 0
+                        async for partition in result.mappings().partitions(settings.fetch_rows):
+                            for row in partition:
+                                number += 1
+                                yield f"{name}:{number}", dict(row)
+        finally:
+            await engine.dispose()
+
+
+class MssqlConnector(_SqlConnector):
+    """A SQL Server table or query; the blocking driver runs in worker threads."""
+
+    label = "mssql"
+    query_type = SourceType.MSSQL_QUERY
+    opening, closing = "[", "]"
+    driver = "pymssql"
+    schemes = frozenset({"mssql", "sqlserver", "mssql+pymssql"})
+    engine_factory = staticmethod(lambda url, **options: create_engine(url, **options))
+
+    def _derived(self, query: str) -> str:
+        return mssql_orderable(query)
+
+    def statement(self, since: Any) -> tuple[str, dict[str, Any], str]:
+        sql, parameters, name = super().statement(since)
+        if isinstance(parameters.get("since"), datetime):
+            # pymssql binds a datetime with millisecond precision; SQL Server converts the
+            # text to the type of the watermark column, microseconds included.
+            parameters["since"] = parameters["since"].isoformat(sep=" ")
+        return sql, parameters, name
+
+    async def rows(self, since: Any) -> AsyncIterator[tuple[str, Row]]:
+        sql, parameters, name = self.statement(since)
+        url = self._url()
+        settings = self.settings
+        timeout_ms = int(settings.statement_timeout_ms)
+        engine = self.engine_factory(
+            url,
+            poolclass=NullPool,
+            connect_args={
+                "login_timeout": math.ceil(settings.connect_timeout_s),
+                "timeout": math.ceil(timeout_ms / 1000),
+                "appname": APPLICATION_NAME,
+                # datetime2 keeps its microseconds: a watermark must not lose precision.
+                "use_datetime2": True,
+            },
+        )
+        connection: Any = None
+        try:
+            with _read_errors(name):
+                connection = await asyncio.to_thread(engine.connect)
+                await asyncio.to_thread(connection.execute, text(f"SET LOCK_TIMEOUT {timeout_ms}"))
+                result = await asyncio.to_thread(connection.execute, text(sql), parameters)
+                self._columns = tuple(result.keys())
+                rows = result.mappings()
+                number = 0
+                while batch := await asyncio.to_thread(rows.fetchmany, settings.fetch_rows):
+                    for row in batch:
+                        number += 1
+                        yield f"{name}:{number}", dict(row)
+        finally:
+            await asyncio.shield(asyncio.to_thread(self._close, engine, connection))
+
+    @staticmethod
+    def _close(engine: Any, connection: Any) -> None:
+        try:
+            if connection is not None:
+                connection.close()
+        finally:
+            engine.dispose()