execsql2 2.9.0__tar.gz → 2.10.0__tar.gz

{execsql2-2.9.0 → execsql2-2.10.0}/CHANGELOG.md

@@ -13,6 +13,18 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.10.0] - 2026-04-01
+
+### Added
+
+- **`BREAKPOINT` metacommand** — pauses script execution and drops into an interactive debug REPL. The prompt accepts `continue`/`c` to resume, `abort`/`q` to halt, `vars` to list substitution variables, `$VARNAME` to print a single variable, `SELECT ...;` to run ad-hoc SQL against the current database, `next`/`n` to step one statement at a time, `stack` to inspect the command-list stack, and `help` for a command summary. Silently skipped in non-TTY environments (CI, piped input) so automated pipelines are never blocked.
+
+- **`step_mode` on `RuntimeContext`** — internal boolean flag set by the REPL's `next` command; the script engine re-enters the debug REPL after each subsequent statement while step mode is active.
+
+- **`ROW_COUNT_GT(table, N)`**, **`ROW_COUNT_GTE(table, N)`**, **`ROW_COUNT_EQ(table, N)`**, **`ROW_COUNT_LT(table, N)`** conditional tests — compare the row count of any table or view against an integer threshold using `IF`, `ELSEIF`, or `ASSERT`. Each issues a `SELECT count(*)` query against the current database. An error is raised if the table does not exist or the threshold is not an integer.
+
+______________________________________________________________________
+
 ## [2.9.0] - 2026-04-01
 
 ### Added

{execsql2-2.9.0 → execsql2-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.9.0
+Version: 2.10.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

{execsql2-2.9.0 → execsql2-2.10.0}/docs/about/divergence.md

@@ -39,11 +39,21 @@ ______________________________________________________________________
 
 ### Metacommands
 
-| Metacommand            | Description                                                                                                                                                           |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ASSERT`               | Evaluate a condition and raise an error (halting the script) if it is false. Supports all IF conditions. Optional quoted failure message. Skipped in false IF blocks. |
-| `CONFIG SHOW_PROGRESS` | Enable the Rich progress bar for IMPORT operations at runtime.                                                                                                        |
-| `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                 |
+| Metacommand            | Description                                                                                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ASSERT`               | Evaluate a condition and raise an error (halting the script) if it is false. Supports all IF conditions. Optional quoted failure message. Skipped in false IF blocks.          |
+| `BREAKPOINT`           | Pause script execution and drop into an interactive debug REPL. Inspect variables, run ad-hoc SQL, and step through the script. Silently skipped in non-TTY (CI) environments. |
+| `CONFIG SHOW_PROGRESS` | Enable the Rich progress bar for IMPORT operations at runtime.                                                                                                                 |
+| `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                          |
+
+### Conditional Tests
+
+| Conditional               | Description                                                                                              |
+| ------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `ROW_COUNT_GT(table, N)`  | True if the number of rows in *table* is strictly greater than *N* (integer). Queries `SELECT count(*)`. |
+| `ROW_COUNT_GTE(table, N)` | True if the number of rows in *table* is greater than or equal to *N*.                                   |
+| `ROW_COUNT_EQ(table, N)`  | True if the number of rows in *table* is exactly equal to *N*.                                           |
+| `ROW_COUNT_LT(table, N)`  | True if the number of rows in *table* is strictly less than *N*.                                         |
 
 ### Configuration Options
 

{execsql2-2.9.0 → execsql2-2.10.0}/docs/reference/metacommands.md

@@ -67,6 +67,7 @@ The `<condition>` supports all [conditional tests](metacommands.md#conditional_t
 - `HAS_ROWS(<table>)` / `NOT HAS_ROWS(<table>)`
 - `EQUAL(<val1>, <val2>)` / `NOT EQUAL(<val1>, <val2>)`
 - `IS_GT(<val1>, <val2>)`, `IS_GTE(<val1>, <val2>)`, `IS_ZERO(<val>)`
+- `ROW_COUNT_GT(<table>, N)`, `ROW_COUNT_GTE(<table>, N)`, `ROW_COUNT_EQ(<table>, N)`, `ROW_COUNT_LT(<table>, N)`
 - `DBMS(<type>)`, `SCHEMA_EXISTS(<schema>)`, `VIEW_EXISTS(<view>)`
 - Boolean combinators: `AND`, `OR`, `NOT`
 
@@ -116,6 +117,43 @@ The AUTOCOMMIT metacommand is database-specific, and affects only the database i
 The [IMPORT](#import) and [COPY](#copy) metacommands do not commit data changes while AUTOCOMMIT is off (except when the NEW or REPLACEMENT clauses are used with Firebird; in those cases the 'create table' statement that *execsql* generates and runs will be committed). The SQL statements generated by the [IMPORT](#import) and [COPY](#copy) metacommands are sent to the database, however. Therefore the AUTOCOMMIT metacommand is recommended when explicit transaction control is to be applied to the [IMPORT](#import) and [COPY](#copy) metacommands.
 
 
+## BREAKPOINT { #breakpoint }
+
+```
+BREAKPOINT
+```
+
+Pauses script execution and drops into an interactive debug REPL (read-eval-print loop) on the console. Use this to inspect state and step through a script interactively while debugging.
+
+**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:**
+
+| 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 |
+
+Pressing Ctrl-D (EOF) or Ctrl-C (KeyboardInterrupt) at the `execsql debug>` prompt resumes execution, the same as typing `continue`.
+
+**Example:**
+
+```sql
+INSERT INTO staging SELECT * FROM raw_data;
+-- !x! BREAKPOINT
+-- Script pauses here. Inspect variables, run queries, then continue.
+SELECT count(*) FROM staging;
+```
+
+BREAKPOINT is silently skipped inside a `False` [IF](#if_cmd) block.
+
+
 ## BEGIN BATCH and END BATCH { #batch }
 
 ```
@@ -1435,6 +1473,62 @@ IS_GTE(<value1>, <value2>)
 Evaluates whether or not the first of the specified values is greater than or equal to the second value. If the values are not numeric, an error will occur, and script processing will halt.
 
 
+### *ROW_COUNT_GT* { #row_count_gt }
+
+```
+ROW_COUNT_GT(<table_name>, <N>)
+```
+
+Evaluates whether the number of rows in the specified table or view is strictly greater than the integer *N*. Issues a `SELECT count(*)` query against the current database. An error will occur if the table does not exist or is not accessible.
+
+
+### *ROW_COUNT_GTE* { #row_count_gte }
+
+```
+ROW_COUNT_GTE(<table_name>, <N>)
+```
+
+Evaluates whether the number of rows in the specified table or view is greater than or equal to the integer *N*.
+
+
+### *ROW_COUNT_EQ* { #row_count_eq }
+
+```
+ROW_COUNT_EQ(<table_name>, <N>)
+```
+
+Evaluates whether the number of rows in the specified table or view is exactly equal to the integer *N*.
+
+
+### *ROW_COUNT_LT* { #row_count_lt }
+
+```
+ROW_COUNT_LT(<table_name>, <N>)
+```
+
+Evaluates whether the number of rows in the specified table or view is strictly less than the integer *N*.
+
+**Examples:**
+
+```sql
+-- Halt if the orders table is empty.
+-- !x! ASSERT ROW_COUNT_GT(orders, 0) "orders table must not be empty"
+
+-- Only process if staging has at least 1000 rows.
+-- !x! IF (ROW_COUNT_GTE(staging, 1000))
+-- !x!   WRITE "staging is ready"
+-- !x! ENDIF
+
+-- Verify exactly 12 monthly records were loaded.
+-- !x! ASSERT ROW_COUNT_EQ(monthly_totals, 12) "expected 12 monthly rows"
+
+-- Skip cleanup if the temp table already has fewer than 100 rows.
+-- !x! IF (ROW_COUNT_LT(temp_work, 100))
+-- !x!   WRITE "temp_work is small, skipping truncate"
+-- !x! ENDIF
+```
+
+
 ### *IS_NULL*
 
 ```

{execsql2-2.9.0 → execsql2-2.10.0}/extras/vscode-execsql/syntaxes/execsql.tmLanguage.json

@@ -93,7 +93,7 @@
     },
     "action-keywords": {
       "comment": "sub, write, execute script, export, etc.",
-      "match": "(?i)\\b(reset\\s+dialog_canceled|write\\s+create_table|export_metadata|sub_querystring|execute\\s+script|append\\s+script|extend\\s+script|reset\\s+counter|export\\s+query|sub_tempfile|write\\s+script|import_file|set\\s+counter|sub_decrypt|sub_encrypt|autocommit|copy\\s+query|disconnect|select_sub|sub_append|system_cmd|pg_vacuum|sub_empty|sub_local|connect|include|max_int|rm_file|subdata|sub_add|sub_ini|assert|export|import|rm_sub|debug|email|serve|write|copy|log|run|sub|use|zip|cd)\\b",
+      "match": "(?i)\\b(reset\\s+dialog_canceled|write\\s+create_table|export_metadata|sub_querystring|execute\\s+script|append\\s+script|extend\\s+script|reset\\s+counter|export\\s+query|sub_tempfile|write\\s+script|import_file|set\\s+counter|sub_decrypt|sub_encrypt|autocommit|breakpoint|copy\\s+query|disconnect|select_sub|sub_append|system_cmd|pg_vacuum|sub_empty|sub_local|connect|include|max_int|rm_file|subdata|sub_add|sub_ini|assert|export|import|rm_sub|debug|email|serve|write|copy|log|run|sub|use|zip|cd)\\b",
       "name": "keyword.other.execsql"
     },
     "config-event-keywords": {
@@ -108,7 +108,7 @@
     },
     "builtin-functions": {
       "comment": "Conditional test functions used in if/elseif",
-      "match": "(?i)\\b(metacommand_error|directory_exists|dialog_canceled|alias_defined|column_exists|database_name|schema_exists|script_exists|table_exists|file_exists|role_exists|starts_with|sub_defined|view_exists|console_on|newer_date|newer_file|ends_with|identical|sql_error|sub_empty|contains|is_false|hasrows|is_null|is_true|is_zero|is_gte|equal|is_gt|dbms|not|or)\\b",
+      "match": "(?i)\\b(metacommand_error|directory_exists|dialog_canceled|alias_defined|column_exists|database_name|row_count_gte|schema_exists|script_exists|row_count_eq|row_count_gt|row_count_lt|table_exists|file_exists|role_exists|starts_with|sub_defined|view_exists|console_on|newer_date|newer_file|ends_with|identical|sql_error|sub_empty|contains|is_false|hasrows|is_null|is_true|is_zero|is_gte|equal|is_gt|dbms|not|or)\\b",
       "name": "support.function.execsql"
     },
     "config-option-names": {

{execsql2-2.9.0 → execsql2-2.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.9.0"
+version = "2.10.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.9.0"
+current_version = "2.10.0"
 commit = true
 commit_args = "--no-verify"
 tag = true

{execsql2-2.9.0 → execsql2-2.10.0}/src/execsql/metacommands/__init__.py

@@ -100,6 +100,7 @@ from execsql.metacommands.debug import (
     x_debug_write_subvars,
     x_debug_write_config,
 )
+from execsql.metacommands.debug_repl import x_breakpoint
 from execsql.metacommands.io import (
     x_export,
     x_export_query,
@@ -300,6 +301,8 @@ __all__ = [
     "x_debug_log_config",
     "x_debug_write_subvars",
     "x_debug_write_config",
+    # debug repl handlers
+    "x_breakpoint",
     # io handlers
     "x_export",
     "x_export_query",

{execsql2-2.9.0 → execsql2-2.10.0}/src/execsql/metacommands/conditions.py

@@ -71,6 +71,124 @@ def xf_hasrows(**kwargs: Any) -> bool:
     return nrows > 0
 
 
+def _row_count(queryname: str, sql_context: str, metacommandline: str) -> int:
+    """Return the number of rows in *queryname*, raising ErrInfo on failure.
+
+    Args:
+        queryname: Table or view name to count rows in.
+        sql_context: The SQL string to include in error messages.
+        metacommandline: The full metacommand line for error context.
+
+    Returns:
+        Integer row count.
+
+    Raises:
+        ErrInfo: If the query fails or the result is not numeric.
+    """
+    sql = f"select count(*) from {queryname};"
+    try:
+        _hdrs, rec = _state.dbs.current().select_data(sql)
+    except ErrInfo:
+        raise
+    except Exception as e:
+        raise ErrInfo("db", sql, exception_msg=exception_desc()) from e
+    try:
+        return int(rec[0][0])
+    except (IndexError, TypeError, ValueError) as e:
+        raise ErrInfo(
+            type="cmd",
+            command_text=metacommandline,
+            other_msg=f"Could not read row count for {queryname}.",
+        ) from e
+
+
+def _parse_row_count_n(raw: str, metacommandline: str) -> int:
+    """Parse and return the numeric threshold N from the matched group.
+
+    Args:
+        raw: The raw string captured by the regex group (``n``).
+        metacommandline: The full metacommand line for error context.
+
+    Returns:
+        Integer value of *raw*.
+
+    Raises:
+        ErrInfo: If *raw* cannot be parsed as an integer.
+    """
+    try:
+        return int(raw.strip())
+    except (ValueError, TypeError) as e:
+        raise ErrInfo(
+            type="cmd",
+            command_text=metacommandline,
+            other_msg=f"ROW_COUNT threshold must be an integer; got {raw!r}.",
+        ) from e
+
+
+def xf_row_count_gt(**kwargs: Any) -> bool:
+    """Return True if the row count of *queryname* is strictly greater than N.
+
+    Args:
+        **kwargs: Named groups from the regex match, plus ``metacommandline``.
+            Required keys: ``queryname``, ``n``.
+
+    Returns:
+        True if ``count(*) > N``.
+    """
+    queryname = kwargs["queryname"]
+    mcl = kwargs["metacommandline"]
+    n = _parse_row_count_n(kwargs["n"], mcl)
+    return _row_count(queryname, f"select count(*) from {queryname};", mcl) > n
+
+
+def xf_row_count_gte(**kwargs: Any) -> bool:
+    """Return True if the row count of *queryname* is greater than or equal to N.
+
+    Args:
+        **kwargs: Named groups from the regex match, plus ``metacommandline``.
+            Required keys: ``queryname``, ``n``.
+
+    Returns:
+        True if ``count(*) >= N``.
+    """
+    queryname = kwargs["queryname"]
+    mcl = kwargs["metacommandline"]
+    n = _parse_row_count_n(kwargs["n"], mcl)
+    return _row_count(queryname, f"select count(*) from {queryname};", mcl) >= n
+
+
+def xf_row_count_eq(**kwargs: Any) -> bool:
+    """Return True if the row count of *queryname* equals N exactly.
+
+    Args:
+        **kwargs: Named groups from the regex match, plus ``metacommandline``.
+            Required keys: ``queryname``, ``n``.
+
+    Returns:
+        True if ``count(*) == N``.
+    """
+    queryname = kwargs["queryname"]
+    mcl = kwargs["metacommandline"]
+    n = _parse_row_count_n(kwargs["n"], mcl)
+    return _row_count(queryname, f"select count(*) from {queryname};", mcl) == n
+
+
+def xf_row_count_lt(**kwargs: Any) -> bool:
+    """Return True if the row count of *queryname* is strictly less than N.
+
+    Args:
+        **kwargs: Named groups from the regex match, plus ``metacommandline``.
+            Required keys: ``queryname``, ``n``.
+
+    Returns:
+        True if ``count(*) < N``.
+    """
+    queryname = kwargs["queryname"]
+    mcl = kwargs["metacommandline"]
+    n = _parse_row_count_n(kwargs["n"], mcl)
+    return _row_count(queryname, f"select count(*) from {queryname};", mcl) < n
+
+
 def xf_sqlerror(**kwargs: Any) -> bool:
     return _state.status.sql_error
 
@@ -495,6 +613,36 @@ def build_conditional_table() -> Any:
     mcl.add(r"^\s*HASROWS\((?P<queryname>[^)]+)\)", xf_hasrows, description="HASROWS", category="condition")
     mcl.add(r"^\s*HAS_ROWS\((?P<queryname>[^)]+)\)", xf_hasrows)
 
+    # ROW_COUNT comparisons — ROW_COUNT_GT/GTE/EQ/LT(table, N)
+    # Table name: unquoted, double-quoted, or single-quoted.  N: integer literal.
+    _rc_table = r"(?P<queryname>[A-Za-z0-9_.\"'\[\]]+)"
+    _rc_n = r"(?P<n>\d+)"
+    _rc_sep = r"\s*,\s*"
+    mcl.add(
+        rf"^\s*ROW_COUNT_GT\s*\(\s*{_rc_table}{_rc_sep}{_rc_n}\s*\)",
+        xf_row_count_gt,
+        description="ROW_COUNT_GT",
+        category="condition",
+    )
+    mcl.add(
+        rf"^\s*ROW_COUNT_GTE\s*\(\s*{_rc_table}{_rc_sep}{_rc_n}\s*\)",
+        xf_row_count_gte,
+        description="ROW_COUNT_GTE",
+        category="condition",
+    )
+    mcl.add(
+        rf"^\s*ROW_COUNT_EQ\s*\(\s*{_rc_table}{_rc_sep}{_rc_n}\s*\)",
+        xf_row_count_eq,
+        description="ROW_COUNT_EQ",
+        category="condition",
+    )
+    mcl.add(
+        rf"^\s*ROW_COUNT_LT\s*\(\s*{_rc_table}{_rc_sep}{_rc_n}\s*\)",
+        xf_row_count_lt,
+        description="ROW_COUNT_LT",
+        category="condition",
+    )
+
     # Status predicates
     mcl.add(r"^\s*sql_error\(\s*\)", xf_sqlerror, description="SQL_ERROR", category="condition")
     mcl.add(r"^\s*dialog_canceled\(\s*\)", xf_dialogcanceled, description="DIALOG_CANCELED", category="condition")

execsql2-2.10.0/src/execsql/metacommands/debug_repl.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+"""
+Interactive debug REPL metacommand handler for execsql.
+
+Implements ``x_breakpoint`` — the ``BREAKPOINT`` metacommand — which pauses
+script execution and drops into an interactive read-eval-print loop.
+
+The REPL allows the user to:
+
+- Inspect and print substitution variables.
+- Run ad-hoc SQL queries against the current database.
+- Step through the script one statement at a time.
+- Resume or abort execution.
+
+In non-interactive environments (CI, piped input, ``sys.stdin.isatty()`` is
+``False``) the metacommand is silently skipped so automated pipelines are not
+blocked.
+"""
+
+import sys
+from typing import Any
+
+import execsql.state as _state
+
+__all__ = ["x_breakpoint"]
+
+# ---------------------------------------------------------------------------
+# Public handler
+# ---------------------------------------------------------------------------
+
+_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
+"""
+
+
+def x_breakpoint(**kwargs: Any) -> None:
+    """Pause execution and enter the interactive debug REPL.
+
+    If ``sys.stdin`` is not a TTY (CI, piped input), the metacommand is
+    silently skipped — scripts will not hang in automation.
+
+    Args:
+        **kwargs: Keyword arguments injected by the dispatch table (unused).
+    """
+    if not sys.stdin.isatty():
+        return
+    _debug_repl()
+
+
+# ---------------------------------------------------------------------------
+# REPL core
+# ---------------------------------------------------------------------------
+
+
+def _debug_repl() -> None:
+    """Interactive read-eval-print loop for script debugging.
+
+    Reads commands from stdin until the user types ``continue`` or ``abort``,
+    or until EOF / KeyboardInterrupt.
+    """
+    try:
+        import readline as _readline  # noqa: F401 — side-effect: enables history/arrow keys
+    except ImportError:
+        pass  # readline not available on Windows; continue without it
+
+    _write("\n[Breakpoint] Script paused. Type 'help' for commands, 'continue' to resume.\n")
+
+    while True:
+        try:
+            line = input("execsql debug> ").strip()
+        except EOFError:
+            _write("\n")
+            return  # Ctrl-D → continue
+        except KeyboardInterrupt:
+            _write("\n")
+            return  # Ctrl-C → continue
+
+        if not line:
+            continue
+
+        lower = line.lower()
+
+        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(";"):
+            _run_sql(line)
+        else:
+            _write(f"Unknown command: {line!r}. Type 'help' for available commands.\n")
+
+
+# ---------------------------------------------------------------------------
+# REPL command implementations
+# ---------------------------------------------------------------------------
+
+
+def _write(text: str) -> None:
+    """Write *text* to the execsql output stream (falls back to stdout)."""
+    output = _state.output
+    if output is not None:
+        output.write(text)
+    else:
+        sys.stdout.write(text)
+        sys.stdout.flush()
+
+
+def _print_all_vars() -> None:
+    """Print all substitution variables and their current values."""
+    subvars = _state.subvars
+    if subvars is None:
+        _write("  (no substitution variables defined)\n")
+        return
+    items = subvars.substitutions  # list of (name, value) tuples
+    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)
+    for name, value in sorted(items):
+        _write(f"  {name:<{max_name}}  =  {value!r}\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``.
+    """
+    subvars = _state.subvars
+    if subvars is None:
+        _write(f"  {varname}: (substitution variables not initialised)\n")
+        return
+    # varvalue() expects the name with its prefix (e.g. "$foo"); it lowercases internally.
+    value = subvars.varvalue(varname)
+    if value is None:
+        _write(f"  {varname}: (undefined)\n")
+    else:
+        _write(f"  {varname} = {value!r}\n")
+
+
+def _print_stack() -> None:
+    """Print the current command-list stack (script name, line number, depth)."""
+    stack = _state.commandliststack
+    if not stack:
+        _write("  (command list stack is empty)\n")
+        return
+    _write(f"  Stack depth: {len(stack)}\n")
+    for depth, cmdlist in enumerate(stack):
+        listname = getattr(cmdlist, "listname", "<unknown>")
+        cmdptr = getattr(cmdlist, "cmdptr", 0)
+        _write(f"  [{depth}] {listname}  (cursor at index {cmdptr})\n")
+
+
+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.
+    """
+    dbs = _state.dbs
+    if dbs is None:
+        _write("  (no database connection is active)\n")
+        return
+    db = dbs.current()
+    if db is None:
+        _write("  (no database connection is active)\n")
+        return
+    try:
+        colnames, rows = db.select_data(sql)
+    except Exception as exc:
+        _write(f"  SQL error: {exc}\n")
+        return
+
+    if not colnames:
+        _write("  (query returned no columns)\n")
+        return
+
+    # Build a simple text table.
+    col_widths = [len(c) for c in colnames]
+    str_rows: list[list[str]] = []
+    for row in rows:
+        str_row = [str(v) if v is not None else "NULL" for v in row]
+        str_rows.append(str_row)
+        for i, cell in enumerate(str_row):
+            col_widths[i] = max(col_widths[i], len(cell))
+
+    sep = "+-" + "-+-".join("-" * w for w in col_widths) + "-+"
+    header = "| " + " | ".join(c.ljust(col_widths[i]) for i, c in enumerate(colnames)) + " |"
+    _write(sep + "\n")
+    _write(header + "\n")
+    _write(sep + "\n")
+    for str_row in str_rows:
+        data_line = "| " + " | ".join(cell.ljust(col_widths[i]) for i, cell in enumerate(str_row)) + " |"
+        _write(data_line + "\n")
+    _write(sep + "\n")
+    row_word = "row" if len(str_rows) == 1 else "rows"
+    _write(f"  ({len(str_rows)} {row_word})\n")
+
+
+def _enable_step_mode() -> None:
+    """Activate step mode so the engine re-enters the REPL after the next statement."""
+    _state.step_mode = True

{execsql2-2.9.0 → execsql2-2.10.0}/src/execsql/metacommands/dispatch.py

@@ -100,6 +100,7 @@ from execsql.metacommands.debug import (
     x_debug_write_odbc_drivers,
     x_debug_write_subvars,
 )
+from execsql.metacommands.debug_repl import x_breakpoint
 from execsql.metacommands.io import (
     x_cd,
     x_copy,
@@ -1690,6 +1691,17 @@ def build_dispatch_table() -> MetaCommandList:
         run_when_false=False,
     )
 
+    # ------------------------------------------------------------------
+    # BREAKPOINT
+    # ------------------------------------------------------------------
+    mcl.add(
+        r"^\s*BREAKPOINT\s*$",
+        x_breakpoint,
+        description="BREAKPOINT",
+        category="action",
+        run_when_false=False,
+    )
+
     # ------------------------------------------------------------------
     # IF / ORIF / ANDIF / ELSEIF / ELSE / ENDIF
     # ------------------------------------------------------------------

{execsql2-2.9.0 → execsql2-2.10.0}/src/execsql/script/engine.py

@@ -506,6 +506,11 @@ 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: