execsql2 2.10.1__tar.gz → 2.11.0__tar.gz

{execsql2-2.10.1 → execsql2-2.11.0}/CHANGELOG.md

@@ -13,6 +13,27 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.11.0] - 2026-04-01
+
+### Added
+
+- `--debug` CLI flag — starts the script in step-through debug mode. The debug REPL pauses before each statement, as if `BREAKPOINT` were inserted at the top with `.next` always active.
+
+### Changed
+
+- BREAKPOINT debug REPL now pauses **before** each statement instead of after, so the upcoming statement can be inspected before it runs.
+
+### Fixed
+
+- BREAKPOINT REPL no longer wraps variable values in extra single quotes — values are now displayed exactly as defined.
+- Error messages now include script file name and line number — `ErrInfo` fields `script_file` and `script_line_no` are populated via a new `stamp_errinfo()` helper called from `exit_now()` and metacommand error paths, restoring monolith-level "Line N of script foo.sql" context in all error output.
+- `$ERROR_MESSAGE` substitution variable is now updated on every error: in `exit_now()`, in non-halting SQL errors (`SqlStmt.run()`), and in non-halting metacommand errors (`MetacommandStmt.run()`). Previously it was initialized to `""` and never changed.
+- `MetacommandStmt.run()` now re-raises the original handler `ErrInfo` when `halt_on_metacommand_err` is True, instead of discarding it and raising a generic "Unknown metacommand" error.
+- `write_warning()` now accepts an `always=True` keyword argument that bypasses the `conf.write_warnings` gate, ensuring structural warnings (IF-level mismatch, unsubstituted variables) are always visible on stderr.
+- Uncaught-exception error message in `_execute_script_direct()` and `_execute_script_textual_console()` no longer appends "in script , line 0" when `current_script_line()` returns an empty string.
+
+______________________________________________________________________
+
 ## [2.10.1] - 2026-04-01
 
 ### Fixed

{execsql2-2.10.1 → execsql2-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.10.1
+Version: 2.11.0
 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
@@ -223,6 +223,7 @@ execsql script.sql                          # read connection from config file
 | `--dry-run`                         | Parse the script and report commands without executing          |
 | `--lint`                            | Static analysis: check structure and warn on issues (no DB)     |
 | `--progress`                        | Show a progress bar for long-running IMPORT operations          |
+| `--debug`                           | Start in step-through debug mode (REPL pauses before each stmt) |
 | `--dump-keywords`                   | Print metacommand keywords as JSON and exit                     |
 | `--gui-framework {tkinter,textual}` | GUI framework for interactive prompts                           |
 

{execsql2-2.10.1 → execsql2-2.11.0}/README.md

@@ -113,6 +113,7 @@ execsql script.sql                          # read connection from config file
 | `--dry-run`                         | Parse the script and report commands without executing          |
 | `--lint`                            | Static analysis: check structure and warn on issues (no DB)     |
 | `--progress`                        | Show a progress bar for long-running IMPORT operations          |
+| `--debug`                           | Start in step-through debug mode (REPL pauses before each stmt) |
 | `--dump-keywords`                   | Print metacommand keywords as JSON and exit                     |
 | `--gui-framework {tkinter,textual}` | GUI framework for interactive prompts                           |
 

{execsql2-2.10.1 → execsql2-2.11.0}/docs/about/divergence.md

@@ -22,6 +22,7 @@ ______________________________________________________________________
 | `--progress`                    | Show a Rich progress bar during long-running IMPORT operations.                                                                                                                                                                                                                                                                         |
 | `--dump-keywords`               | Emit all metacommand keywords, conditionals, config options, and export formats as structured JSON.                                                                                                                                                                                                                                     |
 | `--gui-framework`               | Select GUI backend: `tkinter` (default) or `textual` (terminal UI).                                                                                                                                                                                                                                                                     |
+| `--debug`                       | Start in step-through debug mode. The debug REPL pauses before each statement, as if `BREAKPOINT` were at the top with `.next` always active.                                                                                                                                                                                           |
 | `--dry-run`                     | Parse the script and print the full command list without connecting to a database or executing anything. Substitution variables already populated at parse time (env vars, `--assign-arg` values, built-in start-time vars) are expanded in the output; execution-time variables (`$DB_NAME`, `$CURRENT_TIME`, etc.) remain unexpanded. |
 | `--profile`                     | Record wall-clock time for each SQL and metacommand statement. After the script completes, print a summary table sorted by elapsed time (descending), showing time, percentage of total, source location, command type, and a command preview. Top 20 slowest statements are shown.                                                     |
 | `--ping`                        | Test database connectivity and exit. Connects using the supplied connection parameters, queries for the server version, and prints a one-line success message (exit 0) or the error (exit 1). No script file argument is required.                                                                                                      |
@@ -167,13 +168,17 @@ These are behavioral changes driven by security or correctness issues in the ups
 
 ### Bug Fixes
 
-| Area                              | Fix                                                                                                        |
-| --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| Oracle default port               | Corrected from `5432` (PostgreSQL) to `1521`.                                                              |
-| MySQL `LOAD DATA INFILE` encoding | Python encoding names are now mapped to MySQL charset names.                                               |
-| `dt_cast` type converters         | Base `Database` class auto-populates 8 type converters that were previously left empty after the refactor. |
-| `FileWriter` CPU busy-loop        | Uses blocking `queue.get(timeout=0.1)` instead of `get_nowait()` in a tight loop.                          |
-| Substitution variable cycles      | 100-iteration limit prevents infinite loops on cyclic variable references.                                 |
+| Area                              | Fix                                                                                                                                                                                           |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Oracle default port               | Corrected from `5432` (PostgreSQL) to `1521`.                                                                                                                                                 |
+| MySQL `LOAD DATA INFILE` encoding | Python encoding names are now mapped to MySQL charset names.                                                                                                                                  |
+| `dt_cast` type converters         | Base `Database` class auto-populates 8 type converters that were previously left empty after the refactor.                                                                                    |
+| `FileWriter` CPU busy-loop        | Uses blocking `queue.get(timeout=0.1)` instead of `get_nowait()` in a tight loop.                                                                                                             |
+| Substitution variable cycles      | 100-iteration limit prevents infinite loops on cyclic variable references.                                                                                                                    |
+| Script location in error messages | `ErrInfo.script_file` and `script_line_no` are now populated via `stamp_errinfo()` so error output includes "Line N of script foo.sql" context — restoring behavior present in the monolith.  |
+| `$ERROR_MESSAGE` not updated      | `$ERROR_MESSAGE` is now set on every error path: `exit_now()`, non-halting SQL errors, and non-halting metacommand errors. Previously it was initialized to `""` and never changed.           |
+| Metacommand error message lost    | When `halt_on_metacommand_err` is `ON`, the original handler `ErrInfo` is now re-raised; the generic "Unknown metacommand" message no longer replaces the specific error from the handler.    |
+| Empty script name in error msg    | `_execute_script_direct()` and `_execute_script_textual_console()` no longer append "in script , line 0" to uncaught-exception messages when `current_script_line()` returns an empty string. |
 
 ______________________________________________________________________
 

{execsql2-2.10.1 → execsql2-2.11.0}/docs/getting-started/syntax.md

@@ -224,6 +224,10 @@ Valid encoding names can be displayed with the `-y` option. See also [Character
     execsql --ping --dsn sqlite:///mydb.sqlite
     ```
 
+`--debug`
+
+:   Start in step-through debug mode. The debug REPL pauses before each statement, as if a `BREAKPOINT` metacommand were inserted at the top of the script with `.next` always active. Type `.continue` or `.c` at the REPL prompt to resume normal execution, or `.next` / `.n` to step one statement at a time. Silently skipped in non-TTY environments.
+
 `--profile`
 
 :   Record the wall-clock execution time of each SQL statement and metacommand. After the script finishes, print a summary table to the console showing elapsed time, percentage of total time, source file and line number, command type, and a preview of the command text. Statements are sorted from slowest to fastest; the top 20 are displayed. Useful for identifying slow queries or metacommands in long-running scripts.

{execsql2-2.10.1 → execsql2-2.11.0}/docs/reference/metacommands.md

@@ -127,20 +127,30 @@ Pauses script execution and drops into an interactive debug REPL (read-eval-prin
 
 **Non-interactive safety:** If `sys.stdin` is not a TTY (e.g. CI pipelines, piped input, batch execution) the metacommand is silently skipped. Scripts will never hang in automation.
 
-**REPL commands:**
+All REPL commands are dot-prefixed to avoid ambiguity with variable names and SQL. Anything without a dot prefix is treated as a variable lookup or SQL.
+
+**REPL commands (dot-prefixed):**
 
 | Command | Description |
 |---------|-------------|
-| `continue` or `c` | Resume script execution |
-| `abort`, `q`, or `quit` | Halt the script with exit status 1 |
-| `vars` | List all substitution variables and their current values |
-| `$VARNAME` | Print the value of a single variable (also `&VAR`, `@VAR`) |
-| `SELECT ...;` | Run an ad-hoc SQL query against the current database and pretty-print results |
-| `next` or `n` | Execute the next script statement, then pause again (step mode) |
-| `stack` | Show the command-list stack: script name, cursor index, and nesting depth |
-| `help` | Show the list of available REPL commands |
+| `.continue` or `.c` | Resume script execution |
+| `.abort` or `.q` | Halt the script with exit status 1 |
+| `.vars` | List user, system, local, and counter variables (grouped by type) |
+| `.vars all` | Include environment variables (`&`) in the listing |
+| `.next` or `.n` | Execute the next script statement, then pause again (step mode) |
+| `.stack` | Show the command-list stack: script name, cursor index, and nesting depth |
+| `.help` | Show the list of available REPL commands |
+
+**Variable inspection and SQL (no dot prefix):**
 
-Pressing Ctrl-D (EOF) or Ctrl-C (KeyboardInterrupt) at the `execsql debug>` prompt resumes execution, the same as typing `continue`.
+| Input | Description |
+|-------|-------------|
+| `logfile` | Print the value of the `logfile` variable |
+| `$ARG_1` | Print the value of a system/built-in variable |
+| `&HOME` | Print the value of an environment variable |
+| `SELECT ...;` | Run ad-hoc SQL against the current database and pretty-print results |
+
+Pressing Ctrl-D (EOF) or Ctrl-C (KeyboardInterrupt) at the `execsql debug>` prompt resumes execution, the same as typing `.continue`.
 
 **Example:**
 
@@ -153,6 +163,9 @@ SELECT count(*) FROM staging;
 
 BREAKPOINT is silently skipped inside a `False` [IF](#if_cmd) block.
 
+!!! tip
+    Use `execsql --debug script.sql` to start in step-through mode without adding a `BREAKPOINT` metacommand to your script. The REPL pauses before each statement.
+
 
 ## BEGIN BATCH and END BATCH { #batch }
 

{execsql2-2.10.1 → execsql2-2.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.10.1"
+version = "2.11.0"
 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" }
@@ -158,7 +158,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.10.1"
+current_version = "2.11.0"
 commit = true
 commit_args = "--no-verify"
 tag = true

{execsql2-2.10.1 → execsql2-2.11.0}/src/execsql/cli/__init__.py

@@ -278,6 +278,11 @@ def main(
         "--profile",
         help="Record per-statement execution times and print a timing summary after the script completes.",
     ),
+    debug: bool = typer.Option(
+        False,
+        "--debug",
+        help="Start in step-through debug mode. The debug REPL pauses before each statement.",
+    ),
     version: bool | None = typer.Option(
         None,
         "--version",
@@ -446,6 +451,7 @@ def main(
         profile=profile,
         ping=ping,
         lint=lint,
+        debug=debug,
     )
 
 

{execsql2-2.10.1 → execsql2-2.11.0}/src/execsql/cli/run.py

@@ -214,6 +214,7 @@ def _run(
     profile: bool = False,
     ping: bool = False,
     lint: bool = False,
+    debug: bool = False,
 ) -> None:
     """Initialise state, connect to the database, load the script, and run it.
 
@@ -547,6 +548,9 @@ def _run(
     if profile:
         _state.profile_data = []
 
+    if debug:
+        _state.step_mode = True
+
     _execute_script_direct(conf, profile=profile)
 
 
@@ -653,7 +657,7 @@ def _execute_script_direct(conf: ConfigData, *, profile: bool = False) -> None:
         lno = strace[0][1]
         msg = f"{Path(sys.argv[0]).name}: Uncaught exception {sys.exc_info()[0]} ({sys.exc_info()[1]}) on line {lno}"
         script, slno = current_script_line()
-        if script is not None:
+        if script:
             msg += f" in script {script}, line {slno}"
         from execsql.utils.errors import exit_now
 

{execsql2-2.10.1 → execsql2-2.11.0}/src/execsql/metacommands/debug_repl.py

@@ -13,6 +13,11 @@ The REPL allows the user to:
 - Step through the script one statement at a time.
 - Resume or abort execution.
 
+All REPL commands are dot-prefixed (``.continue``, ``.vars``, ``.next``)
+to avoid ambiguity with variable names and SQL.  Anything not starting
+with ``.`` is treated as either a variable lookup (if it matches a known
+variable) or SQL (if it ends with ``;``).
+
 In non-interactive environments (CI, piped input, ``sys.stdin.isatty()`` is
 ``False``) the metacommand is silently skipped so automated pipelines are not
 blocked.
@@ -30,15 +35,19 @@ __all__ = ["x_breakpoint"]
 # ---------------------------------------------------------------------------
 
 _HELP_TEXT = """\
-execsql debug REPL commands:
-  continue  c        Resume script execution
-  abort     q quit   Halt the script (exit 1)
-  vars               List all substitution variables and their values
-  $VARNAME           Print a single variable's value  (also &VAR, @VAR)
-  SELECT ...;        Run ad-hoc SQL against the current database
-  next      n        Execute the next statement then pause again (step mode)
-  stack              Show the command-list stack (script name, line, depth)
-  help               Show this help text
+execsql debug REPL — all commands start with '.'
+
+  .continue  .c       Resume script execution
+  .abort     .q       Halt the script (exit 1)
+  .vars               List user, system, local, and counter variables
+  .vars all           Include environment variables (&) in the listing
+  .next      .n       Execute the next statement then pause again (step mode)
+  .stack              Show the command-list stack (script name, line, depth)
+  .help               Show this help text
+
+Everything else:
+  varname             Print a variable's value (e.g. logfile, $ARG_1, &HOME)
+  SELECT ...;         Run ad-hoc SQL against the current database
 """
 
 
@@ -64,7 +73,7 @@ def x_breakpoint(**kwargs: Any) -> None:
 def _debug_repl() -> None:
     """Interactive read-eval-print loop for script debugging.
 
-    Reads commands from stdin until the user types ``continue`` or ``abort``,
+    Reads commands from stdin until the user types ``.continue`` or ``.abort``,
     or until EOF / KeyboardInterrupt.
     """
     try:
@@ -72,7 +81,7 @@ def _debug_repl() -> None:
     except ImportError:
         pass  # readline not available on Windows; continue without it
 
-    _write("\n[Breakpoint] Script paused. Type 'help' for commands, 'continue' to resume.\n")
+    _write("\n[Breakpoint] Script paused. Type '.help' for commands, '.c' to resume.\n")
 
     while True:
         try:
@@ -87,27 +96,48 @@ def _debug_repl() -> None:
         if not line:
             continue
 
-        lower = line.lower()
+        # Dot-prefixed → REPL command
+        if line.startswith("."):
+            _handle_dot_command(line)
+            if line.lower().lstrip(".") in ("continue", "c"):
+                return
+            if line.lower().lstrip(".") in ("abort", "q", "quit"):
+                # _handle_dot_command already raised SystemExit, but guard anyway
+                return
+            if line.lower().lstrip(".") in ("next", "n"):
+                return
+            continue
 
-        if lower in ("continue", "c"):
-            return
-        elif lower in ("abort", "q", "quit"):
-            raise SystemExit(1)
-        elif lower == "help":
-            _write(_HELP_TEXT)
-        elif lower == "vars":
-            _print_all_vars()
-        elif lower == "stack":
-            _print_stack()
-        elif lower in ("next", "n"):
-            _enable_step_mode()
-            return
-        elif line[0] in ("$", "&", "@"):
-            _print_var(line)
-        elif line.rstrip().endswith(";"):
+        # SQL (ends with semicolon)
+        if line.rstrip().endswith(";"):
             _run_sql(line)
-        else:
-            _write(f"Unknown command: {line!r}. Type 'help' for available commands.\n")
+            continue
+
+        # Everything else → variable lookup
+        _print_var(line)
+
+
+def _handle_dot_command(line: str) -> None:
+    """Dispatch a dot-prefixed REPL command."""
+    # Strip the leading dot and normalize
+    cmd = line[1:].strip().lower()
+
+    if cmd in ("continue", "c"):
+        return  # caller checks and returns from _debug_repl
+    elif cmd in ("abort", "q", "quit"):
+        raise SystemExit(1)
+    elif cmd == "help":
+        _write(_HELP_TEXT)
+    elif cmd == "vars all":
+        _print_all_vars(include_env=True)
+    elif cmd == "vars":
+        _print_all_vars()
+    elif cmd == "stack":
+        _print_stack()
+    elif cmd in ("next", "n"):
+        _enable_step_mode()
+    else:
+        _write(f"  Unknown command: {line!r}. Type '.help' for available commands.\n")
 
 
 # ---------------------------------------------------------------------------
@@ -125,8 +155,8 @@ def _write(text: str) -> None:
         sys.stdout.flush()
 
 
-def _print_all_vars() -> None:
-    """Print all substitution variables and their current values."""
+def _print_all_vars(*, include_env: bool = False) -> None:
+    """Print substitution variables grouped by type."""
     subvars = _state.subvars
     if subvars is None:
         _write("  (no substitution variables defined)\n")
@@ -135,17 +165,52 @@ def _print_all_vars() -> None:
     if not items:
         _write("  (no substitution variables defined)\n")
         return
-    # Compute column width for aligned output.
-    max_name = max((len(name) for name, _ in items), default=0)
+
+    # Group by prefix.
+    user_vars: list[tuple[str, str]] = []
+    system_vars: list[tuple[str, str]] = []
+    counter_vars: list[tuple[str, str]] = []
+    local_vars: list[tuple[str, str]] = []
+    env_vars: list[tuple[str, str]] = []
+
     for name, value in sorted(items):
-        _write(f"  {name:<{max_name}}  =  {value!r}\n")
+        if name.startswith("&"):
+            env_vars.append((name, value))
+        elif name.startswith("~"):
+            local_vars.append((name, value))
+        elif name.startswith("@"):
+            counter_vars.append((name, value))
+        elif name.startswith("$"):
+            system_vars.append((name, value))
+        else:
+            user_vars.append((name, value))
+
+    def _print_group(label: str, group: list[tuple[str, str]]) -> None:
+        if not group:
+            return
+        _write(f"  {label}:\n")
+        max_name = max(len(n) for n, _ in group)
+        for name, value in group:
+            _write(f"    {name:<{max_name}}  =  {value}\n")
+
+    _print_group("User variables", user_vars)
+    _print_group("System variables ($)", system_vars)
+    _print_group("Local variables (~)", local_vars)
+    _print_group("Counter variables (@)", counter_vars)
+    if include_env:
+        _print_group("Environment variables (&)", env_vars)
+
+    if not any([user_vars, system_vars, local_vars, counter_vars]):
+        if env_vars:
+            _write("  (no script variables defined — use '.vars all' to see environment variables)\n")
+        else:
+            _write("  (no variables defined)\n")
 
 
 def _print_var(varname: str) -> None:
     """Print the value of a single substitution variable.
 
-    Args:
-        varname: The variable reference as typed by the user, e.g. ``$FOO``.
+    Tries the name as typed, then with the sigil prefix stripped.
     """
     subvars = _state.subvars
     if subvars is None:
@@ -153,14 +218,14 @@ def _print_var(varname: str) -> None:
         return
     # Try the name as typed first, then without the sigil prefix ($, &, @, #, ~).
     # SUB creates variables without a prefix (e.g., "logfile"), but users
-    # naturally type "$logfile" at the prompt.
+    # may type "$logfile" at the prompt.
     value = subvars.varvalue(varname)
     if value is None and len(varname) > 1 and varname[0] in "$&@#~":
         value = subvars.varvalue(varname[1:])
     if value is None:
         _write(f"  {varname}: (undefined)\n")
     else:
-        _write(f"  {varname} = {value!r}\n")
+        _write(f"  {varname} = {value}\n")
 
 
 def _print_stack() -> None:
@@ -177,11 +242,7 @@ def _print_stack() -> None:
 
 
 def _run_sql(sql: str) -> None:
-    """Execute ad-hoc SQL against the current database and pretty-print the results.
-
-    Args:
-        sql: A complete SQL statement ending with a semicolon.
-    """
+    """Execute ad-hoc SQL against the current database and pretty-print the results."""
     dbs = _state.dbs
     if dbs is None:
         _write("  (no database connection is active)\n")

{execsql2-2.10.1 → execsql2-2.11.0}/src/execsql/script/engine.py

@@ -306,6 +306,7 @@ class SqlStmt:
                 e = ErrInfo(type="exception", exception_msg=exception_desc())
             if e:
                 _state.subvars.add_substitution("$LAST_ERROR", cmd)
+                _state.subvars.add_substitution("$ERROR_MESSAGE", str(e))
                 _state.status.sql_error = True
                 if _state.status.halt_on_err:
                     from execsql.utils.errors import exit_now
@@ -350,8 +351,11 @@ class MetacommandStmt:
         if e:
             _state.status.metacommand_error = True
             _state.subvars.add_substitution("$LAST_ERROR", cmd)
+            _state.subvars.add_substitution("$ERROR_MESSAGE", str(e))
             if _state.status.halt_on_metacommand_err:
-                raise ErrInfo(type="cmd", command_text=cmd, other_msg=errmsg)
+                # Re-raise the original ErrInfo so its message is preserved, not
+                # replaced with the generic "Unknown metacommand" text.
+                raise e
         if _state.if_stack.all_true():
             # but nothing applies, because we got here.
             _state.status.metacommand_error = True
@@ -489,6 +493,11 @@ class CommandList:
             _state.subvars.add_substitution("$CURRENT_SCRIPT_NAME", Path(cmditem.source).name)
             _state.subvars.add_substitution("$CURRENT_SCRIPT_LINE", str(cmditem.line_no))
             _state.subvars.add_substitution("$SCRIPT_LINE", str(cmditem.line_no))
+            if _state.step_mode:
+                _state.step_mode = False
+                from execsql.metacommands.debug_repl import _debug_repl
+
+                _debug_repl()
             _profiling = _state.profile_data is not None
             if _profiling:
                 import time as _time
@@ -506,11 +515,6 @@ class CommandList:
                         cmditem.command.commandline()[:100],
                     ),
                 )
-            if _state.step_mode:
-                _state.step_mode = False
-                from execsql.metacommands.debug_repl import _debug_repl
-
-                _debug_repl()
         self.cmdptr += 1
 
     def run_next(self) -> None:

{execsql2-2.10.1 → execsql2-2.11.0}/src/execsql/utils/errors.py

@@ -30,6 +30,7 @@ __all__ = [
     "exception_desc",
     "exit_now",
     "fatal_error",
+    "stamp_errinfo",
     "write_warning",
     "file_size_date",
     "chainfuncs",
@@ -70,9 +71,37 @@ def exception_desc() -> str:
     return f"{exc_type}: {exc_strval} in {exc_filename} on line {exc_lineno} of execsql."
 
 
+def stamp_errinfo(errinfo: ErrInfo) -> ErrInfo:
+    """Attach script location from ``_state.last_command`` to an :class:`~execsql.exceptions.ErrInfo`.
+
+    Reads the source file name, line number, command text, and command type from
+    the most-recently-executed :class:`~execsql.script.engine.ScriptCmd` and
+    populates any ``None`` fields on *errinfo*.  This ensures that error messages
+    include "Line N of script foo.sql" context even when the ErrInfo was originally
+    created deep inside a handler that had no access to execution state.
+
+    Args:
+        errinfo: The :class:`~execsql.exceptions.ErrInfo` to stamp.
+
+    Returns:
+        The same *errinfo* object, with location fields populated.
+    """
+    lc = _state.last_command
+    if lc is not None and errinfo.script_file is None:
+        errinfo.script_file = lc.source
+        errinfo.script_line_no = lc.line_no
+        if errinfo.cmd is None:
+            errinfo.cmd = lc.command.commandline() if hasattr(lc.command, "commandline") else None
+            errinfo.cmdtype = lc.command_type
+    return errinfo
+
+
 def exit_now(exit_status: int, errinfo: ErrInfo | None, logmsg: str | None = None) -> None:
     em = None
     if errinfo is not None:
+        stamp_errinfo(errinfo)
+        if _state.subvars is not None:
+            _state.subvars.add_substitution("$ERROR_MESSAGE", errinfo.errmsg())
         em = errinfo.write()
         if _state.err_halt_writespec is not None:
             try:
@@ -147,10 +176,20 @@ def fatal_error(error_msg: str | None = None) -> None:
     exit_now(1, ErrInfo("error", other_msg=error_msg))
 
 
-def write_warning(warning_msg: str) -> None:
+def write_warning(warning_msg: str, *, always: bool = False) -> None:
+    """Write a non-fatal warning message to the log and optionally to stderr.
+
+    Args:
+        warning_msg: The warning text to emit.
+        always: When ``True``, always write to stderr regardless of the
+            ``conf.write_warnings`` setting.  Use this for structural warnings
+            (e.g. IF-level mismatch, unsubstituted variables) that should always
+            be visible.  When ``False`` (default), stderr output is gated by
+            ``conf.write_warnings``.
+    """
     if _state.exec_log is not None:
         _state.exec_log.log_status_warning(warning_msg)
-    if _state.conf is not None and _state.conf.write_warnings and _state.output is not None:
+    if _state.output is not None and (always or (_state.conf is not None and _state.conf.write_warnings)):
         _state.output.write_err(f"**** Warning {warning_msg}")