execsql2 2.26.0__py3-none-any.whl → 2.28.0__py3-none-any.whl

execsql/cli/commands/__init__.py

@@ -11,3 +11,4 @@ from execsql.cli.commands import lint  # noqa: F401
 from execsql.cli.commands import config  # noqa: F401
 from execsql.cli.commands import listing  # noqa: F401
 from execsql.cli.commands import init  # noqa: F401
+from execsql.cli.commands import lsp  # noqa: F401

execsql/cli/commands/format.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from pathlib import Path
 
 import typer
+from rich.markup import escape
 
 from execsql.cli.application import ExecsqlCommand, app
 from execsql.cli.help import _err_console
@@ -90,7 +91,7 @@ def format_cmd(
         try:
             _require_sqlglot()
         except ImportError as exc:
-            _err_console.print(f"[bold red]Error:[/bold red] {exc}", highlight=False)
+            _err_console.print(f"[bold red]Error:[/bold red] {escape(str(exc))}", highlight=False)
             raise typer.Exit(code=1) from exc
     raise typer.Exit(
         code=run_formatter(

execsql/cli/commands/listing.py

@@ -9,17 +9,21 @@ from __future__ import annotations
 
 import json
 import sys
+from typing import Annotated
 
 import typer
 
 from execsql.cli.application import ExecsqlCommand, ExecsqlSubGroup, app
 from execsql.cli.help import (
+    _err_console,
     _encoding_names,
-    _metacommand_rows,
+    _metacommand_entries,
+    _metacommand_json,
     _plugins_data,
     _print_encodings,
     _print_keywords_json,
     _print_keywords_text,
+    _print_metacommand,
     _print_metacommands,
     _print_plugins,
 )
@@ -43,10 +47,33 @@ def _json(data: object) -> None:
 
 
 @list_app.command(cls=ExecsqlCommand, name="metacommands")
-def metacommands_cmd(output_format: OutputFormatOpt = OutputFormat.text) -> None:
-    """Every metacommand and its syntax."""
-    if output_format is OutputFormat.json:
-        _json([{"name": name, "syntax": syntax} for name, syntax in _metacommand_rows()])
+def metacommands_cmd(
+    keyword: Annotated[
+        list[str] | None,
+        typer.Argument(metavar="[KEYWORD]", help="Show one metacommand's syntax, e.g. EXPORT or export query."),
+    ] = None,
+    output_format: OutputFormatOpt = OutputFormat.text,
+) -> None:
+    """Every metacommand with a one-line summary, or the syntax of one."""
+    if keyword:
+        from execsql.metacommands.reference import metacommand
+
+        wanted = " ".join(keyword)
+        entry = metacommand(wanted)
+        if entry is None:
+            import difflib
+
+            names = [m.keyword for m in _metacommand_entries()]
+            close = difflib.get_close_matches(wanted.upper(), names, n=3)
+            hint = f" Did you mean {', '.join(close)}?" if close else ""
+            _err_console.print(f"[bold red]Error:[/bold red] No metacommand {wanted!r}.{hint}", highlight=False)
+            raise typer.Exit(code=2)
+        if output_format is OutputFormat.json:
+            _json(_metacommand_json(entry))
+        else:
+            _print_metacommand(entry)
+    elif output_format is OutputFormat.json:
+        _json([_metacommand_json(m) for m in _metacommand_entries()])
     else:
         _print_metacommands()
 

execsql/cli/commands/lsp.py

@@ -0,0 +1,64 @@
+"""The ``lsp`` command: the language server editors start for ``.sql`` files."""
+
+from __future__ import annotations
+
+import typer
+from rich.markup import escape
+
+from execsql.cli.application import ExecsqlCommand, app
+from execsql.cli.help import _err_console
+from execsql.utils.errors import install_hint
+
+__all__ = ["lsp_cmd"]
+
+
+def _lsp_libraries_installed() -> bool:
+    """Whether pygls and lsprotocol are installed (whether or not this execsql can use them)."""
+    from importlib.util import find_spec
+
+    return all(find_spec(name) is not None for name in ("pygls", "lsprotocol"))
+
+
+def _pygls_version() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("pygls")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+@app.command(
+    cls=ExecsqlCommand,
+    name="lsp",
+    help=(
+        "Run the execsql language server on stdin/stdout, for an editor to start. "
+        "Shows execsql lint findings as you type, completes metacommands, "
+        "conditional tests and variables, explains them on hover, and finds where variables, "
+        "SCRIPTs and included files are defined, offers quick fixes, and formats documents. Requires the lsp "
+        "extra; --check reports whether it is installed."
+    ),
+)
+def lsp_cmd(
+    # Editors' language clients pass --stdio (VS Code always does); stdio is the only transport.
+    stdio: bool = typer.Option(False, "--stdio", hidden=True),
+    check: bool = typer.Option(False, "--check", help="Report whether the language server can start, and exit."),
+) -> None:
+    """The ``lsp`` command; its user-facing help is the decorator's ``help``."""
+    try:
+        from execsql.lsp.server import create_server
+    except ImportError as exc:
+        if _lsp_libraries_installed():
+            # pygls is there but this execsql cannot use it (another major version, a broken install).
+            message = (
+                f"execsql lsp cannot use the installed pygls {_pygls_version()} ({exc}). "
+                f"It needs pygls 2.x, which the lsp extra installs. {install_hint('lsp')}"
+            )
+        else:
+            message = f"execsql lsp needs the lsp extra. {install_hint('lsp')}"
+        _err_console.print(f"[bold red]Error:[/bold red] {escape(message)}", highlight=False)
+        raise typer.Exit(code=1) from exc
+    if check:
+        typer.echo(f"execsql lsp is ready (pygls {_pygls_version()}).")
+        return
+    create_server().start_io()

execsql/cli/dispatch.py

@@ -29,7 +29,7 @@ from __future__ import annotations
 __all__ = ["COMMANDS", "GLOBAL_FLAGS", "dispatch", "normalize"]
 
 #: Tokens that name a command.
-COMMANDS = ("run", "format", "lint", "config", "list", "init")
+COMMANDS = ("run", "format", "lint", "config", "list", "init", "lsp")
 
 #: Options declared on the app rather than on a command, which must reach
 #: the parser without ``run`` in front of them. ``-m``, ``--encodings`` and

execsql/cli/help.py

@@ -19,7 +19,9 @@ __all__ = [
     "_init_config",
     "_init_config_text",
     "_keywords_data",
-    "_metacommand_rows",
+    "_metacommand_entries",
+    "_metacommand_json",
+    "_print_metacommand",
     "_plugins_data",
     "_print_encodings",
     "_print_keywords_json",
@@ -31,66 +33,6 @@ __all__ = [
 _console = Console()
 _err_console = Console(stderr=True)
 
-# ---------------------------------------------------------------------------
-# Metacommand syntax hints — paired with keywords from the dispatch table.
-# Keys must match the ``description`` values used in mcl.add() calls.
-# Entries here are validated by tests/test_registry.py.
-# ---------------------------------------------------------------------------
-
-_SYNTAX: dict[str, tuple[str, str]] = {
-    # (display_name, syntax_hint)
-    "ASK": ("ASK", '"<question>" SUB <match_string>'),
-    "AUTOCOMMIT": ("AUTOCOMMIT", "ON|OFF"),
-    "BEGIN BATCH": ("BEGIN BATCH / END BATCH / ROLLBACK BATCH", ""),
-    "BEGIN SCRIPT": ("BEGIN SCRIPT / END SCRIPT", ""),
-    "BEGIN SQL": ("BEGIN SQL / END SQL", ""),
-    "CANCEL_HALT": ("CANCEL_HALT", "ON|OFF"),
-    "CD": ("CD", "<directory>"),
-    "CONNECT": ("CONNECT", "<alias> [AS <alias_name>]"),
-    "COPY": ("COPY", "<source_file> TO <dest_file>"),
-    "DEBUG": ("DEBUG", "ON|OFF"),
-    "SUB": ("DEFINE SUB", "<variable> [AS] <value>"),
-    "EXPORT QUERY": ("EXPORT QUERY", "<queryname> [AS <alias>] ..."),
-    "EXPORT": ("EXPORT", "<queryname> TO <format> <filename> ..."),
-    "HALT": ("HALT [ON]", "ERROR|CANCEL"),
-    "IF": ("IF <condition>", "/ ELSE / ENDIF"),
-    "IMPORT_FILE": ("IMPORT FILE", "<filename> [OPTIONS ...]"),
-    "IMPORT": ("IMPORT TABLE", "<tablename> FROM FILE <filename> [OPTIONS ...]"),
-    "LOOP": ("LOOP <n> TIMES | WHILE | UNTIL", "/ END LOOP"),
-    "CONFIG": ("CONFIG", "<option> <value>"),
-    "ON CANCEL_HALT": ("ON CANCEL_HALT", "..."),
-    "ON ERROR_HALT": ("ON ERROR_HALT", "..."),
-    "PAUSE": ("PAUSE", "[<text>]"),
-    "PROMPT ACTION": ("PROMPT ACTION", "..."),
-    "PROMPT ENTRY_FORM": ("PROMPT ENTRY_FORM", "..."),
-    "PROMPT OPENFILE": ("PROMPT OPENFILE", "..."),
-    "PROMPT SAVEFILE": ("PROMPT SAVEFILE", "..."),
-    "PROMPT DIRECTORY": ("PROMPT DIRECTORY", "..."),
-    "PROMPT MAP": ("PROMPT MAP", "..."),
-    "ROLLBACK BATCH": ("ROLLBACK", ""),
-    "SERVE": ("SERVE", "<queryname> ..."),
-    "SYSTEM_CMD": ("SYSTEM_CMD", "(<operating system command line>)"),
-    "TIMER": ("TIMER", "ON|OFF"),
-    "USE": ("USE", "<alias_name>"),
-    "WAIT_UNTIL": ("WAIT_UNTIL", "<Boolean_expression> <HALT|CONTINUE> AFTER <n> SECONDS"),
-    "WRITE": ("WRITE", '"<text>" [[TEE] TO <output>]'),
-    "WRITE CREATE_TABLE": ("WRITE CREATE_TABLE FROM", "<filename> [TO <output>]"),
-    "WRITE SCRIPT": ("WRITE SCRIPT", "<script_name> [[APPEND] TO <output_file>]"),
-    "ZIP": ("ZIP", "<filename> [APPEND] TO ZIPFILE <zipfilename>"),
-    "SUB_TEMPFILE": ("SUB_TEMPFILE", "<variable>"),
-}
-
-# Keys from _SYNTAX that should be skipped when auto-generating from dispatch
-# table (they're variants covered by another entry).
-_SKIP_FROM_DISPATCH = {
-    "END BATCH",
-    "END SCRIPT",
-    "END SQL",
-    "ROLLBACK BATCH",
-    "BEGIN SCRIPT",
-    "BEGIN SQL",
-}
-
 
 def _init_config_text() -> str:
     """The default execsql.conf template, every option commented out and documented."""
@@ -106,56 +48,62 @@ def _init_config() -> None:
     sys.stdout.write(_init_config_text())
 
 
-def _metacommand_rows() -> list[tuple[str, str]]:
-    """``(name, syntax)`` for every metacommand, in the order they are listed.
+_CATEGORY_ORDER = ("control", "block", "action", "config", "prompt")
 
-    Keyword list is derived from the dispatch table; syntax hints come from
-    the ``_SYNTAX`` dict above.  Keywords not in ``_SYNTAX`` get an empty
-    syntax hint.
-    """
-    from execsql.metacommands import DISPATCH_TABLE
-
-    # Collect unique keyword names from the dispatch table.
-    seen: set[str] = set()
-    keywords: list[str] = []
-    for mc in DISPATCH_TABLE:
-        if mc.description and mc.description not in seen and mc.description not in _SKIP_FROM_DISPATCH:
-            seen.add(mc.description)
-            keywords.append(mc.description)
-    # Add parser-level keywords not in the dispatch table.
-    for extra in ("BEGIN BATCH", "BEGIN SCRIPT", "BEGIN SQL"):
-        if extra not in seen:
-            seen.add(extra)
-            keywords.append(extra)
-
-    rows: list[tuple[str, str]] = []
-    for kw in sorted(keywords):
-        if kw in _SYNTAX:
-            rows.append(_SYNTAX[kw])
-        elif kw.startswith("CONFIG ") or kw.startswith("CONSOLE_") or "_" in kw:
-            continue  # skip config options / internal entries
-        else:
-            rows.append((kw, ""))
-    return rows
+
+def _metacommand_entries() -> list[Any]:
+    """Every metacommand's readable entry, by category, then keyword."""
+    from execsql.metacommands.reference import metacommands
+
+    order = {c: i for i, c in enumerate(_CATEGORY_ORDER)}
+    return sorted(metacommands(), key=lambda m: (order.get(m.category, len(order)), m.keyword))
+
+
+def _metacommand_json(entry: Any) -> dict[str, Any]:
+    return {
+        "name": entry.keyword,
+        "category": entry.category,
+        "syntax": entry.forms[0],
+        "forms": list(entry.forms),
+        "summary": entry.summary,
+        "url": entry.url,
+    }
 
 
 def _print_metacommands() -> None:
-    """Print the metacommands table using Rich."""
+    """Print every metacommand with its category and one-line summary."""
     table = Table(
         title="execsql Metacommands",
-        caption="Embed in SQL comment lines following the [bold]!x![/bold] token.",
+        caption=(
+            "Write them in a SQL comment after [bold]-- !x![/bold].  "
+            "[bold]execsql list metacommands <KEYWORD>[/bold] shows the syntax of one."
+        ),
         show_header=True,
         header_style="bold cyan",
         border_style="dim",
         expand=False,
     )
     table.add_column("Metacommand", style="bold green", no_wrap=True)
-    table.add_column("Syntax", style="white")
-    for name, syntax in _metacommand_rows():
-        table.add_row(name, syntax)
+    table.add_column("Category", style="dim", no_wrap=True)
+    table.add_column("Summary", style="white")
+    for entry in _metacommand_entries():
+        table.add_row(entry.keyword, entry.category, entry.summary)
     _console.print(table)
 
 
+def _print_metacommand(entry: Any) -> None:
+    """Print one metacommand's syntax lines, summary and docs link."""
+    from rich.markup import escape
+
+    _console.print(f"[bold green]{escape(entry.keyword)}[/bold green]  [dim]{entry.category}[/dim]")
+    _console.print(escape(entry.summary))
+    _console.print()
+    for form in entry.forms:
+        _console.print(f"  -- !x! {escape(form)}", highlight=False)
+    _console.print()
+    _console.print(f"[dim]{entry.url}[/dim]", highlight=False)
+
+
 def _encoding_names() -> list[str]:
     """Every encoding name Python accepts, sorted."""
     return sorted(codec_dict.keys())

execsql/cli/lint.py

@@ -48,6 +48,7 @@ Public surface:
 
 from __future__ import annotations
 
+import functools
 import json
 import re
 from collections import Counter
@@ -82,6 +83,7 @@ __all__ = [
     "filter_issues",
     "lint",
     "lint_source",
+    "variables_defined_by",
     "parse_error",
     "print_concise",
     "print_statistics",
@@ -430,6 +432,18 @@ def _extract_var_definition(
             _read_ini_vars(ini_file, ini_section, script_dir, defined)
 
 
+def variables_defined_by(command: str, script_dir: Path | None = None) -> set[str]:
+    """The variable names (upper case, without ``~``/``+``) a metacommand defines.
+
+    *command* is the text after ``-- !x!``.  Covers the SUB family, the
+    prompts that store an answer, SUB_QUERYSTRING and SUB_INI (whose INI file
+    is read, relative to *script_dir*).
+    """
+    defined: set[str] = set()
+    _extract_var_definition(command, script_dir, defined)
+    return defined
+
+
 # Larger than any real SUB_INI file; lint reads no more than this.
 _MAX_INI_BYTES = 1024 * 1024
 
@@ -447,23 +461,40 @@ def _read_ini_vars(
     language server; a file that is unreadable or not valid INI defines
     nothing.
     """
-    from configparser import ConfigParser
-    from configparser import Error as ConfigError
-
     p = Path(ini_file)
     if not p.is_absolute() and script_dir is not None:
         p = script_dir / p
+    try:
+        if not p.is_file():
+            return
+        stat = p.stat()
+        if stat.st_size > _MAX_INI_BYTES:
+            return
+        resolved = str(p.resolve())
+    except OSError:
+        return
+    defined_vars.update(_ini_section_keys(resolved, stat.st_size, stat.st_mtime_ns, section))
+
+
+@functools.lru_cache(maxsize=64)
+def _ini_section_keys(path: str, size: int, mtime_ns: int, section: str) -> frozenset[str]:
+    """The upper-cased keys of *section* in the INI file at *path*.
+
+    Cached by the file's size and modification time: a script that names
+    the same file on many SUB_INI lines, and the language server re-linting
+    on every edit, read it once.
+    """
+    from configparser import ConfigParser
+    from configparser import Error as ConfigError
 
     cp = ConfigParser()
     try:
-        if not p.is_file() or p.stat().st_size > _MAX_INI_BYTES:
-            return
-        cp.read_string(p.read_text(encoding="utf-8"), source=str(p))
+        cp.read_string(Path(path).read_text(encoding="utf-8"), source=path)
     except (OSError, UnicodeDecodeError, ConfigError):
-        return
-    if cp.has_section(section):
-        for key, _value in cp.items(section):
-            defined_vars.add(key.upper())
+        return frozenset()
+    if not cp.has_section(section):
+        return frozenset()
+    return frozenset(key.upper() for key, _value in cp.items(section))
 
 
 def _is_known_var(raw_name: str, defined_vars: set[str]) -> bool:
@@ -821,7 +852,12 @@ def _referencing_text(node: Node) -> list[str]:
     return texts
 
 
-def _check_unused_variables(script: Script, defined: set[str], issues: list[_Issue]) -> None:
+def _check_unused_variables(
+    script: Script,
+    defined: set[str],
+    issues: list[_Issue],
+    script_dir: Path | None = None,
+) -> None:
     """Report variables a SUB defines that nothing ever reads.
 
     Almost always a typo in either the definition or the reference — the two
@@ -832,8 +868,11 @@ def _check_unused_variables(script: Script, defined: set[str], issues: list[_Iss
     referenced: set[str] = set()
     _collect_var_references(script.body, referenced)
     unused = sorted(defined - referenced)
+    lines: dict[str, int] = {}
+    if unused:
+        _definition_lines(script.body, script_dir, lines)
     for name in unused:
-        line = _definition_line(script.body, name)
+        line = lines.get(name, 0)
         issues.append(
             _issue(
                 "V002",
@@ -844,18 +883,15 @@ def _check_unused_variables(script: Script, defined: set[str], issues: list[_Iss
         )
 
 
-def _definition_line(nodes: list[Node], name: str) -> int:
-    """Line of the SUB that defines *name*, or 0 when it cannot be located."""
+def _definition_lines(nodes: list[Node], script_dir: Path | None, lines: dict[str, int]) -> None:
+    """Add to *lines* the line of the first metacommand that defines each variable, in script order."""
     for node in nodes:
         if isinstance(node, MetaCommandStatement):
             probe: set[str] = set()
-            _extract_var_definition(node.command, None, probe)
-            if name in probe:
-                return node.span.start_line
-        found = _definition_line(list(node.children()), name)
-        if found:
-            return found
-    return 0
+            _extract_var_definition(node.command, script_dir, probe)
+            for name in probe:
+                lines.setdefault(name, node.span.start_line)
+        _definition_lines(list(node.children()), script_dir, lines)
 
 
 # ---------------------------------------------------------------------------
@@ -995,7 +1031,7 @@ def lint(
     )
 
     # Pass 3: whole-script rules, which need every reference collected first
-    _check_unused_variables(script, all_defined, issues)
+    _check_unused_variables(script, all_defined, issues, script_dir)
 
     return issues
 

execsql/db/access.py

@@ -17,7 +17,7 @@ from typing import Any, cast
 from execsql.db.base import Database, _fetched
 from execsql.db.tiers import SupportTier
 from execsql.exceptions import ErrInfo
-from execsql.utils.errors import exception_desc, fatal_error
+from execsql.utils.errors import exception_desc, fatal_error, install_hint
 from execsql.utils.auth import (
     begin_login,
     clear_stored_password,
@@ -68,7 +68,7 @@ class AccessDatabase(Database):
         try:
             import pyodbc  # noqa: F401
         except Exception:
-            fatal_error("The pyodbc module is required.  See http://github.com/mkleehammer/pyodbc")
+            fatal_error(f"The pyodbc module is required to connect to Access. {install_hint('odbc')}")
         from execsql.types import dbt_access
 
         super().__init__(
@@ -327,8 +327,8 @@ class AccessDatabase(Database):
             rows = curs.fetchall()
             return [d[0] for d in curs.description], rows
 
-    def select_rowsource(self, sql: str) -> tuple[list[str], Any]:
-        """Return column names and an iterable that yields rows one at a time."""
+    def select_rowsource(self, sql: str, *, decode_bytes: bool = True) -> tuple[list[str], Any]:  # noqa: ARG002
+        """Return column names and an iterable that yields rows one at a time (values as the driver returns them)."""
         # Return 1) a list of column names, and 2) an iterable that yields rows.
         self.dao_flush_check()
         curs = self.cursor()

execsql/db/base.py

@@ -405,8 +405,13 @@ class Database(ABC):
             rows = curs.fetchall()
             return [d[0] for d in curs.description], rows
 
-    def select_rowsource(self, sql: str) -> tuple[list[str], Generator]:
-        """Execute *sql* and return ``(column_names, row_generator)`` for streaming large result sets."""
+    def select_rowsource(self, sql: str, *, decode_bytes: bool = True) -> tuple[list[str], Generator]:
+        """Execute *sql* and return ``(column_names, row_generator)`` for streaming large result sets.
+
+        A binary value (``bytes``) is decoded to text with the connection's
+        encoding, as the exporters expect, unless *decode_bytes* is false:
+        COPY passes false so binary columns reach the target unchanged.
+        """
         # Return 1) a list of column names, and 2) an iterable that yields rows.
         curs = self.cursor()
         try:
@@ -433,7 +438,7 @@ class Database(ABC):
                         break
                     else:
                         for row in rows:
-                            if self.encoding:
+                            if self.encoding and decode_bytes:
                                 yield [
                                     c.decode(self.encoding, "backslashreplace") if isinstance(c, bytes) else c
                                     for c in row
@@ -501,6 +506,15 @@ class Database(ABC):
         """The schema (MySQL: database) an unqualified table name is created in, or ``None`` if unknown."""
         return None
 
+    def table_exists_where_created(self, table_name: str, schema_name: str | None = None) -> bool:
+        """Whether *table_name* exists where a ``CREATE TABLE`` on this connection would put it.
+
+        The same as :meth:`table_exists`, except on a connection that sees
+        tables of other databases (DuckDB ``ATTACH``): only the current
+        database counts there.
+        """
+        return self.table_exists(table_name, schema_name)
+
     def _query_current_schema(self, sql: str) -> str | None:
         with self._cursor() as curs:
             curs.execute(sql)

execsql/db/dsn.py

@@ -12,7 +12,7 @@ the CLI.
 from execsql.db.base import Database
 from execsql.db.tiers import SupportTier
 from execsql.exceptions import ErrInfo
-from execsql.utils.errors import exception_desc, fatal_error
+from execsql.utils.errors import exception_desc, fatal_error, install_hint
 from execsql.utils.auth import (
     begin_login,
     clear_stored_password,
@@ -51,7 +51,7 @@ class DsnDatabase(Database):
         try:
             import pyodbc  # noqa: F401
         except Exception:
-            fatal_error("The pyodbc module is required.  See http://github.com/mkleehammer/pyodbc")
+            fatal_error(f"The pyodbc module is required to connect through an ODBC DSN. {install_hint('odbc')}")
         from execsql.types import dbt_dsn
 
         super().__init__(

execsql/db/duckdb.py

@@ -14,7 +14,7 @@ from typing import Any
 
 from execsql.db.base import Database, statement_start
 from execsql.exceptions import ErrInfo
-from execsql.utils.errors import exception_desc, fatal_error
+from execsql.utils.errors import exception_desc, fatal_error, install_hint
 import execsql.state as _state
 
 __all__ = ["DuckDBDatabase"]
@@ -62,7 +62,7 @@ class DuckDBDatabase(Database):
         try:
             import duckdb  # noqa: F401
         except Exception:
-            fatal_error("The duckdb module is required.")
+            fatal_error(f"The duckdb module is required to use DuckDB. {install_hint('duckdb')}")
         from execsql.types import dbt_duckdb
 
         super().__init__(
@@ -167,6 +167,18 @@ class DuckDBDatabase(Database):
                 self.rollback()
                 raise
 
+    def table_exists_where_created(self, table_name: str, schema_name: str | None = None) -> bool:
+        """Whether *table_name* exists in the current database (not an ``ATTACH``ed one)."""
+        # information_schema.tables lists the tables of every attached database.
+        sql = "select table_name from information_schema.tables where table_name = ? and table_catalog = current_database()"
+        params: list = [table_name]
+        if schema_name:
+            sql += " and table_schema = ?"
+            params.append(schema_name)
+        with self._cursor() as curs:
+            curs.execute(sql, params)
+            return len(curs.fetchall()) > 0
+
     def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
         """Return True if the named view exists in the DuckDB database."""
         # DuckDB information_schema has no 'views' table; views are listed in 'tables'

execsql/db/firebird.py

@@ -11,7 +11,7 @@ via the ``firebird-driver`` package.  Corresponds to ``-t f`` on the CLI.
 from execsql.db.base import Database
 from execsql.db.tiers import SupportTier
 from execsql.exceptions import ErrInfo
-from execsql.utils.errors import exception_desc, fatal_error
+from execsql.utils.errors import exception_desc, fatal_error, install_hint
 from execsql.utils.auth import (
     begin_login,
     clear_stored_password,
@@ -46,8 +46,7 @@ class FirebirdDatabase(Database):
             from firebird import driver as firebird_lib  # noqa: F401
         except Exception:
             fatal_error(
-                "The firebird-driver module is required to connect to Firebird.   "
-                "See https://pypi.org/project/firebird-driver/",
+                f"The firebird-driver module is required to connect to Firebird. {install_hint('firebird')}",
             )
         from execsql.types import dbt_firebird
 

execsql/db/mysql.py

@@ -12,7 +12,7 @@ from typing import Any, cast
 
 from execsql.db.base import Database
 from execsql.exceptions import ErrInfo
-from execsql.utils.errors import exception_desc, fatal_error
+from execsql.utils.errors import exception_desc, fatal_error, install_hint
 from execsql.utils.auth import (
     begin_login,
     clear_stored_password,
@@ -81,7 +81,7 @@ class MySQLDatabase(Database):
             import pymysql as mysql_lib  # noqa: F401
         except Exception:
             fatal_error(
-                "The pymysql module is required to connect to MySQL.   See https://pypi.python.org/pypi/PyMySQL",
+                f"The pymysql module is required to connect to MySQL. {install_hint('mysql')}",
             )
         from execsql.types import dbt_mysql