sql-query-mcp 0.3.0__tar.gz → 0.4.1__tar.gz

{sql_query_mcp-0.3.0/sql_query_mcp.egg-info → sql_query_mcp-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-query-mcp
-Version: 0.3.0
+Version: 0.4.1
 Summary: Read-only SQL MCP server for PostgreSQL and MySQL.
 Author: Andy Wang
 License-Expression: MIT
@@ -62,10 +62,11 @@ without exposing raw connection strings or flattening engine-specific concepts.
 ## What AI can do with it
 
 The current tool set focuses on database discovery, controlled query workflows,
-asynchronous read-only queries, and one narrow local file import path. You can
-use it to help an AI assistant understand structure before it generates SQL,
-runs a bounded query, starts a long-running read-only query, or imports a
-prepared CSV/XLSX file into an existing table.
+asynchronous read-only queries, batched query result exports, and one narrow
+local file import path. You can use it to help an AI assistant understand
+structure before it generates SQL, runs a bounded query, starts a long-running
+read-only query, exports PostgreSQL or MySQL results to a local file, or imports
+a prepared CSV/XLSX file into an existing table.
 
 MySQL and Hive support `explain_query`. Hive uses `EXPLAIN` and
 `EXPLAIN ANALYZE` for `explain_query`.
@@ -83,19 +84,22 @@ MySQL and Hive support `explain_query`. Hive uses `EXPLAIN` and
 | `cancel_query(query_id)` | Yes | Yes | Yes | Cancel running async queries |
 | `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Yes | Inspect query plans |
 | `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Yes | Fetch small table samples |
+| `export_query_file(connection_id, sql, output_path, format?, limit?, export_all?, file_name?, overwrite?)` | Yes | Yes | No | Export query results to local CSV/XLSX files |
 | `import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?)` | Yes | Yes | Yes | Import local CSV/XLSX files |
 
 These tools are useful for tasks such as listing namespaces, inspecting table
 definitions, reviewing indexes, sampling records, running short read-only
 queries with `run_select`, running long read-only queries with `start_query`,
 `get_query`, and `cancel_query`, analyzing read-only queries with `EXPLAIN`, and
-importing prepared local files. For full request and response details, see
+exporting PostgreSQL or MySQL query results to local CSV/XLSX files. You can
+also import prepared local files. For full request and response details, see
 `docs/api-reference.md` (Chinese).
 
 ## How boundaries are constrained
 
 The product boundary is intentionally narrow today. PostgreSQL, MySQL, and Hive
-are available today. Query tools remain read-only, and the only write path is a
+are available today. Query tools remain read-only, PostgreSQL and MySQL query
+results can be exported to local files, and the only database write path is a
 controlled local CSV/XLSX import into existing tables.
 
 The service keeps those boundaries explicit in a few ways.
@@ -112,6 +116,11 @@ The service keeps those boundaries explicit in a few ways.
   queries.
 - The server accepts only `SELECT` and `WITH ... SELECT`, rejects comments and
   multi-statement input, and records audit logs for each call.
+- `export_query_file` writes files on the MCP server machine. It is synchronous
+  but reads database rows and writes CSV/XLSX files in batches. Large exports can
+  still hit your MCP client's tool timeout. For XLSX output, UUID values are
+  written as text and timezone-aware datetime values are written without the
+  timezone. Hive export is not supported yet.
 - `import_table_file` doesn't accept raw SQL. It inserts only file columns whose
   headers exactly match existing table columns.
 - Hive `import_table_file` is intended for small files only and rejects files

{sql_query_mcp-0.3.0 → sql_query_mcp-0.4.1}/README.md

@@ -30,10 +30,11 @@ without exposing raw connection strings or flattening engine-specific concepts.
 ## What AI can do with it
 
 The current tool set focuses on database discovery, controlled query workflows,
-asynchronous read-only queries, and one narrow local file import path. You can
-use it to help an AI assistant understand structure before it generates SQL,
-runs a bounded query, starts a long-running read-only query, or imports a
-prepared CSV/XLSX file into an existing table.
+asynchronous read-only queries, batched query result exports, and one narrow
+local file import path. You can use it to help an AI assistant understand
+structure before it generates SQL, runs a bounded query, starts a long-running
+read-only query, exports PostgreSQL or MySQL results to a local file, or imports
+a prepared CSV/XLSX file into an existing table.
 
 MySQL and Hive support `explain_query`. Hive uses `EXPLAIN` and
 `EXPLAIN ANALYZE` for `explain_query`.
@@ -51,19 +52,22 @@ MySQL and Hive support `explain_query`. Hive uses `EXPLAIN` and
 | `cancel_query(query_id)` | Yes | Yes | Yes | Cancel running async queries |
 | `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Yes | Inspect query plans |
 | `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Yes | Fetch small table samples |
+| `export_query_file(connection_id, sql, output_path, format?, limit?, export_all?, file_name?, overwrite?)` | Yes | Yes | No | Export query results to local CSV/XLSX files |
 | `import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?)` | Yes | Yes | Yes | Import local CSV/XLSX files |
 
 These tools are useful for tasks such as listing namespaces, inspecting table
 definitions, reviewing indexes, sampling records, running short read-only
 queries with `run_select`, running long read-only queries with `start_query`,
 `get_query`, and `cancel_query`, analyzing read-only queries with `EXPLAIN`, and
-importing prepared local files. For full request and response details, see
+exporting PostgreSQL or MySQL query results to local CSV/XLSX files. You can
+also import prepared local files. For full request and response details, see
 `docs/api-reference.md` (Chinese).
 
 ## How boundaries are constrained
 
 The product boundary is intentionally narrow today. PostgreSQL, MySQL, and Hive
-are available today. Query tools remain read-only, and the only write path is a
+are available today. Query tools remain read-only, PostgreSQL and MySQL query
+results can be exported to local files, and the only database write path is a
 controlled local CSV/XLSX import into existing tables.
 
 The service keeps those boundaries explicit in a few ways.
@@ -80,6 +84,11 @@ The service keeps those boundaries explicit in a few ways.
   queries.
 - The server accepts only `SELECT` and `WITH ... SELECT`, rejects comments and
   multi-statement input, and records audit logs for each call.
+- `export_query_file` writes files on the MCP server machine. It is synchronous
+  but reads database rows and writes CSV/XLSX files in batches. Large exports can
+  still hit your MCP client's tool timeout. For XLSX output, UUID values are
+  written as text and timezone-aware datetime values are written without the
+  timezone. Hive export is not supported yet.
 - `import_table_file` doesn't accept raw SQL. It inserts only file columns whose
   headers exactly match existing table columns.
 - Hive `import_table_file` is intended for small files only and rejects files

{sql_query_mcp-0.3.0 → sql_query_mcp-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sql-query-mcp"
-version = "0.3.0"
+version = "0.4.1"
 description = "Read-only SQL MCP server for PostgreSQL and MySQL."
 readme = "README.md"
 requires-python = ">=3.10"

{sql_query_mcp-0.3.0 → sql_query_mcp-0.4.1}/sql_query_mcp/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.4"
+__version__ = "0.4.1"

{sql_query_mcp-0.3.0 → sql_query_mcp-0.4.1}/sql_query_mcp/adapters/hive.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from contextlib import contextmanager
-from typing import Iterator, List
+from typing import Any, Iterator, List
 from urllib.parse import parse_qs, unquote, urlparse
 
 try:
@@ -52,6 +52,10 @@ class HiveAdapter:
     def column_names(self, description) -> List[str]:
         return [column[0] for column in (description or [])]
 
+    def normalize_identifier(self, value: str) -> str:
+        # Hive table and column identifiers are case-insensitive.
+        return value.casefold()
+
     def normalize_rows(self, rows, columns: List[str]) -> List[dict]:
         return [dict(zip(columns, row)) for row in rows]
 
@@ -80,7 +84,7 @@ class HiveAdapter:
         columns = []
         in_partitions = False
         for row in rows:
-            name = self._first_value(row)
+            name = self._describe_value(row, "col_name", 0)
             if not name:
                 continue
             if str(name).startswith("# Partition Information"):
@@ -88,9 +92,8 @@ class HiveAdapter:
                 continue
             if str(name).startswith("#"):
                 continue
-            values = self._row_values(row)
-            data_type = values[1] if len(values) > 1 else None
-            comment = values[2] if len(values) > 2 else None
+            data_type = self._describe_value(row, "data_type", 1)
+            comment = self._describe_value(row, "comment", 2)
             columns.append(
                 {
                     "column_name": name,
@@ -141,7 +144,13 @@ class HiveAdapter:
             return next(iter(row.values()))
         return row[0]
 
-    def _row_values(self, row):
-        if isinstance(row, dict):
-            return list(row.values())
-        return list(row)
+    def _describe_value(self, row, key: str, index: int) -> Any:
+        # Hive table and column identifiers are case-insensitive. DESCRIBE may
+        # return tuples or dict rows, so dict key lookup follows Hive semantics.
+        if not isinstance(row, dict):
+            return row[index] if len(row) > index else None
+        lowered_key = key.lower()
+        for existing_key, value in row.items():
+            if existing_key.lower() == lowered_key:
+                return value
+        return None

{sql_query_mcp-0.3.0 → sql_query_mcp-0.4.1}/sql_query_mcp/adapters/mysql.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 from contextlib import contextmanager
-from typing import Iterator, List
+from typing import Any, Iterator, List
 from urllib.parse import parse_qs, unquote, urlparse
 
 try:
@@ -42,6 +42,11 @@ class MySQLAdapter:
         with conn.cursor() as cur:
             cur.execute("SET SESSION max_execution_time = %s", (int(timeout_ms),))
 
+    def export_cursor(self, conn: object):
+        if pymysql is None:
+            raise ConfigurationError("缺少 PyMySQL 依赖，请先安装项目依赖。")
+        return conn.cursor(pymysql.cursors.SSDictCursor)
+
     def list_databases(self, conn: object) -> List[str]:
         with conn.cursor() as cur:
             cur.execute(
@@ -52,7 +57,7 @@ class MySQLAdapter:
                 ORDER BY schema_name
                 """
             )
-            return [row["database_name"] for row in cur.fetchall()]
+            return [_row_value(row, "database_name") for row in cur.fetchall()]
 
     def list_tables(self, conn: object, database: str):
         with conn.cursor() as cur:
@@ -65,7 +70,14 @@ class MySQLAdapter:
                 """,
                 (database,),
             )
-            return cur.fetchall()
+            return [
+                {
+                    "database_name": _row_value(row, "database_name"),
+                    "table_name": _row_value(row, "table_name"),
+                    "table_type": _row_value(row, "table_type"),
+                }
+                for row in cur.fetchall()
+            ]
 
     def describe_table(self, conn: object, database: str, table_name: str):
         with conn.cursor() as cur:
@@ -96,13 +108,13 @@ class MySQLAdapter:
         return {
             "columns": [
                 {
-                    "column_name": row["column_name"],
-                    "data_type": row["column_type"],
+                    "column_name": _row_value(row, "column_name"),
+                    "data_type": _row_value(row, "column_type"),
                     "udt_name": None,
-                    "nullable": row["is_nullable"] == "YES",
-                    "default": row["column_default"],
-                    "primary_key": row["column_key"] == "PRI",
-                    "extra": row["extra"],
+                    "nullable": _row_value(row, "is_nullable") == "YES",
+                    "default": _row_value(row, "column_default"),
+                    "primary_key": _row_value(row, "column_key") == "PRI",
+                    "extra": _row_value(row, "extra"),
                 }
                 for row in columns
             ],
@@ -131,7 +143,7 @@ class MySQLAdapter:
     def extract_plan(self, rows):
         if not rows:
             return []
-        plan = rows[0].get("EXPLAIN", [])
+        plan = _row_value(rows[0], "EXPLAIN")
         if isinstance(plan, str):
             try:
                 return json.loads(plan)
@@ -142,6 +154,11 @@ class MySQLAdapter:
     def column_names(self, description) -> List[str]:
         return [column[0] for column in (description or [])]
 
+    def normalize_identifier(self, value: str) -> str:
+        # MySQL column names, index names, and column aliases are
+        # case-insensitive on every platform.
+        return value.casefold()
+
     def _parse_dsn(self, dsn: str) -> dict:
         parsed = urlparse(dsn)
         if parsed.scheme not in {"mysql", "mysql+pymysql"}:
@@ -164,16 +181,29 @@ class MySQLAdapter:
     def _normalize_indexes(self, rows: List[dict]) -> List[dict]:
         grouped = {}
         for row in rows:
-            index_name = row["index_name"]
+            index_name = _row_value(row, "index_name")
             item = grouped.setdefault(
                 index_name,
                 {
                     "index_name": index_name,
                     "columns": [],
-                    "unique": row["non_unique"] == 0,
+                    "unique": _row_value(row, "non_unique") == 0,
                     "primary_key": index_name == "PRIMARY",
                     "definition": None,
                 },
             )
-            item["columns"].append(row["column_name"])
+            item["columns"].append(_row_value(row, "column_name"))
         return [grouped[name] for name in sorted(grouped)]
+
+
+def _row_value(row: dict, key: str) -> Any:
+    # MySQL column names, index names, and column aliases are case-insensitive,
+    # and drivers may expose information_schema labels as COLUMN_NAME or
+    # column_name. Keep this normalization local to the MySQL adapter.
+    if key in row:
+        return row[key]
+    lowered_key = key.lower()
+    for existing_key, value in row.items():
+        if existing_key.lower() == lowered_key:
+            return value
+    raise KeyError(key)

{sql_query_mcp-0.3.0 → sql_query_mcp-0.4.1}/sql_query_mcp/adapters/postgres.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from contextlib import contextmanager
+from uuid import uuid4
 from typing import Iterator, List
 
 try:
@@ -37,6 +38,19 @@ class PostgresAdapter:
         with conn.cursor() as cur:
             cur.execute("SELECT set_config('statement_timeout', %s, false)", (str(timeout_ms),))
 
+    @contextmanager
+    def export_cursor(self, conn: object) -> Iterator[object]:
+        previous_autocommit = getattr(conn, "autocommit", None)
+        if previous_autocommit is True:
+            conn.autocommit = False
+        try:
+            with conn.cursor(name=f"sql_query_mcp_export_{uuid4().hex}") as cur:
+                yield cur
+        finally:
+            if previous_autocommit is True:
+                conn.rollback()
+                conn.autocommit = True
+
     def list_schemas(self, conn: object) -> List[str]:
         with conn.cursor() as cur:
             cur.execute(
@@ -174,6 +188,11 @@ class PostgresAdapter:
     def column_names(self, description) -> List[str]:
         return [column.name for column in (description or [])]
 
+    def normalize_identifier(self, value: str) -> str:
+        # PostgreSQL quoted identifiers are case-sensitive, and this adapter
+        # quotes import columns with sql.Identifier, so header matching is exact.
+        return value
+
     def _get_pool(self, connection_id: str, dsn: str) -> ConnectionPool:
         if ConnectionPool is None or dict_row is None:
             raise ConfigurationError("缺少 psycopg / psycopg-pool 依赖，请先安装项目依赖。")

{sql_query_mcp-0.3.0 → sql_query_mcp-0.4.1}/sql_query_mcp/app.py

@@ -11,6 +11,7 @@ from .audit import AuditLogger
 from .config import load_config
 from .errors import SqlQueryMCPError
 from .executor import QueryExecutor
+from .exporter import QueryExporter
 from .importer import TableFileImporter
 from .introspection import MetadataService
 from .registry import ConnectionRegistry
@@ -22,6 +23,7 @@ def create_app() -> FastMCP:
     audit_logger = AuditLogger(app_config.settings.audit_log_path)
     metadata = MetadataService(registry, app_config.settings, audit_logger)
     executor = QueryExecutor(registry, app_config.settings, audit_logger)
+    exporter = QueryExporter(registry, app_config.settings, audit_logger)
     importer = TableFileImporter(registry, app_config.settings, audit_logger)
     async_queries = AsyncQueryService(registry, app_config.settings, audit_logger)
 
@@ -90,6 +92,32 @@ def create_app() -> FastMCP:
 
         return _run_tool(lambda: executor.get_table_sample(connection_id, table_name, schema, database, limit))
 
+    @mcp.tool()
+    def export_query_file(
+        connection_id: str,
+        sql: str,
+        output_path: str,
+        format: str = "csv",
+        limit: Optional[int] = 1000,
+        export_all: bool = False,
+        file_name: Optional[str] = None,
+        overwrite: bool = False,
+    ) -> dict:
+        """Export a read-only query result to a local CSV or XLSX file."""
+
+        return _run_tool(
+            lambda: exporter.export_query_file(
+                connection_id,
+                sql,
+                output_path,
+                format,
+                limit,
+                export_all,
+                file_name,
+                overwrite,
+            )
+        )
+
     @mcp.tool()
     def start_query(connection_id: str, sql: str, limit: Optional[int] = None) -> dict:
         """Start an asynchronous read-only SELECT or CTE query."""

sql_query_mcp-0.4.1/sql_query_mcp/exporter.py

@@ -0,0 +1,264 @@
+"""Controlled query result exports."""
+
+from __future__ import annotations
+
+import csv
+import time
+import uuid
+from datetime import datetime, time as datetime_time, timezone
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, cast
+
+try:
+    from openpyxl import Workbook
+except ImportError:  # pragma: no cover - runtime dependency
+    Workbook = None
+
+from .audit import AuditLogger
+from .config import ServerSettings
+from .errors import QueryExecutionError, sanitize_error_message
+from .validator import clamp_limit, summarize_sql, validate_select_sql
+
+EXPORT_BATCH_SIZE = 1000
+SUPPORTED_EXPORT_ENGINES = {"postgres", "mysql"}
+SUPPORTED_EXPORT_FORMATS = {"csv", "xlsx"}
+
+
+class QueryExporter:
+    """Export validated read-only query results to local files."""
+
+    def __init__(self, registry: Any, settings: ServerSettings, audit_logger: AuditLogger):
+        self._registry = registry
+        self._settings = settings
+        self._audit = audit_logger
+
+    def export_query_file(
+        self,
+        connection_id: str,
+        sql_text: str,
+        output_path: str,
+        format: str = "csv",
+        limit: Optional[int] = 1000,
+        export_all: bool = False,
+        file_name: Optional[str] = None,
+        overwrite: bool = False,
+    ) -> Dict[str, object]:
+        started = time.perf_counter()
+        config = None
+        final_path: Optional[Path] = None
+        row_count = 0
+        applied_limit = None
+        sql_summary = summarize_sql(sql_text)
+        normalized_format = str(format).lower().lstrip(".")
+
+        try:
+            if normalized_format not in SUPPORTED_EXPORT_FORMATS:
+                raise QueryExecutionError("导出格式仅支持 csv 和 xlsx。")
+            config = self._registry.get_connection_config(connection_id)
+            if config.engine not in SUPPORTED_EXPORT_ENGINES:
+                raise QueryExecutionError("export_query_file 首版仅支持 PostgreSQL 和 MySQL。")
+            cleaned_sql = validate_select_sql(sql_text, config.engine)
+            sql_summary = summarize_sql(cleaned_sql)
+            final_path = _resolve_output_file(
+                output_path,
+                normalized_format,
+                file_name=file_name,
+                overwrite=overwrite,
+            )
+            query = cleaned_sql
+            if not export_all:
+                applied_limit = clamp_limit(limit, 1000, self._settings.max_limit)
+                query = _build_exact_limited_query(cleaned_sql, applied_limit)
+
+            with self._registry.connection_from_config(config) as (conn, adapter):
+                _apply_statement_timeout(adapter, conn, self._settings.statement_timeout_ms)
+                with _open_export_cursor(adapter, conn) as cur:
+                    cur.execute(query)
+                    columns = adapter.column_names(cur.description)
+                    batches = _iter_batches(cur, columns, adapter)
+                    if normalized_format == "csv":
+                        row_count = _write_csv(final_path, columns, batches)
+                    else:
+                        row_count = _write_xlsx(final_path, columns, batches)
+
+            duration_ms = _elapsed_ms(started)
+            self._audit.log(
+                tool="export_query_file",
+                connection_id=connection_id,
+                success=True,
+                duration_ms=duration_ms,
+                row_count=row_count,
+                sql_summary=sql_summary,
+                extra=_audit_extra(config, final_path, normalized_format, export_all, applied_limit),
+            )
+            return {
+                "connection_id": connection_id,
+                "engine": config.engine,
+                "file_path": str(final_path),
+                "format": normalized_format,
+                "row_count": row_count,
+                "duration_ms": duration_ms,
+                "export_all": export_all,
+                "applied_limit": applied_limit,
+            }
+        except Exception as exc:
+            duration_ms = _elapsed_ms(started)
+            sanitized = sanitize_error_message(str(exc))
+            self._audit.log(
+                tool="export_query_file",
+                connection_id=connection_id,
+                success=False,
+                duration_ms=duration_ms,
+                row_count=row_count,
+                sql_summary=sql_summary,
+                error=sanitized,
+                extra=_audit_extra(config, final_path, normalized_format, export_all, applied_limit),
+            )
+            raise QueryExecutionError(sanitized) from exc
+
+
+def _iter_batches(cur: Any, columns: Sequence[str], adapter: Any) -> Iterable[List[object]]:
+    while True:
+        rows = cur.fetchmany(EXPORT_BATCH_SIZE)
+        if not rows:
+            return
+        if hasattr(adapter, "normalize_rows"):
+            rows = adapter.normalize_rows(rows, list(columns))
+        yield cast(List[object], rows)
+
+
+def _build_exact_limited_query(sql: str, row_limit: int) -> str:
+    return f"SELECT * FROM ({sql}) AS pq_result LIMIT {int(row_limit)}"
+
+
+def _write_csv(path: Path, columns: Sequence[str], batches: Iterable[Sequence[object]]) -> int:
+    row_count = 0
+    with path.open("w", encoding="utf-8", newline="") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(columns)
+        for batch in batches:
+            for row in batch:
+                writer.writerow(_row_values(row, columns))
+                row_count += 1
+    return row_count
+
+
+def _write_xlsx(path: Path, columns: Sequence[str], batches: Iterable[Sequence[object]]) -> int:
+    if Workbook is None:
+        raise QueryExecutionError("缺少 openpyxl 依赖，请先安装项目依赖。")
+    workbook = Workbook(write_only=True)
+    worksheet = workbook.create_sheet("Export")
+    worksheet.append(list(columns))
+    row_count = 0
+    for batch in batches:
+        for row in batch:
+            values = _row_values(row, columns, normalize_value=_normalize_xlsx_value)
+            try:
+                worksheet.append(values)
+            except Exception as exc:
+                raise QueryExecutionError(_format_xlsx_error(columns, values, exc)) from exc
+            row_count += 1
+    workbook.save(path)
+    return row_count
+
+
+def _row_values(
+    row: object,
+    columns: Sequence[str],
+    normalize_value: Optional[Callable[[object], object]] = None,
+) -> List[object]:
+    if isinstance(row, dict):
+        values: List[object] = [row.get(column) for column in columns]
+    elif isinstance(row, (list, tuple)):
+        values = list(row)
+    else:
+        values = [row]
+    if normalize_value is None:
+        return values
+    return [normalize_value(value) for value in values]
+
+
+def _normalize_xlsx_value(value: object) -> object:
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, datetime) and value.tzinfo is not None:
+        return value.replace(tzinfo=None)
+    if isinstance(value, datetime_time) and value.tzinfo is not None:
+        return value.replace(tzinfo=None)
+    return value
+
+
+def _format_xlsx_error(columns: Sequence[str], values: Sequence[object], exc: Exception) -> str:
+    message = str(exc) or exc.__class__.__name__
+    details = ", ".join(
+        f"{column}={type(value).__name__}"
+        for column, value in zip(columns, values)
+    )
+    return f"XLSX 导出失败: {message}; columns: {details}"
+
+
+def _resolve_output_file(output_path: str, format: str, file_name: Optional[str], overwrite: bool) -> Path:
+    base = Path(output_path).expanduser()
+    suffix = f".{format}"
+    if base.exists() and base.is_dir():
+        name = file_name or f"export_{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')}"
+        candidate = base / _with_suffix(name, suffix)
+    else:
+        if file_name:
+            raise QueryExecutionError("output_path 为文件路径时不能同时传 file_name。")
+        candidate = Path(_with_suffix(str(base), suffix)).expanduser()
+        if not candidate.parent.exists():
+            raise QueryExecutionError("导出目录不存在。")
+    if overwrite or not candidate.exists():
+        return candidate
+    return _next_available_path(candidate)
+
+
+def _with_suffix(value: str, suffix: str) -> str:
+    return value if value.lower().endswith(suffix) else value + suffix
+
+
+def _next_available_path(path: Path) -> Path:
+    stem = path.stem
+    suffix = path.suffix
+    parent = path.parent
+    index = 1
+    while True:
+        candidate = parent / f"{stem} ({index}){suffix}"
+        if not candidate.exists():
+            return candidate
+        index += 1
+
+
+def _apply_statement_timeout(adapter: Any, conn: Any, timeout_ms: Optional[int]) -> None:
+    if timeout_ms is not None:
+        getattr(adapter, "set_statement_timeout")(conn, timeout_ms)
+
+
+def _open_export_cursor(adapter: Any, conn: Any) -> Any:
+    export_cursor = getattr(adapter, "export_cursor", None)
+    if callable(export_cursor):
+        return export_cursor(conn)
+    return conn.cursor()
+
+
+def _elapsed_ms(started: float) -> int:
+    return int((time.perf_counter() - started) * 1000)
+
+
+def _audit_extra(
+    config: Any,
+    file_path: Optional[Path],
+    format: str,
+    export_all: bool,
+    applied_limit: Optional[int],
+) -> Dict[str, object]:
+    extra: Dict[str, object] = {
+        "file_path": str(file_path) if file_path is not None else None,
+        "format": format,
+        "export_all": export_all,
+        "applied_limit": applied_limit,
+    }
+    if config is not None:
+        extra["engine"] = config.engine
+    return extra