execsql2 2.35.0__py3-none-any.whl → 2.37.0__py3-none-any.whl

execsql/api.py

@@ -540,8 +540,8 @@ def run(
                 errors.append(
                     ScriptError(
                         message=exc.errmsg(),
-                        source=_last_source(ctx),
-                        line=_last_line(ctx),
+                        source=_last_source(ctx, exc),
+                        line=_last_line(ctx, exc),
                         sql=getattr(exc, "command_text", None),
                     ),
                 )
@@ -655,8 +655,8 @@ def _capture_errors(ctx: RuntimeContext, errors: list[ScriptError], exit_code: A
     errors.append(
         ScriptError(
             message=msg,
-            source=_last_source(ctx),
-            line=_last_line(ctx),
+            source=_last_source(ctx, err),
+            line=_last_line(ctx, err),
             sql=sql,
         ),
     )
@@ -680,16 +680,24 @@ def _error_text(exc: BaseException) -> str:
     return exc.errmsg() if isinstance(exc, ErrInfo) else str(exc)
 
 
-def _last_source(ctx: RuntimeContext) -> str:
-    """Get the source file from the last executed command."""
+def _last_source(ctx: RuntimeContext, err: ErrInfo | None = None) -> str:
+    """The source file of *err*, as its report gives it, else of the last executed command.
+
+    An error can name a line other than the statement on record: an ELSEIF,
+    ANDIF or ORIF condition, or a loop condition evaluated after its body.
+    """
+    if err is not None and err.script_file and err.script_line_no:
+        return err.script_file
     lc = ctx.last_command
     if lc is not None and hasattr(lc, "source"):
         return cast(str, lc.source)
     return "<unknown>"
 
 
-def _last_line(ctx: RuntimeContext) -> int | None:
-    """Get the line number from the last executed command."""
+def _last_line(ctx: RuntimeContext, err: ErrInfo | None = None) -> int | None:
+    """The line of *err*, as its report gives it, else of the last executed command (see :func:`_last_source`)."""
+    if err is not None and err.script_file and err.script_line_no:
+        return err.script_line_no
     lc = ctx.last_command
     if lc is not None and hasattr(lc, "line_no"):
         return cast(int | None, lc.line_no)

execsql/cli/lint.py

@@ -58,6 +58,7 @@ from typing import TYPE_CHECKING, NamedTuple
 
 from execsql.utils.paths import is_network_path
 from execsql.exceptions import ErrInfo
+from execsql.script.parser import strip_quotes
 from execsql.script.ast import (
     BatchBlock,
     Comment,
@@ -857,10 +858,13 @@ def _referencing_text(node: Node) -> list[str]:
         texts.append(node.command)
     elif isinstance(node, IncludeDirective):
         texts.append(node.target)
+        texts.extend(t for t in (node.arguments, node.loop_condition) if t)
     if isinstance(node, IfBlock):
         texts.append(node.condition)
         texts.extend(m.condition for m in node.condition_modifiers)
-        texts.extend(c.condition for c in node.elseif_clauses)
+        for clause in node.elseif_clauses:
+            texts.append(clause.condition)
+            texts.extend(m.condition for m in clause.condition_modifiers)
     elif isinstance(node, LoopBlock):
         texts.append(node.condition)
     return texts
@@ -913,6 +917,24 @@ def _definition_lines(nodes: list[Node], script_dir: Path | None, lines: dict[st
 # ---------------------------------------------------------------------------
 
 
+_RX_FILE_EXISTS = re.compile(r"^\s*FILE_EXISTS\s*\(\s*(?P<path>.+?)\s*\)\s*$", re.I)
+
+
+def _file_exists_guards(condition: str, modifiers: list[ConditionModifier]) -> frozenset[str]:
+    """The files an IF branch runs only if they exist: ``IF (FILE_EXISTS(f))``, with any ``ANDIF (FILE_EXISTS(g))``.
+
+    An ``ORIF`` lets the branch run without the file, so it guards nothing.
+    """
+    if any(m.kind == "OR" for m in modifiers):
+        return frozenset()
+    paths = set()
+    for cond in [condition, *(m.condition for m in modifiers)]:
+        m = _RX_FILE_EXISTS.match(cond)
+        if m:
+            paths.add(strip_quotes(m.group("path")))
+    return frozenset(paths)
+
+
 def _lint_nodes(
     nodes: list[Node],
     script_dir: Path | None,
@@ -921,8 +943,13 @@ def _lint_nodes(
     issues: list[_Issue],
     *,
     visited_scripts: set[str] | None = None,
+    guarded: frozenset[str] = frozenset(),
 ) -> None:
-    """Walk a list of AST nodes and collect lint issues."""
+    """Walk a list of AST nodes and collect lint issues.
+
+    *guarded* holds the files an enclosing ``IF (FILE_EXISTS(…))`` has
+    checked, so an ``INCLUDE`` of one is not reported as missing.
+    """
     if visited_scripts is None:
         visited_scripts = set()
 
@@ -947,6 +974,9 @@ def _lint_nodes(
 
         # -- IncludeDirective checks --
         elif isinstance(node, IncludeDirective):
+            for text in (node.target, node.arguments, node.loop_condition):
+                for name in _unresolved_var_refs(text or "", defined_vars):
+                    _check_var_ref(name, src, lno, defined_vars, issues)
             if node.is_execute_script:
                 target = node.target.lower()
                 if target not in script_blocks:
@@ -967,14 +997,22 @@ def _lint_nodes(
             else:
                 # INCLUDE file existence check
                 if not node.if_exists:
-                    raw_path = node.target.strip().strip("\"'")
-                    if not _RX_VAR_REF.search(raw_path):
+                    raw_path = strip_quotes(node.target.strip())
+                    if not _RX_VAR_REF.search(raw_path) and raw_path not in guarded:
                         _check_include_path(raw_path, script_dir, src, lno, issues)
 
         # -- Recurse into block children --
         if isinstance(node, IfBlock):
             _check_constant_condition(node, issues)
-            _lint_nodes(node.body, script_dir, defined_vars, script_blocks, issues, visited_scripts=visited_scripts)
+            _lint_nodes(
+                node.body,
+                script_dir,
+                defined_vars,
+                script_blocks,
+                issues,
+                visited_scripts=visited_scripts,
+                guarded=guarded | _file_exists_guards(node.condition, node.condition_modifiers),
+            )
             for clause in node.elseif_clauses:
                 _lint_nodes(
                     clause.body,
@@ -983,6 +1021,7 @@ def _lint_nodes(
                     script_blocks,
                     issues,
                     visited_scripts=visited_scripts,
+                    guarded=guarded | _file_exists_guards(clause.condition, clause.condition_modifiers),
                 )
             _lint_nodes(
                 node.else_body,
@@ -991,9 +1030,18 @@ def _lint_nodes(
                 script_blocks,
                 issues,
                 visited_scripts=visited_scripts,
+                guarded=guarded,
             )
         elif isinstance(node, (LoopBlock, BatchBlock, SqlBlock)):
-            _lint_nodes(node.body, script_dir, defined_vars, script_blocks, issues, visited_scripts=visited_scripts)
+            _lint_nodes(
+                node.body,
+                script_dir,
+                defined_vars,
+                script_blocks,
+                issues,
+                visited_scripts=visited_scripts,
+                guarded=guarded,
+            )
         elif isinstance(node, ScriptBlock):
             # Lint the block body once (structural errors are caught by the
             # parser). Issues carry their own line, which already places them

execsql/cli/run.py

@@ -47,14 +47,14 @@ def _print_dry_run(tree: Script | None) -> None:
     source location. Variables already populated at parse time are expanded;
     execution-time variables remain unexpanded.
     """
-    from execsql.script.ast import MetaCommandStatement, SqlStatement
+    from execsql.script.ast import IncludeDirective, MetaCommandStatement, SqlStatement
 
     if tree is None:
         _console.print("[yellow]No commands found in script.[/yellow]")
         return
     nodes = list(tree.walk())
-    # Count only executable nodes (SQL and metacommands)
-    executable = [n for n in nodes if isinstance(n, (SqlStatement, MetaCommandStatement))]
+    # Count only executable nodes (SQL, metacommands, INCLUDE and EXECUTE SCRIPT)
+    executable = [n for n in nodes if isinstance(n, (SqlStatement, MetaCommandStatement, IncludeDirective))]
     if not executable:
         _console.print("[yellow]No commands found in script.[/yellow]")
         return
@@ -871,14 +871,9 @@ def _end_run_on_sigterm() -> None:
     """
     import signal
 
-    def _terminate(signum: int, _frame: Any) -> None:
-        import execsql.state as _state
+    from execsql.utils.sigterm import terminate
 
-        if _state.exec_log is not None:
-            _state.exec_log.log_exit_terminated()
-        raise SystemExit(128 + signum)
-
-    signal.signal(signal.SIGTERM, _terminate)
+    signal.signal(signal.SIGTERM, terminate)
 
 
 def _execute_script_ast(

execsql/data/execsql.conf.template

@@ -326,19 +326,22 @@
 # Values: Yes or No.  Default: Yes.
 #allow_serve=Yes
 
-# Root directory under which INCLUDE / EXECUTE SCRIPT targets must
-# resolve. When set, attempts to include files outside this root via
-# ../, absolute paths, drive letters, or UNC paths are rejected with
-# an error. Default: no containment (any readable path is permitted).
+# Root directory under which the files INCLUDE reads must resolve.
+# When set, attempts to include files outside this root via ../,
+# absolute paths, drive letters, or UNC paths are rejected with an
+# error that stops the run, even with METACOMMAND_ERROR_HALT OFF.
+# Default: no containment (any readable path is permitted).
 #include_root=
 
 # Root directory under which SERVE targets must resolve. Same
-# containment semantics as include_root. Default: no containment.
+# containment checks as include_root, but a refused path is an
+# ordinary metacommand error. Default: no containment.
 #serve_root=
 
 # Root directory under which Jinja2 / string.Template loader paths
-# must resolve. Same containment semantics as include_root.
-# Default: no containment.
+# must resolve. Same containment checks as include_root, but a
+# refused path is an ordinary metacommand error. Default: no
+# containment.
 #template_root=
 
 # Maximum byte size of any single substitution-variable expansion,

execsql/db/base.py

@@ -352,9 +352,19 @@ class Database(ABC):
         self.autocommit = False
 
     def commit(self) -> None:
-        """Commit the current transaction if autocommit is enabled."""
+        """Commit the current transaction if autocommit is enabled.
+
+        A commit that fails (a deferred constraint, a lock) rolls the
+        transaction back before the error is raised: some DBMSs (SQLite)
+        keep it open, and the next commit on the connection would store
+        what was just reported as failed.
+        """
         if self.conn and self.autocommit:
-            self.conn.commit()
+            try:
+                self.conn.commit()
+            except BaseException:
+                self.rollback()
+                raise
 
     def rollback(self) -> None:
         """Roll back the current transaction; swallows errors (best-effort)."""

execsql/db/duckdb.py

@@ -253,7 +253,14 @@ class DuckDBDatabase(Database):
 
     def commit(self) -> None:
         """Commit the open transaction if autocommit is enabled."""
-        self._take_connection()
+        try:
+            # Reading ahead another cursor's result can raise (DuckDB reports
+            # some errors at fetch time); roll back as a failed commit does.
+            self._take_connection()
+        except BaseException:
+            if self.autocommit and self.in_transaction:
+                self.rollback()
+            raise
         super().commit()
         if self.autocommit:
             self.in_transaction = False

execsql/debug/repl.py

@@ -6,8 +6,8 @@ Input runs as if it were written where the script paused, through
 :mod:`execsql.interactive`: SQL (ending with ``;``, results shown as tables),
 metacommands and blocks, in the paused script's variable scope and
 transaction. A ``SUB`` typed here is still set
-when the script resumes; a ``BREAK`` inside a LOOP leaves the loop; ``HALT``
-ends the run. An error ends only the input that caused it.
+when the script resumes; a ``BREAK`` leaves the LOOP, SCRIPT or included file
+the script paused in; ``HALT`` ends the run. An error ends only the input that caused it.
 
 Commands to the REPL itself start with ``.``: ``.continue`` and ``.next``
 resume the script, ``.where`` and ``.stack`` show where it paused, ``.quit``

execsql/metacommands/connect.py

@@ -461,15 +461,16 @@ def x_use(**kwargs: Any) -> None:
 def x_disconnect(**kwargs: Any) -> None:
     alias = kwargs["alias"]
     current_alias = _state.dbs.current_alias()
-    if alias is None:
-        alias = _state.dbs.current_alias()
-    if alias.lower() == "initial":
-        raise ErrInfo(type="error", other_msg="You may not disconnect from the initial database used.")
-    if _state.status.batch.uses_db(alias):
-        raise ErrInfo(
-            type="error",
-            other_msg="You may not disconnect from a database that is currently used in a batch.",
-        )
+    # Aliases are stored lowercase (DatabasePool.add), as USE expects.
+    alias = current_alias if alias is None else alias.lower()
+    # type="cmd": reported as a metacommand error; the engine adds the
+    # "Metacommand: DISCONNECT ..." line itself.
+    if alias == "initial":
+        raise ErrInfo(type="cmd", other_msg="You may not disconnect from the initial database used.")
+    if alias not in _state.dbs.aliases():
+        raise ErrInfo(type="cmd", other_msg=f"Unrecognized database alias: {alias}.")
+    if _state.status.batch.uses_db(_state.dbs.aliased_as(alias)):
+        raise ErrInfo(type="cmd", other_msg="You may not disconnect from a database that is currently used in a batch.")
     _state.exec_log.log_status_info(f"Disconnecting from database with alias '{alias}'")
     if alias == current_alias:
         _state.dbs.make_current("initial")

execsql/metacommands/io_fileops.py

@@ -67,11 +67,14 @@ def _close_rowsource(rows: Any) -> None:
 
 
 def x_include(**kwargs: Any) -> None:
-    # INCLUDE is now handled natively by the AST executor (_execute_include_native).
-    # This handler exists only for dispatch table registration compatibility.
+    # The executor runs INCLUDE itself (an IncludeDirective) wherever the
+    # script writes it. Only a metacommand whose text a substitution variable
+    # supplies (-- !x! !!cmd!!) reaches the dispatch table. The entry also
+    # gives INCLUDE its place in the keyword list, the language server and the
+    # run manifest.
     raise ErrInfo(
         type="cmd",
-        other_msg="INCLUDE should be handled by the AST executor, not the dispatch table.",
+        other_msg="An INCLUDE that a substitution variable supplies cannot run; write the INCLUDE in the script.",
     )
 
 

execsql/metacommands/io_write.py

@@ -261,11 +261,13 @@ def _render_script_nodes(nodes: Any, emit: Any) -> None:
             # Preserve comment text verbatim; the parser stores it including
             # the leading "--" / "/* ... */" delimiters.
             emit(f"{node.text}\n")
+        elif isinstance(node, IncludeDirective) and node.command:
+            emit(f"-- !x! {node.command}\n")
         elif isinstance(node, IncludeDirective):
             kw = "EXECUTE SCRIPT" if node.is_execute_script else "INCLUDE"
             if_exists = " IF EXISTS" if node.if_exists else ""
             args = f" ({node.arguments})" if node.arguments else ""
-            loop = f" LOOP {node.loop_type} ({node.loop_condition})" if node.loop_type else ""
+            loop = f" {node.loop_type} ({node.loop_condition})" if node.loop_type else ""
             emit(f"-- !x! {kw}{if_exists} {node.target}{args}{loop}\n")
         elif isinstance(node, IfBlock):
             emit(f"-- !x! IF ({node.condition})\n")

execsql/metacommands/script_ext.py

@@ -11,10 +11,11 @@ AST executor:
   an inline source).
 - ``x_extendscript_metacommand`` — ``EXTEND SCRIPT … WITH METACOMMAND …``.
 - ``x_extendscript_sql`` — ``EXTEND SCRIPT … WITH SQL …``.
-- ``x_executescript`` — dispatch-table sentinel only. ``EXECUTE SCRIPT``
-  / ``RUN SCRIPT`` are handled natively by the AST executor; this stub
-  raises ``ErrInfo`` if the parser ever fails to recognize them as
-  structural nodes.
+- ``x_executescript`` — dispatch-table entry. The executor runs
+  ``EXECUTE SCRIPT`` / ``RUN SCRIPT`` itself wherever the script writes them
+  (a line of their own, an inline ``IF``, ``EXTEND SCRIPT … WITH
+  METACOMMAND``); this stub is reached only by one that a substitution
+  variable supplies, and reports that it cannot run.
 
 Registration of ``BEGIN SCRIPT … END SCRIPT`` blocks themselves is
 handled by the AST parser (block boundaries) and executor (registering
@@ -68,12 +69,12 @@ def x_extendscript(**kwargs: Any) -> None:
 
 def x_extendscript_metacommand(**kwargs: Any) -> None:
     """Append a single metacommand line to an existing SCRIPT body."""
-    from execsql.script.ast import MetaCommandStatement
+    from execsql.script.parser import metacommand_node
 
     block = _get_ast_script(kwargs["script"])
     script_file, script_line_no = current_script_line()
     span = _new_span(script_file, script_line_no or 0)
-    block.body.append(MetaCommandStatement(span=span, command=kwargs["cmd"]))
+    block.body.append(metacommand_node(kwargs["cmd"].strip(), span))
 
 
 def x_extendscript_sql(**kwargs: Any) -> None:
@@ -87,10 +88,12 @@ def x_extendscript_sql(**kwargs: Any) -> None:
 
 
 def x_executescript(**kwargs: Any) -> None:
-    # EXECUTE SCRIPT is now handled natively by the AST executor
-    # (_execute_include / _execute_script_native). This handler exists only
-    # for dispatch table registration compatibility.
+    # The executor runs EXECUTE SCRIPT itself (an IncludeDirective) wherever
+    # the script writes it. Only a metacommand whose text a substitution
+    # variable supplies (-- !x! !!cmd!!) reaches the dispatch table. The entry
+    # also gives EXECUTE / RUN SCRIPT their place in the keyword list, the
+    # language server and the run manifest.
     raise ErrInfo(
         "cmd",
-        other_msg="EXECUTE SCRIPT should be handled by the AST executor, not the dispatch table.",
+        other_msg="An EXECUTE SCRIPT that a substitution variable supplies cannot run; write it in the script.",
     )

execsql/metacommands/system.py

@@ -33,6 +33,7 @@ from execsql.utils.gui import (
     gui_console_width,
 )
 from execsql.utils.mail import MailSpec, Mailer
+from execsql.utils.sigterm import command
 
 
 def x_system_cmd(**kwargs: Any) -> None:
@@ -51,19 +52,25 @@ def x_system_cmd(**kwargs: Any) -> None:
     if cont is None:
         timeout = getattr(_state.conf, "system_cmd_timeout", 0.0)
         try:
-            if timeout and timeout > 0:
-                result = subprocess.run(cmdlist, timeout=timeout)
-            else:
-                result = subprocess.run(cmdlist)
+            # The command is killed if the block is left before it finishes,
+            # and by a SIGTERM at any point once it has started.
+            with command(cmdlist) as proc:
+                # communicate(), as subprocess.run() does: after Ctrl-C it
+                # gives the command a moment to handle its own SIGINT.
+                proc.communicate(timeout=timeout if timeout and timeout > 0 else None)
         except subprocess.TimeoutExpired as e:
             _state.subvars.add_substitution("$SYSTEM_CMD_EXIT_STATUS", "124")
+            msg = f"SYSTEM_CMD timed out after {timeout:g} seconds."
+            if proc.returncode is None:
+                # The OS refused to kill it: it runs as another user.
+                msg += f" The command could not be stopped and is still running (process {proc.pid})."
             raise ErrInfo(
                 type="cmd",
                 command_text=kwargs.get("metacommandline", "SYSTEM_CMD"),
-                other_msg=f"SYSTEM_CMD timed out after {timeout:g} seconds.",
+                other_msg=msg,
                 exception_msg=exception_desc(),
             ) from e
-        _state.subvars.add_substitution("$SYSTEM_CMD_EXIT_STATUS", str(result.returncode))
+        _state.subvars.add_substitution("$SYSTEM_CMD_EXIT_STATUS", str(proc.returncode))
     else:
         proc = subprocess.Popen(cmdlist)
         _state.subvars.add_substitution("$SYSTEM_CMD_PID", str(proc.pid))

execsql/script/ast.py

@@ -212,12 +212,15 @@ class ElseIfClause:
         condition_modifiers: ANDIF/ORIF modifiers that compound the ELSEIF
             condition, evaluated left-to-right at runtime.
         body: Nodes executed when this condition is true.
+        command: The metacommand as written, without ``-- !x!``, for error
+            reports.
     """
 
     condition: str
     span: SourceSpan
     condition_modifiers: list[ConditionModifier] = field(default_factory=list)
     body: list[Node] = field(default_factory=list)
+    command: str = ""
 
 
 @dataclass
@@ -232,6 +235,8 @@ class IfBlock(Node):
         elseif_clauses: Zero or more ELSEIF branches, evaluated in order.
         else_body: Nodes executed when the IF condition (and all ELSEIFs)
             are false.  Empty list means no ELSE branch.
+        command: The metacommand as written, without ``-- !x!``, for error
+            reports.
     """
 
     condition: str
@@ -240,6 +245,7 @@ class IfBlock(Node):
     elseif_clauses: list[ElseIfClause] = field(default_factory=list)
     else_body: list[Node] = field(default_factory=list)
     else_span: SourceSpan | None = None
+    command: str = ""
 
     def children(self) -> Iterator[Node]:
         yield from self.body
@@ -261,11 +267,14 @@ class LoopBlock(Node):
         loop_type: Either ``"WHILE"`` or ``"UNTIL"``.
         condition: The condition expression text.
         body: Nodes executed on each iteration.
+        command: The metacommand as written, without ``-- !x!``, for error
+            reports.
     """
 
     loop_type: str  # "WHILE" or "UNTIL"
     condition: str
     body: list[Node] = field(default_factory=list)
+    command: str = ""
 
     def children(self) -> Iterator[Node]:
         yield from self.body
@@ -283,9 +292,12 @@ class BatchBlock(Node):
 
     Attributes:
         body: Nodes within the batch.
+        command: The metacommand as written, without ``-- !x!``, for error
+            reports.
     """
 
     body: list[Node] = field(default_factory=list)
+    command: str = ""
 
     def children(self) -> Iterator[Node]:
         yield from self.body
@@ -325,12 +337,15 @@ class ScriptBlock(Node):
         doc: Optional docstring extracted from comments immediately following
             the BEGIN SCRIPT line.
         body: Nodes within the script block.
+        command: The metacommand as written, without ``-- !x!``, for error
+            reports.
     """
 
     name: str
     param_defs: list[ParamDef] | None = None
     doc: str | None = None
     body: list[Node] = field(default_factory=list)
+    command: str = ""
 
     @property
     def param_names(self) -> list[str] | None:
@@ -358,9 +373,12 @@ class SqlBlock(Node):
     Attributes:
         body: Nodes within the SQL block (typically a single
             :class:`SqlStatement`).
+        command: The metacommand as written, without ``-- !x!``, for error
+            reports.
     """
 
     body: list[Node] = field(default_factory=list)
+    command: str = ""
 
     def children(self) -> Iterator[Node]:
         yield from self.body
@@ -384,6 +402,8 @@ class IncludeDirective(Node):
         arguments: Optional argument expression for EXECUTE SCRIPT.
         loop_type: Optional ``"WHILE"`` or ``"UNTIL"`` for looped execution.
         loop_condition: The loop condition expression, if *loop_type* is set.
+        command: The metacommand as written, without ``-- !x!``, for error
+            reports.
     """
 
     target: str
@@ -392,6 +412,7 @@ class IncludeDirective(Node):
     arguments: str | None = None
     loop_type: str | None = None
     loop_condition: str | None = None
+    command: str = ""
 
     def __repr__(self) -> str:
         kind = "EXECUTE SCRIPT" if self.is_execute_script else "INCLUDE"

execsql/script/control.py

@@ -30,6 +30,8 @@ class BatchLevels:
     class Batch:
         def __init__(self) -> None:
             self.dbs_used: list[Any] = []
+            # Why this batch can no longer commit (an error inside it), or None.
+            self.failed: str | None = None
 
     def __init__(self) -> None:
         self.batchlevels: list[BatchLevels.Batch] = []
@@ -38,6 +40,25 @@ class BatchLevels:
         """Return True if execution is currently inside at least one BATCH block."""
         return len(self.batchlevels) > 0
 
+    def fail_enclosing(self, reason: str) -> None:
+        """Mark every open batch level as failed, so its END BATCH rolls back instead of committing."""
+        for b in self.batchlevels:
+            if b.failed is None:
+                b.failed = reason
+
+    def failure(self) -> str | None:
+        """Why the innermost batch can no longer commit, or None.
+
+        A batch inside a failed one cannot commit either: its commit would
+        commit the failed batch's later statements on a shared connection.
+        Nothing clears the mark, ROLLBACK BATCH included: once anything in a
+        batch has failed, the whole stack of batches rolls back.
+        """
+        for b in reversed(self.batchlevels):
+            if b.failed is not None:
+                return b.failed
+        return None
+
     def new_batch(self) -> None:
         """Push a new empty batch level onto the stack."""
         self.batchlevels.append(self.Batch())
@@ -61,7 +82,46 @@ class BatchLevels:
                 db.rollback()
 
     def end_batch(self) -> None:
-        """Commit all databases in the innermost batch level and pop the stack."""
+        """Commit all databases in the innermost batch level and pop the stack.
+
+        If a commit fails, :meth:`Database.commit` rolls that database back,
+        and the ones not yet committed are rolled back too (except one with
+        autocommit off, whose transaction is the script's) before the error
+        is raised: a commit that already succeeded
+        cannot be undone, but nothing else of the batch is left pending for
+        a later statement to commit.
+        """
+        b = self.batchlevels.pop()
+        for i, db in enumerate(b.dbs_used):
+            try:
+                db.commit()
+            except BaseException:
+                _roll_back(b.dbs_used[i + 1 :])
+                raise
+
+    def abandon_batch(self) -> None:
+        """Pop the innermost batch level without committing it.
+
+        Inside another batch, its databases join the enclosing level, which
+        commits or rolls them back.  Otherwise they are rolled back, except
+        one with autocommit off: :meth:`end_batch` would not have committed
+        it either, so its transaction stays the script's to end.
+        """
         b = self.batchlevels.pop()
-        for db in b.dbs_used:
-            db.commit()
+        if self.batchlevels:
+            for db in b.dbs_used:
+                self.using_db(db)
+            return
+        _roll_back(b.dbs_used)
+
+    def abandon_all(self) -> None:
+        """Abandon every open batch level, innermost first."""
+        while self.batchlevels:
+            self.abandon_batch()
+
+
+def _roll_back(dbs: list[Any]) -> None:
+    """Roll back each of *dbs* except one with autocommit off, whose transaction is the script's."""
+    for db in dbs:
+        if db.autocommit:
+            db.rollback()