execsql2 2.6.0__tar.gz → 2.7.1__tar.gz

{execsql2-2.6.0 → execsql2-2.7.1}/.claude/project_context.md

@@ -265,10 +265,10 @@ ______________________________________________________________________
 
 ### v2.7 — New Export/Import Formats
 
-- [ ] **Parquet import** — complement existing Parquet export and Feather import. Natural fit with DuckDB support.
-- [ ] **YAML export** — popular for config-generation workflows; rounds out the format matrix.
-- [ ] **Markdown (GFM) export** — GitHub-flavored markdown tables. Lightweight and useful for docs/reports.
-- [ ] **Excel (XLSX) multi-sheet export** — multiple queries → multiple named sheets in one workbook, with basic formatting.
+- [x] **Parquet import** — already existed as `IMPORT TO table FROM PARQUET file` (verified present).
+- [x] **YAML export** — `FORMAT YAML` via PyYAML, list-of-dicts with native type preservation.
+- [x] **Markdown (GFM) export** — `FORMAT MARKDOWN` / `MD`, pipe tables with alignment and escaping.
+- [x] **Excel (XLSX) multi-sheet export** — `FORMAT XLSX` single + multi-sheet via openpyxl, bold headers, inventory sheet, sheet name deduplication.
 
 ### v2.8 — Scripting Power Features
 

{execsql2-2.6.0 → execsql2-2.7.1}/CHANGELOG.md

@@ -13,6 +13,24 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.7.1] - 2026-04-01
+
+### Fixed
+
+- Fix `AttributeError: module 'execsql.state' has no attribute 'dedup_words'` when importing CSV files with `DEDUP_COL_HDRS` enabled — `dedup_words` is now correctly imported from `execsql.utils.strings` instead of accessed through the state module.
+
+______________________________________________________________________
+
+## [2.7.0] - 2026-04-01
+
+### Added
+
+- **Markdown export** (`FORMAT MARKDOWN` / `FORMAT MD`) — GitHub-flavored pipe tables with column alignment, pipe/backslash escaping, and zip support. No dependencies required.
+- **YAML export** (`FORMAT YAML`) — list-of-dicts output via PyYAML with native type preservation (int, float, null). Requires `PyYAML` (included in `formats` extras).
+- **XLSX export** (`FORMAT XLSX`) — single-sheet and multi-sheet Excel export via openpyxl with bold headers, native type preservation, sheet name deduplication, and a "Datasheets" inventory sheet. Multi-sheet syntax: `EXPORT table1, table2 TO file.xlsx AS XLSX`.
+
+______________________________________________________________________
+
 ## [2.6.0] - 2026-04-01
 
 ### Added

{execsql2-2.6.0 → execsql2-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.6.0
+Version: 2.7.1
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Repository, https://github.com/geocoug/execsql
 Project-URL: Issues, https://github.com/geocoug/execsql/issues
@@ -54,6 +54,7 @@ Requires-Dist: polars; extra == 'all'
 Requires-Dist: psycopg2-binary; extra == 'all'
 Requires-Dist: pymysql; extra == 'all'
 Requires-Dist: pyodbc; extra == 'all'
+Requires-Dist: pyyaml; extra == 'all'
 Requires-Dist: tables; extra == 'all'
 Requires-Dist: xlrd; extra == 'all'
 Provides-Extra: all-db
@@ -76,6 +77,7 @@ Requires-Dist: openpyxl; extra == 'dev'
 Requires-Dist: polars; extra == 'dev'
 Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: tables; extra == 'dev'
 Requires-Dist: tox-uv>=1.13.1; extra == 'dev'
@@ -91,6 +93,7 @@ Requires-Dist: jinja2; extra == 'formats'
 Requires-Dist: odfpy; extra == 'formats'
 Requires-Dist: openpyxl; extra == 'formats'
 Requires-Dist: polars; extra == 'formats'
+Requires-Dist: pyyaml; extra == 'formats'
 Requires-Dist: tables; extra == 'formats'
 Requires-Dist: xlrd; extra == 'formats'
 Provides-Extra: mssql
@@ -227,7 +230,7 @@ Run `execsql --help` for the full option list, or `execsql -m` to list all metac
 # Features
 
 - Import data from CSV, TSV, Excel, OpenDocument, Feather, or Parquet files into a database table.
-- Export query results in 15+ formats including CSV, TSV, JSON, XML, HTML, LaTeX, OpenDocument, Feather, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
+- Export query results in 20+ formats including CSV, TSV, JSON, YAML, XML, HTML, Markdown, LaTeX, XLSX, OpenDocument, Feather, Parquet, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
 - Copy data between databases, including across different DBMS types.
 - Conditionally execute SQL and metacommands using `IF`/`ELSE`/`ENDIF` based on data values, DBMS type, or user input.
 - Loop over blocks of SQL and metacommands using `LOOP`/`ENDLOOP`.

{execsql2-2.6.0 → execsql2-2.7.1}/README.md

@@ -120,7 +120,7 @@ Run `execsql --help` for the full option list, or `execsql -m` to list all metac
 # Features
 
 - Import data from CSV, TSV, Excel, OpenDocument, Feather, or Parquet files into a database table.
-- Export query results in 15+ formats including CSV, TSV, JSON, XML, HTML, LaTeX, OpenDocument, Feather, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
+- Export query results in 20+ formats including CSV, TSV, JSON, YAML, XML, HTML, Markdown, LaTeX, XLSX, OpenDocument, Feather, Parquet, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
 - Copy data between databases, including across different DBMS types.
 - Conditionally execute SQL and metacommands using `IF`/`ELSE`/`ENDIF` based on data values, DBMS type, or user input.
 - Loop over blocks of SQL and metacommands using `LOOP`/`ENDLOOP`.

{execsql2-2.6.0 → execsql2-2.7.1}/docs/about/divergence.md

@@ -26,10 +26,13 @@ ______________________________________________________________________
 
 ### Export Formats
 
-| Format    | Description                                                                     |
-| --------- | ------------------------------------------------------------------------------- |
-| `PARQUET` | Export query or table results to Apache Parquet via `polars`.                   |
-| `FEATHER` | Export to Apache Feather/IPC via `polars` + `pyarrow` (upstream used `pandas`). |
+| Format            | Description                                                                                                          |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `PARQUET`         | Export query or table results to Apache Parquet via `polars`.                                                        |
+| `FEATHER`         | Export to Apache Feather/IPC via `polars` + `pyarrow` (upstream used `pandas`).                                      |
+| `YAML`            | Export query or table results as a YAML sequence of mappings via `PyYAML`.                                           |
+| `MARKDOWN` / `MD` | Export query or table results as a GitHub-Flavored Markdown (GFM) pipe table. Pure Python, no optional dependencies. |
+| `XLSX`            | Export query or table results to an Excel XLSX workbook via `openpyxl` (single or multi-sheet).                      |
 
 ### Metacommands
 

{execsql2-2.6.0 → execsql2-2.7.1}/docs/reference/metacommands.md

@@ -932,7 +932,22 @@ JSON_TS or JSON_TABLESCHEMA
 
 LATEX
 
-:   Input for the [LaTeΧ](https://www.latex-project.org/) typesetting system. If the "APPEND" keyword is not used, a complete document (of class article) will be written. If the "APPEND" keyword is used, only the table definition will be written to the output file. If the "APPEND" keyword is used and an existing output file contains an \\end directive, the table will be written before that directive rather than at the physical end of the file. Wide or long tables may exceed LaTeΧ's default page size. If the "DESCRIPTION" keyword is used, the given description will be used as the table's caption. Data exported in LaTeX format cannot be written into a zipfile.
+:   Input for the [LaTeX](https://www.latex-project.org/) typesetting system. If the "APPEND" keyword is not used, a complete document (of class article) will be written. If the "APPEND" keyword is used, only the table definition will be written to the output file. If the "APPEND" keyword is used and an existing output file contains an \\end directive, the table will be written before that directive rather than at the physical end of the file. Wide or long tables may exceed LaTeΧ's default page size. If the "DESCRIPTION" keyword is used, the given description will be used as the table's caption. Data exported in LaTeX format cannot be written into a zipfile.
+
+
+MARKDOWN or MD
+
+:   [GitHub-Flavored Markdown](https://github.github.com/gfm/) pipe table. Column values are aligned and pipe (`|`) and backslash (`\`) characters in data are escaped. If the "DESCRIPTION" keyword is used, the description is written as an HTML comment (`<!-- ... -->`) before the table. If the "APPEND" keyword is used, only the table is appended (no repeated headers). No optional dependencies required.
+
+
+XLSX
+
+:   [Excel](https://www.microsoft.com/en-us/microsoft-365/excel) workbook in the Office Open XML format. One or more tables (or views) can be exported to an XLSX workbook. Each table will be exported to a separate worksheet within the workbook, with the first row containing bold column headers. To export multiple tables, their names must be separated by commas. The "APPEND" keyword can be used to add worksheets to an existing workbook. The name of the view or table exported will be used as the worksheet name; if this conflicts with a sheet already in the workbook, a number will be appended to make the sheet name unique. A "Datasheets" inventory sheet is created with author, date, description, and source information for each data sheet. Data types are preserved natively (integers, floats, dates, datetimes, booleans). The `openpyxl` library must be installed (`pip install execsql2[excel]`). Data exported in XLSX format cannot be written into a zipfile.
+
+
+YAML
+
+:   [YAML](https://yaml.org/) sequence of mappings. Each row is represented as a mapping (dictionary) with column names as keys. Python data types are preserved — integers remain integers, floats remain floats, and `None` becomes YAML `null`. If the "APPEND" keyword is used, a new YAML document is appended to the file (multi-document stream). The `PyYAML` library must be installed (`pip install execsql2[formats]`). No description text is included in the output even if provided.
 
 
 SQLITE

{execsql2-2.6.0 → execsql2-2.7.1}/extras/vscode-execsql/syntaxes/execsql.tmLanguage.json

@@ -118,7 +118,7 @@
     },
     "export-formats": {
       "comment": "Export/import format names",
-      "match": "(?i)\\b(json_tableschema|cgi-html|feather|json_ts|txt-and|unitsep|duckdb|sqlite|values|latex|plain|hdf5|html|json|tabq|tsvq|b64|csv|ods|raw|tab|tsv|txt|xml|us)\\b",
+      "match": "(?i)\\b(json_tableschema|cgi-html|markdown|feather|json_ts|txt-and|unitsep|duckdb|sqlite|values|latex|plain|hdf5|html|json|tabq|tsvq|xlsx|yaml|b64|csv|ods|raw|tab|tsv|txt|xml|md|us)\\b",
       "name": "support.constant.execsql"
     },
     "secondary-operators": {

{execsql2-2.6.0 → execsql2-2.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.6.0"
+version = "2.7.1"
 description = "Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE.txt" }
@@ -56,7 +56,7 @@ firebird = ["firebird-driver"]
 oracle = ["oracledb"]
 odbc = ["pyodbc"]
 # Feature bundles
-formats = ["odfpy", "xlrd", "openpyxl", "Jinja2", "polars", "tables"]
+formats = ["odfpy", "xlrd", "openpyxl", "Jinja2", "polars", "tables", "PyYAML"]
 auth = ["keyring"]
 # Convenience groups
 all-db = [
@@ -158,7 +158,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.6.0"
+current_version = "2.7.1"
 commit = true
 commit_args = "--no-verify"
 tag = true

{execsql2-2.6.0 → execsql2-2.7.1}/src/execsql/exporters/__init__.py

@@ -9,9 +9,9 @@ handlers can access them via ``_state.write_query_to_csv`` etc. without
 importing directly from here.
 
 Sub-modules: ``base``, ``delimited``, ``json``, ``xml``, ``html``,
-``latex``, ``ods``, ``xls``, ``zip``, ``raw``, ``pretty``, ``values``,
-``templates``, ``feather``, ``parquet``, ``duckdb``, ``sqlite``,
-``protocol``.
+``latex``, ``markdown``, ``ods``, ``xls``, ``zip``, ``raw``, ``pretty``,
+``values``, ``templates``, ``feather``, ``parquet``, ``duckdb``,
+``sqlite``, ``protocol``.
 """
 
 from execsql.exporters.protocol import QueryExporter, RowsetExporter

{execsql2-2.6.0 → execsql2-2.7.1}/src/execsql/exporters/delimited.py

@@ -27,7 +27,7 @@ from execsql.exceptions import ErrInfo
 from execsql.models import DataTable
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
-from execsql.utils.strings import clean_words, fold_words
+from execsql.utils.strings import clean_words, dedup_words, fold_words
 
 __all__ = ["LineDelimiter", "CsvFile", "CsvWriter", "DelimitedWriter", "write_delimited_file"]
 
@@ -677,7 +677,7 @@ class CsvFile(EncodedFile):
         if conf.fold_col_hdrs != "no":
             colnames = fold_words(colnames, conf.fold_col_hdrs)
         if conf.dedup_col_hdrs:
-            colnames = _state.dedup_words(colnames)
+            colnames = dedup_words(colnames)
         return colnames
 
     def column_headers(self) -> list[str]:

execsql2-2.7.1/src/execsql/exporters/markdown.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+"""
+GitHub-Flavored Markdown (GFM) pipe table export for execsql.
+
+Provides :func:`write_query_to_markdown`, which serializes a query result
+set as a GFM pipe table suitable for inclusion in GitHub README files,
+wikis, and any Markdown renderer that supports the pipe-table extension.
+
+Example output::
+
+    | id | name   | score |
+    |----|--------|-------|
+    | 1  | Alice  | 95.2  |
+    | 2  | Bob    | 87.0  |
+
+No optional dependencies — pure Python.
+"""
+
+from typing import Any
+
+import execsql.state as _state
+from execsql.exceptions import ErrInfo
+from execsql.exporters.zip import ZipWriter
+from execsql.utils.errors import exception_desc
+from execsql.utils.fileio import filewriter_close
+
+__all__ = ["write_query_to_markdown"]
+
+_PIPE_ESCAPE = str.maketrans({"|": r"\|", "\\": "\\\\"})
+
+
+def _cell(value: Any) -> str:
+    """Render a single cell value as a Markdown-safe string.
+
+    Args:
+        value: The cell value from the result set.  ``None`` is rendered as
+            an empty string.  Pipe characters are escaped so they do not
+            break the table structure.
+
+    Returns:
+        A string safe to embed between pipe characters in a GFM table row.
+    """
+    if value is None:
+        return ""
+    return str(value).translate(_PIPE_ESCAPE)
+
+
+def write_query_to_markdown(
+    select_stmt: str,
+    db: Any,
+    outfile: str,
+    append: bool = False,
+    desc: str | None = None,
+    zipfile: str | None = None,
+) -> None:
+    """Execute *select_stmt* and write the result set as a GFM pipe table.
+
+    Writes a GitHub-Flavored Markdown pipe table to *outfile* (or into
+    *zipfile* when provided).  Column widths are derived from the widest
+    value in each column (including the header), so the table renders
+    legibly in plain-text editors as well as in Markdown renderers.
+
+    Args:
+        select_stmt: SQL SELECT statement to execute.
+        db: Database connection object exposing ``select_rowsource()``.
+        outfile: Destination file path, or ``"stdout"`` for console output.
+        append: When ``True`` open the file in append mode.  A blank line
+            is written before the table so consecutive appended tables are
+            visually separated.
+        desc: Optional human-readable description.  When provided it is
+            written as an HTML comment (``<!-- desc -->``), which is valid
+            Markdown and invisible in rendered output.
+        zipfile: When set, write into this ZIP archive instead of a plain
+            file.  *outfile* becomes the entry name inside the archive.
+    """
+    conf = _state.conf
+    try:
+        hdrs, rows = db.select_rowsource(select_stmt)
+    except ErrInfo:
+        raise
+    except Exception as e:
+        raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
+
+    # Materialise the full result set so we can compute column widths in one
+    # pass before writing.  GFM tables require consistent column widths for
+    # readability; width computation requires seeing all rows first.
+    str_hdrs: list[str] = [_cell(h) for h in hdrs]
+    str_rows: list[list[str]] = [[_cell(v) for v in row] for row in rows]
+
+    # Minimum separator width is 3 dashes (GFM spec minimum for alignment row).
+    col_widths: list[int] = [max(3, len(h)) for h in str_hdrs]
+    for row in str_rows:
+        for i, cell in enumerate(row):
+            if len(cell) > col_widths[i]:
+                col_widths[i] = len(cell)
+
+    def _format_row(cells: list[str]) -> str:
+        padded = (f" {c:<{col_widths[i]}} " for i, c in enumerate(cells))
+        return "|" + "|".join(padded) + "|\n"
+
+    def _format_separator() -> str:
+        dashes = (f" {'-' * col_widths[i]} " for i in range(len(str_hdrs)))
+        return "|" + "|".join(dashes) + "|\n"
+
+    if zipfile is None:
+        filewriter_close(outfile)
+        from execsql.utils.fileio import EncodedFile
+
+        ef = EncodedFile(outfile, conf.output_encoding)
+        f = ef.open("at" if append else "wt")
+    else:
+        f = ZipWriter(zipfile, outfile, append)
+
+    try:
+        if append:
+            # Blank line separates consecutive tables when appending.
+            f.write("\n")
+        if desc is not None:
+            f.write(f"<!-- {desc} -->\n\n")
+        f.write(_format_row(str_hdrs))
+        f.write(_format_separator())
+        for row in str_rows:
+            f.write(_format_row(row))
+    finally:
+        f.close()

execsql2-2.7.1/src/execsql/exporters/xlsx.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+"""
+XLSX (Excel Open XML) export for execsql.
+
+Provides :func:`write_query_to_xlsx` (single-sheet export) and
+:func:`write_queries_to_xlsx` (multi-sheet export).  Requires the
+``openpyxl`` package (``execsql2[excel]``).
+"""
+
+import datetime
+import getpass
+import os
+from pathlib import Path
+from typing import Any
+
+import execsql.state as _state
+from execsql.exceptions import ErrInfo
+from execsql.exporters.base import ExportRecord
+from execsql.exporters.pretty import prettyprint_query
+from execsql.script import current_script_line
+from execsql.utils.errors import exception_desc, fatal_error
+from execsql.utils.fileio import filewriter_close
+from execsql.utils.strings import unquoted
+
+__all__ = ["write_query_to_xlsx", "write_queries_to_xlsx"]
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _require_openpyxl() -> Any:
+    """Import and return the openpyxl module, raising a fatal error if absent."""
+    try:
+        import openpyxl
+
+        return openpyxl
+    except ImportError:
+        fatal_error("The openpyxl library is needed to write Excel (.xlsx) spreadsheets (install execsql2[excel]).")
+
+
+def _cell_value(item: Any) -> Any:
+    """Return a value suitable for writing directly to an openpyxl cell.
+
+    openpyxl natively handles int, float, bool, str, datetime.datetime,
+    datetime.date, and None.  datetime.time is converted to a string because
+    openpyxl does not have a native time-only cell type.
+    """
+    if item is None:
+        return None
+    if isinstance(item, bool):
+        # bool must be checked before int — bool is a subclass of int.
+        return item
+    if isinstance(item, int | float):
+        return item
+    if isinstance(item, datetime.datetime):
+        return item
+    if isinstance(item, datetime.date):
+        return item
+    if isinstance(item, datetime.time):
+        # openpyxl has no native time-only type; store as HH:MM:SS string.
+        return item.strftime("%H:%M:%S")
+    return str(item)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def write_query_to_xlsx(
+    select_stmt: str,
+    db: Any,
+    outfile: str,
+    append: bool = False,
+    desc: str | None = None,
+    sheetname: str | None = None,
+) -> None:
+    """Execute *select_stmt* and write the result to a single worksheet in an XLSX file.
+
+    Args:
+        select_stmt: SQL SELECT statement to execute.
+        db: An execsql database adapter with a ``select_rowsource()`` method.
+        outfile: Destination ``.xlsx`` file path.
+        append: If ``True`` and *outfile* exists, add a new sheet to the
+            existing workbook.  If ``False``, overwrite any existing file.
+        desc: Optional human-readable description stored in the inventory sheet.
+        sheetname: Name for the new worksheet.  Defaults to ``"Sheet1"``
+            (or ``"Sheet2"``, ``"Sheet3"``, etc. when appending to avoid
+            name collisions).
+    """
+    openpyxl = _require_openpyxl()
+
+    try:
+        hdrs, rows = db.select_rowsource(select_stmt)
+    except ErrInfo:
+        raise
+    except Exception as e:
+        raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
+
+    # ------------------------------------------------------------------
+    # Determine sheet name and open/create workbook
+    # ------------------------------------------------------------------
+    if append and Path(outfile).is_file():
+        wb = openpyxl.load_workbook(outfile)
+        existing_names = wb.sheetnames
+        base = sheetname or "Sheet"
+        sheet_name = base
+        sheet_no = 1
+        while sheet_name in existing_names:
+            sheet_no += 1
+            sheet_name = f"{base}{sheet_no}"
+    else:
+        sheet_name = sheetname or "Sheet1"
+        if Path(outfile).is_file():
+            filewriter_close(outfile)
+            os.unlink(outfile)
+        wb = openpyxl.Workbook()
+        # openpyxl creates a default sheet named "Sheet"; remove it so we
+        # start with a clean workbook.
+        if wb.sheetnames:
+            del wb[wb.sheetnames[0]]
+
+    # ------------------------------------------------------------------
+    # Ensure the inventory sheet exists
+    # ------------------------------------------------------------------
+    inventory_name = "Datasheets"
+    if inventory_name not in wb.sheetnames:
+        inv_ws = wb.create_sheet(inventory_name)
+        bold_font = openpyxl.styles.Font(bold=True)
+        for col_idx, hdr in enumerate(
+            ("datasheet_name", "created_on", "created_by", "description", "source"),
+            start=1,
+        ):
+            cell = inv_ws.cell(row=1, column=col_idx, value=hdr)
+            cell.font = bold_font
+    else:
+        inv_ws = wb[inventory_name]
+
+    # ------------------------------------------------------------------
+    # Write data to a new sheet
+    # ------------------------------------------------------------------
+    ws = wb.create_sheet(sheet_name)
+    bold_font = openpyxl.styles.Font(bold=True)
+
+    # Header row
+    for col_idx, hdr in enumerate(hdrs, start=1):
+        cell = ws.cell(row=1, column=col_idx, value=str(hdr))
+        cell.font = bold_font
+
+    # Data rows
+    for row_idx, row in enumerate(rows, start=2):
+        for col_idx, item in enumerate(row, start=1):
+            ws.cell(row=row_idx, column=col_idx, value=_cell_value(item))
+
+    # ------------------------------------------------------------------
+    # Update inventory sheet
+    # ------------------------------------------------------------------
+    script, lno = current_script_line()
+    src = (
+        f"{select_stmt} with database {_state.dbs.current().name()}, "
+        f"with script {str(Path(script).resolve())}, line {lno}"
+    )
+    next_row = inv_ws.max_row + 1
+    for col_idx, value in enumerate(
+        (
+            sheet_name,
+            datetime.datetime.now().strftime("%Y-%m-%d %H:%M"),
+            getpass.getuser(),
+            desc,
+            src,
+        ),
+        start=1,
+    ):
+        inv_ws.cell(row=next_row, column=col_idx, value=value)
+
+    wb.save(outfile)
+    wb.close()
+
+
+def write_queries_to_xlsx(
+    table_list: str,
+    db: Any,
+    outfile: str,
+    append: bool = False,
+    tee: bool = False,
+    desc: str | None = None,
+) -> None:
+    """Write multiple tables/queries to separate worksheets in a single XLSX workbook.
+
+    Args:
+        table_list: Comma-separated list of table names (optionally schema-qualified).
+        db: An execsql database adapter with a ``select_rowsource()`` method.
+        outfile: Destination ``.xlsx`` file path.
+        append: If ``True`` and *outfile* exists, add new sheets to the existing
+            workbook rather than replacing it.
+        tee: If ``True``, also pretty-print each query result to stdout.
+        desc: Optional description(s).  A single string is applied to every
+            sheet; a comma-separated string with the same count as *table_list*
+            assigns individual descriptions per sheet.
+    """
+    openpyxl = _require_openpyxl()
+
+    tables = [t.strip() for t in table_list.split(",")]
+    if desc is not None:
+        descriptions = [d.strip() for d in desc.split(",")]
+        one_desc = len(descriptions) != len(tables)
+    else:
+        descriptions = []
+        one_desc = False
+
+    # ------------------------------------------------------------------
+    # Open or create workbook
+    # ------------------------------------------------------------------
+    if Path(outfile).is_file() and not append:
+        filewriter_close(outfile)
+        os.unlink(outfile)
+
+    if Path(outfile).is_file():
+        wb = openpyxl.load_workbook(outfile)
+    else:
+        wb = openpyxl.Workbook()
+        # Remove the default empty sheet created by openpyxl.
+        if wb.sheetnames:
+            del wb[wb.sheetnames[0]]
+
+    # ------------------------------------------------------------------
+    # Ensure the inventory sheet exists
+    # ------------------------------------------------------------------
+    inventory_name = "Datasheets"
+    if inventory_name not in wb.sheetnames:
+        inv_ws = wb.create_sheet(inventory_name)
+        bold_font = openpyxl.styles.Font(bold=True)
+        for col_idx, hdr in enumerate(
+            ("datasheet_name", "created_on", "created_by", "description", "source"),
+            start=1,
+        ):
+            cell = inv_ws.cell(row=1, column=col_idx, value=hdr)
+            cell.font = bold_font
+    else:
+        inv_ws = wb[inventory_name]
+
+    # ------------------------------------------------------------------
+    # Write each table to its own sheet
+    # ------------------------------------------------------------------
+    bold_font = openpyxl.styles.Font(bold=True)
+
+    for i, t in enumerate(tables):
+        # Determine the table name used for the sheet label.
+        if "." in t:
+            st = t.split(".")
+            if len(st) != 2:
+                raise ErrInfo("cmd", other_msg=f"Unrecognized table specification in <{t}>")
+            tblname = unquoted(st[1])
+        else:
+            tblname = unquoted(t)
+
+        # Avoid duplicate sheet names.
+        existing_names = wb.sheetnames
+        sheet_name = tblname
+        sheet_no = 1
+        while sheet_name in existing_names:
+            sheet_name = f"{tblname}_{sheet_no}"
+            sheet_no += 1
+
+        # Fetch data.
+        select_stmt = f"select * from {t};"
+        try:
+            hdrs, rows = db.select_rowsource(select_stmt)
+        except ErrInfo:
+            raise
+        except Exception as e:
+            raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
+
+        # Write data sheet.
+        ws = wb.create_sheet(sheet_name)
+
+        for col_idx, hdr in enumerate(hdrs, start=1):
+            cell = ws.cell(row=1, column=col_idx, value=str(hdr))
+            cell.font = bold_font
+
+        for row_idx, row in enumerate(rows, start=2):
+            for col_idx, item in enumerate(row, start=1):
+                ws.cell(row=row_idx, column=col_idx, value=_cell_value(item))
+
+        # Determine per-sheet description.
+        if desc is None:
+            d = None
+        elif one_desc:
+            d = desc
+        else:
+            d = descriptions[i]
+
+        # Update inventory sheet.
+        script, lno = current_script_line()
+        src = f"From database {_state.dbs.current().name()}, with script {str(Path(script).resolve())}, line {lno}"
+        next_row = inv_ws.max_row + 1
+        for col_idx, value in enumerate(
+            (
+                sheet_name,
+                datetime.datetime.now().strftime("%Y-%m-%d %H:%M"),
+                getpass.getuser(),
+                d,
+                src,
+            ),
+            start=1,
+        ):
+            inv_ws.cell(row=next_row, column=col_idx, value=value)
+
+        if tee and outfile.lower() != "stdout":
+            prettyprint_query(select_stmt, db, "stdout", False, desc=d)
+
+        _state.export_metadata.add(ExportRecord(queryname=select_stmt, outfile=outfile, zipfile=None, description=d))
+
+    wb.save(outfile)
+    wb.close()