execsql2 2.32.0__tar.gz → 2.33.0__tar.gz

{execsql2-2.32.0 → execsql2-2.33.0}/CHANGELOG.md

@@ -13,6 +13,20 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.33.0] - 2026-10-16
+
+### Added
+
+- **`$PG_UPSERT_STATUS`** says how a `PG_UPSERT` ended (`committed`, `dry_run`, `no_changes`, `qa_failed`, `cancelled`, `db_error`), and **`$PG_UPSERT_ERROR`** holds the database error message. A run with nothing to load and a cancelled run used to look the same in the other variables.
+
+### Fixed
+
+- **A failed metacommand sets `$LAST_ERROR` and `$ERROR_MESSAGE`** with `METACOMMAND_ERROR_HALT OFF`, so a script can tell what failed, not only that `METACOMMAND_ERROR()` is true; an `ON ERROR_HALT` handler (including `ON ERROR_HALT WRITE "…!{$LAST_ERROR}!"`) now gets `$LAST_ERROR` too. The error is also written to `execsql.log`.
+- **`execsql.run()` reports a metacommand that failed under `METACOMMAND_ERROR_HALT OFF`** in `result.errors`, with `success` False, as it already did for a SQL error under `ERROR_HALT OFF`.
+- **`PG_UPSERT` cancelled from a prompt** no longer leaves an earlier run's `$PG_UPSERT_*` values (such as `$PG_UPSERT_COMMITTED` `TRUE`) in place.
+
+______________________________________________________________________
+
 ## [2.32.0] - 2026-10-16
 
 ### Changed

{execsql2-2.32.0 → execsql2-2.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execsql2
-Version: 2.32.0
+Version: 2.33.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: Homepage, https://execsql2.readthedocs.io/en/stable/
 Project-URL: Repository, https://github.com/geocoug/execsql
@@ -441,7 +441,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.32.0
+    rev: v2.33.0
     hooks:
       - id: execsql-format
       - id: execsql-lint

{execsql2-2.32.0 → execsql2-2.33.0}/README.md

@@ -321,7 +321,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.32.0
+    rev: v2.33.0
     hooks:
       - id: execsql-format
       - id: execsql-lint

{execsql2-2.32.0 → execsql2-2.33.0}/docs/about/divergence.md

@@ -48,15 +48,15 @@ ______________________________________________________________________
 
 ### 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.                                                                                                                                                                                                                                                                                          |
-| `BREAKPOINT`            | Pause script execution and drop into an interactive debug REPL. See [Debugging](#debugging) below for full details.                                                                                                                                                                                                                                                                                                                                            |
-| `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.                                                                                                                                                                                                                                                                                                                                                                                          |
-| `PG_UPSERT`             | QA-checked, FK-dependency-ordered upserts from staging to base schema on PostgreSQL via the optional [pg-upsert](https://pg-upsert.readthedocs.io/) dependency. Modes: `PG_UPSERT` (full pipeline), `PG_UPSERT QA` (checks only), `PG_UPSERT CHECK` (schema only). QA checks only the rows the given `METHOD` would write. QA failure does not raise — the result is reported via `$PG_UPSERT_QA_PASSED` so the caller's `IF` / `ASSERT` decides control flow. |
-| `IMPORT … FROM JSON`    | Import a JSON file (array of objects or [JSON Lines](https://jsonlines.org/)) into a database table. Nested objects are flattened with dot-separated column names; arrays are stored as JSON strings.                                                                                                                                                                                                                                                          |
-| `SHOW SCRIPTS [<name>]` | Without a name, lists all registered SCRIPT definitions with parameter signatures and source locations. With a name, shows detail including parameters (with defaults), source file/line range, and docstring.                                                                                                                                                                                                                                                 |
+| 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. See [Debugging](#debugging) below for full details.                                                                                                                                                                                                                                                                                                                                                                                        |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `PG_UPSERT`             | QA-checked, FK-dependency-ordered upserts from staging to base schema on PostgreSQL via the optional [pg-upsert](https://pg-upsert.readthedocs.io/) dependency. Modes: `PG_UPSERT` (full pipeline), `PG_UPSERT QA` (checks only), `PG_UPSERT CHECK` (schema only). QA checks only the rows the given `METHOD` would write. QA failure does not raise — the result is reported via `$PG_UPSERT_QA_PASSED` so the caller's `IF` / `ASSERT` decides control flow; `$PG_UPSERT_STATUS` says how the run ended. |
+| `IMPORT … FROM JSON`    | Import a JSON file (array of objects or [JSON Lines](https://jsonlines.org/)) into a database table. Nested objects are flattened with dot-separated column names; arrays are stored as JSON strings.                                                                                                                                                                                                                                                                                                      |
+| `SHOW SCRIPTS [<name>]` | Without a name, lists all registered SCRIPT definitions with parameter signatures and source locations. With a name, shows detail including parameters (with defaults), source file/line range, and docstring.                                                                                                                                                                                                                                                                                             |
 
 ### SCRIPT Enhancements
 
@@ -349,7 +349,7 @@ These are behavioral changes driven by security or correctness issues in the ups
 | `WRITE` after `CD`                                                 | A relative `WRITE ... TO` path is resolved against the working directory at the time of the `WRITE`, so it follows an earlier `CD` the way `EXPORT` and `IMPORT` already did. Upstream wrote it relative to the directory execsql started in, because its writer subprocess never saw the `CD`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `$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. `$LAST_ERROR` also holds a failed metacommand, with `METACOMMAND_ERROR_HALT OFF` and in an `ON ERROR_HALT` handler, as the documentation describes; upstream set it only for SQL errors and unknown metacommands.                                                                                                                                                                                                                                                                                                                                                                                                              |
 | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `PROMPT COMPARE` diff comparison                                   | Diff engine uses native Python equality instead of string comparison — numeric types, Decimals, and booleans compare correctly. `None` is distinguished from empty string. Columns are matched by name (not position), key columns are excluded from comparison, and duplicate PKs keep the first row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

{execsql2-2.32.0 → execsql2-2.33.0}/docs/guides/formatter.md

@@ -272,7 +272,7 @@ select id,name,created_at from users where active = true order by name;
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.32.0
+    rev: v2.33.0
     hooks:
       - id: execsql-format
       - id: execsql-lint # optional: fail the commit on lint errors

{execsql2-2.32.0 → execsql2-2.33.0}/docs/reference/lint.md

@@ -158,7 +158,7 @@ The `execsql-lint` [pre-commit](https://pre-commit.com/) hook runs `execsql lint
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.32.0
+    rev: v2.33.0
     hooks:
       - id: execsql-lint
         args: [--ignore, V002] # optional: any execsql lint option

{execsql2-2.32.0 → execsql2-2.33.0}/docs/reference/metacommands.md

@@ -1766,7 +1766,7 @@ Evaluates whether or not the specified value is equal to zero. If the value is n
 METACOMMAND_ERROR()
 ```
 
-Evaluates whether the previous metacommand generated an error. This test for SQL errors will only be effective if the [METACOMMAND_ERROR_HALT OFF](#metacommanderrorhalt) metacommand has previously been issued. This conditional must be used in the first metacommand after any metacommand that might have encountered an error.
+Evaluates whether the previous metacommand generated an error. This test for SQL errors will only be effective if the [METACOMMAND_ERROR_HALT OFF](#metacommanderrorhalt) metacommand has previously been issued. This conditional must be used in the first metacommand after any metacommand that might have encountered an error: any metacommand that succeeds, even a WRITE, clears the flag. The error itself stays available until the next error: [$LAST_ERROR](substitution_vars.md#system_vars) holds the metacommand that failed and [$ERROR_MESSAGE](substitution_vars.md#system_vars) its message.
 
 
 ### *NEWER_DATE*
@@ -2109,7 +2109,7 @@ The [BREAK](#break) metacommand can be used to exit from a loop at any time.
 METACOMMAND_ERROR_HALT ON|OFF
 ```
 
-When METACOMMAND_ERROR_HALT is set to ON, which is the default, any errors that occur during execution of a metacommand will cause an error message to be displayed immediately, and *execsql* to halt. When METACOMMAND_ERROR_HALT is set to OFF, then metacommand errors will be ignored, but can be evaluated with the [IF METACOMMAND_ERROR](#metacommanderror) conditional.
+When METACOMMAND_ERROR_HALT is set to ON, which is the default, any errors that occur during execution of a metacommand will cause an error message to be displayed immediately, and *execsql* to halt. When METACOMMAND_ERROR_HALT is set to OFF, then metacommand errors will be ignored, but can be evaluated with the [IF METACOMMAND_ERROR](#metacommanderror) conditional; `$LAST_ERROR` and `$ERROR_MESSAGE` hold the failed metacommand and its message.
 
 The METACOMMAND_ERROR_HALT metacommand does not itself set or reset the internal flag that indicates whether a metacommand has encountered an error. This is so that a "METACOMMAND_ERROR_HALT Off" command can be used immediately after a potentially-failing metacommand and not alter the error flag that is set by the previous command. Specifically, constructions like this:
 
@@ -2356,6 +2356,8 @@ Set after every `PG_UPSERT` execution:
 | `$PG_UPSERT_ROWS_UPDATED` | integer | Total rows updated across all tables |
 | `$PG_UPSERT_ROWS_INSERTED` | integer | Total rows inserted across all tables |
 | `$PG_UPSERT_COMMITTED` | TRUE/FALSE | Were changes committed? |
+| `$PG_UPSERT_STATUS` | string | How the run ended: `committed`, `dry_run` (changes made, then rolled back because `COMMIT` was not given), `no_changes` (QA passed, nothing to insert or update), `qa_failed`, `cancelled` or `db_error`. Empty after `PG_UPSERT QA` and `PG_UPSERT CHECK`, which do not upsert. |
+| `$PG_UPSERT_ERROR` | string | The database error message when `$PG_UPSERT_STATUS` is `db_error`; otherwise empty |
 | `$PG_UPSERT_STAGING_SCHEMA` | string | Staging schema name used |
 | `$PG_UPSERT_BASE_SCHEMA` | string | Base schema name used |
 | `$PG_UPSERT_TABLES` | string | Comma-separated list of table names processed |
@@ -2380,7 +2382,7 @@ Set after every `PG_UPSERT` execution:
 
 ### QA failure behavior
 
-`PG_UPSERT`, `PG_UPSERT QA`, and `PG_UPSERT CHECK` do **not** raise an error when QA checks fail. The outcome is reported via `$PG_UPSERT_QA_PASSED` (and the per-table `$PG_UPSERT_TABLE_QA_PASSED`), so the script controls flow with `IF` or with execsql's standard error-halt configuration. When QA fails, the metacommand still runs `EXPORT_FAILURES`, populates all `$PG_UPSERT_*` substitution variables, and skips the upsert (no commit). Pair with `ASSERT` to halt explicitly:
+`PG_UPSERT`, `PG_UPSERT QA`, and `PG_UPSERT CHECK` do **not** raise an error when QA checks fail. The outcome is reported via `$PG_UPSERT_QA_PASSED` (and the per-table `$PG_UPSERT_TABLE_QA_PASSED`), so the script controls flow with `IF` or with execsql's standard error-halt configuration. When QA fails, the metacommand still runs `EXPORT_FAILURES`, populates all `$PG_UPSERT_*` substitution variables, and skips the upsert (no commit). To tell the ways a run can end apart, branch on `$PG_UPSERT_STATUS` rather than combining `$PG_UPSERT_QA_PASSED` with `$PG_UPSERT_COMMITTED`: a run with nothing to load (`no_changes`) and one the user cancelled (`cancelled`) both leave QA passed and nothing committed. Pair with `ASSERT` to halt explicitly:
 
 ```sql
 -- Soft failure: branch on the result, keep running.
@@ -2398,7 +2400,7 @@ Set after every `PG_UPSERT` execution:
 
 ### Database errors
 
-A database error during the run (a deadlock, a lock timeout, a constraint or trigger error the QA checks did not catch) is different from a QA failure. pg-upsert rolls the run back, and `PG_UPSERT` fails like any other metacommand: the driver's message is in `$ERROR_MESSAGE`, and the script halts unless `METACOMMAND_ERROR_HALT` is off. The `$PG_UPSERT_*` variables describe the failed run (`$PG_UPSERT_COMMITTED` is `FALSE` and the row counts are `0`), not an earlier `PG_UPSERT`.
+A database error during the run (a deadlock, a lock timeout, a constraint or trigger error the QA checks did not catch) is different from a QA failure. pg-upsert rolls the run back, and `PG_UPSERT` fails like any other metacommand: the driver's message is in `$ERROR_MESSAGE`, and the script halts unless `METACOMMAND_ERROR_HALT` is off. The `$PG_UPSERT_*` variables describe the failed run (`$PG_UPSERT_STATUS` is `db_error`, `$PG_UPSERT_ERROR` holds the message, `$PG_UPSERT_COMMITTED` is `FALSE` and the row counts are `0`), not an earlier `PG_UPSERT`. Cancelling at one of pg-upsert's own prompts is not an error: `PG_UPSERT` returns, with `$PG_UPSERT_STATUS` `cancelled`.
 
 The rollback ends the connection's transaction, so under `AUTOCOMMIT OFF` or inside `BEGIN BATCH`, statements run earlier on the same connection are rolled back with it.
 

{execsql2-2.32.0 → execsql2-2.33.0}/extras/vscode-execsql/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "execsql-syntax",
-  "version": "2.32.0",
+  "version": "2.33.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "execsql-syntax",
-      "version": "2.32.0",
+      "version": "2.33.0",
       "license": "GPL-3.0-or-later",
       "dependencies": {
         "vscode-languageclient": "10.1.2"

{execsql2-2.32.0 → execsql2-2.33.0}/extras/vscode-execsql/package.json

@@ -2,7 +2,7 @@
   "name": "execsql-syntax",
   "displayName": "execsql",
   "description": "Syntax highlighting, lint findings, completion, hover, navigation, quick fixes and formatting for execsql scripts.",
-  "version": "2.32.0",
+  "version": "2.33.0",
   "publisher": "geocoug",
   "license": "GPL-3.0-or-later",
   "icon": "icon.png",

{execsql2-2.32.0 → execsql2-2.33.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.32.0"
+version = "2.33.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" }
@@ -188,7 +188,7 @@ line-ending = "auto"
 exclude = ["*.md"]
 
 [tool.bumpversion]
-current_version = "2.32.0"
+current_version = "2.33.0"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{execsql2-2.32.0 → execsql2-2.33.0}/src/execsql/metacommands/reference.py

@@ -1364,6 +1364,16 @@ _SYSTEM_VARIABLES: tuple[SystemVariable, ...] = (
         "TRUE or FALSE: whether the changes were committed.",
         "metacommands.md#pg_upsert",
     ),
+    SystemVariable(
+        "$PG_UPSERT_STATUS",
+        "How the run ended: committed, dry_run, no_changes, qa_failed, cancelled or db_error.",
+        "metacommands.md#pg_upsert",
+    ),
+    SystemVariable(
+        "$PG_UPSERT_ERROR",
+        "The database error message when $PG_UPSERT_STATUS is db_error; otherwise empty.",
+        "metacommands.md#pg_upsert",
+    ),
     SystemVariable("$PG_UPSERT_STAGING_SCHEMA", "Staging schema name used.", "metacommands.md#pg_upsert"),
     SystemVariable("$PG_UPSERT_BASE_SCHEMA", "Base schema name used.", "metacommands.md#pg_upsert"),
     SystemVariable("$PG_UPSERT_TABLES", "Comma-separated list of table names processed.", "metacommands.md#pg_upsert"),

{execsql2-2.32.0 → execsql2-2.33.0}/src/execsql/metacommands/upsert.py

@@ -185,6 +185,11 @@ def _set_subvars(result: Any) -> None:
     sv("$PG_UPSERT_ROWS_UPDATED", str(result.total_updated))
     sv("$PG_UPSERT_ROWS_INSERTED", str(result.total_inserted))
     sv("$PG_UPSERT_COMMITTED", str(result.committed).upper())
+    # How the run ended: committed, dry_run, no_changes, qa_failed, cancelled
+    # or db_error.  Empty for QA and CHECK, which do not run an upsert.
+    status = getattr(result, "status", None)
+    sv("$PG_UPSERT_STATUS", status.value if status is not None else "")
+    sv("$PG_UPSERT_ERROR", getattr(result, "error", None) or "")
     sv("$PG_UPSERT_STAGING_SCHEMA", result.staging_schema)
     sv("$PG_UPSERT_BASE_SCHEMA", result.base_schema)
     sv("$PG_UPSERT_TABLES", ", ".join(t.table_name for t in result.tables))
@@ -426,6 +431,14 @@ def _handle_pg_upsert_errors(fn: Any, metacommandline: str | None) -> Any:
     try:
         return fn()
     except UserCancelledError as exc:
+        # No result describes a run cancelled outside pg-upsert's own run();
+        # say what is known rather than leave an earlier run's values.
+        sv = _state.subvars.add_substitution
+        sv("$PG_UPSERT_STATUS", "cancelled")
+        sv("$PG_UPSERT_ERROR", "")
+        sv("$PG_UPSERT_COMMITTED", "FALSE")
+        sv("$PG_UPSERT_ROWS_UPDATED", "0")
+        sv("$PG_UPSERT_ROWS_INSERTED", "0")
         raise ErrInfo(
             "cmd",
             command_text=metacommandline,

{execsql2-2.32.0 → execsql2-2.33.0}/src/execsql/script/engine.py

@@ -108,6 +108,7 @@ class MetaCommand:
         """Match *cmd_str* against this entry's regex and, if it matches, invoke the handler.
 
         Returns ``(True, return_value)`` on a match, ``(False, None)`` otherwise.
+        Raises :class:`ErrInfo` when the handler fails.
         """
         # Runs the metacommand if the command string matches the regex.
         m = self.rx.match(cmd_str.strip())
@@ -125,13 +126,10 @@ class MetaCommand:
                 er = ErrInfo("cmd", command_text=cmd_str, exception_msg=exception_desc())
                 er.__cause__ = exc
             if er:
-                if _state.status.halt_on_metacommand_err:
-                    from execsql.utils.errors import exit_now
-
-                    exit_now(1, er)
-                if self.set_error_flag:
-                    _state.status.metacommand_error = True
-                    return True, None
+                # The caller records the error ($LAST_ERROR, $ERROR_MESSAGE,
+                # the log, the error history) and halts or carries on.
+                if self.set_error_flag or _state.status.halt_on_metacommand_err:
+                    raise er
             else:
                 if self.set_error_flag:
                     _state.status.metacommand_error = False

{execsql2-2.32.0 → execsql2-2.33.0}/src/execsql/script/executor.py

@@ -350,7 +350,9 @@ def _exec_metacommand(
         if ctx.exec_log is not None:
             ctx.exec_log.log_status_info(f"Metacommand error: {logged_error(e)}")
         if status.halt_on_metacommand_err:
-            raise e
+            exit_now(1, e)
+        if (manifest := _manifest.current()) is not None:
+            manifest.record_metacommand(cmd, source, line_no, metacommandlist)
         status.error_history.append((source, line_no, cmd, e.errmsg()))
         return None
     # No handler matched — truly unknown metacommand

{execsql2-2.32.0 → execsql2-2.33.0}/tests/integration/test_postgres.py

@@ -567,6 +567,55 @@ def _upsert_outcomes(tmp_path, metacommands: str) -> dict[str, str]:
 
 
 class TestPgUpsert:
+    @pytest.mark.parametrize(
+        ("staging_rows", "commit", "expected"),
+        [
+            ("(1, 'new'), (2, 'two')", "COMMIT", "committed"),
+            ("(1, 'new'), (2, 'two')", "", "dry_run"),
+            ("", "COMMIT", "no_changes"),
+            ("(2, NULL)", "COMMIT", "qa_failed"),
+        ],
+        ids=["committed", "dry_run", "no_changes", "qa_failed"],
+    )
+    def test_status_says_how_the_run_ended(self, tmp_path, upsert_schemas, staging_rows, commit, expected):
+        if staging_rows:
+            _exec_pg(f"INSERT INTO ups_stg.books VALUES {staging_rows}")
+        outcomes = _upsert_outcomes(
+            tmp_path,
+            f"""\
+            -- !x! PG_UPSERT FROM ups_stg TO ups_base TABLES books {commit}
+            -- !x! WRITE "status=!!$PG_UPSERT_STATUS!!" TO OUT
+            -- !x! WRITE "error=!!$PG_UPSERT_ERROR!!" TO OUT
+            """,
+        )
+        assert outcomes == {"status": expected, "error": ""}
+
+    def test_a_database_error_is_status_db_error_with_its_message(self, tmp_path, upsert_schemas):
+        _exec_pg("INSERT INTO ups_stg.books VALUES (2, 'two')")
+        _exec_pg(
+            "CREATE FUNCTION ups_base.refuse() RETURNS trigger LANGUAGE plpgsql AS "
+            "$$ BEGIN RAISE EXCEPTION 'books are read-only'; END $$",
+        )
+        _exec_pg(
+            "CREATE TRIGGER refuse BEFORE INSERT ON ups_base.books FOR EACH ROW EXECUTE FUNCTION ups_base.refuse()",
+        )
+        _write_conf(tmp_path)
+        out, err = tmp_path / "out.txt", tmp_path / "error.txt"
+        script = write_script(
+            tmp_path,
+            f"""\
+            -- !x! METACOMMAND_ERROR_HALT OFF
+            -- !x! PG_UPSERT FROM ups_stg TO ups_base TABLES books COMMIT
+            -- !x! WRITE "status=!!$PG_UPSERT_STATUS!! committed=!!$PG_UPSERT_COMMITTED!!" TO {out}
+            -- !x! WRITE `!!$PG_UPSERT_ERROR!!` TO {err}
+            """,
+        )
+        result = _run_execsql_pg(tmp_path, script, timeout=60)
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        assert out.read_text().strip() == "status=db_error committed=FALSE"
+        assert "books are read-only" in err.read_text()
+        assert _query_pg("SELECT id FROM ups_base.books ORDER BY id") == [(1,)]
+
     def test_qa_follows_method(self, tmp_path, upsert_schemas):
         """A NULL title on a new row fails QA for upsert, but update never writes that row."""
         _exec_pg("INSERT INTO ups_stg.books VALUES (1, 'new'), (2, NULL)")

{execsql2-2.32.0 → execsql2-2.33.0}/tests/metacommands/test_pg_upsert.py

@@ -893,6 +893,40 @@ class TestUserCancelled:
                     metacommandline="PG_UPSERT FROM staging TO public TABLES books INTERACTIVE",
                 )
             assert "cancelled" in str(exc_info.value)
+        # No earlier run's values are left behind: nothing was committed.
+        calls = {c[0][0]: c[0][1] for c in state.subvars.add_substitution.call_args_list}
+        assert calls["$PG_UPSERT_STATUS"] == "cancelled"
+        assert calls["$PG_UPSERT_ERROR"] == ""
+        assert calls["$PG_UPSERT_COMMITTED"] == "FALSE"
+        assert (calls["$PG_UPSERT_ROWS_UPDATED"], calls["$PG_UPSERT_ROWS_INSERTED"]) == ("0", "0")
+
+
+class TestRunStatus:
+    """$PG_UPSERT_STATUS and $PG_UPSERT_ERROR come from the result's status and error."""
+
+    def test_status_and_error_from_the_result(self, mock_state):
+        import enum
+
+        from execsql.metacommands.upsert import _set_subvars
+
+        class RunStatus(enum.Enum):
+            DB_ERROR = "db_error"
+
+        state, _ = mock_state
+        result = FakeUpsertResult()
+        result.status = RunStatus.DB_ERROR
+        result.error = "trigger said no"
+        _set_subvars(result)
+        calls = {c[0][0]: c[0][1] for c in state.subvars.add_substitution.call_args_list}
+        assert (calls["$PG_UPSERT_STATUS"], calls["$PG_UPSERT_ERROR"]) == ("db_error", "trigger said no")
+
+    def test_no_status_is_empty(self, mock_state):
+        from execsql.metacommands.upsert import _set_subvars
+
+        state, _ = mock_state
+        _set_subvars(FakeUpsertResult())  # QA and CHECK build a result without one
+        calls = {c[0][0]: c[0][1] for c in state.subvars.add_substitution.call_args_list}
+        assert (calls["$PG_UPSERT_STATUS"], calls["$PG_UPSERT_ERROR"]) == ("", "")
 
 
 # ---------------------------------------------------------------------------

{execsql2-2.32.0 → execsql2-2.33.0}/tests/test_engine.py

@@ -100,17 +100,16 @@ class TestMetaCommandRun:
         assert mc.hitcount == 0
 
     def test_handler_raises_errinf_no_halt(self, engine_state):
-        """ErrInfo from handler: sets metacommand_error, returns (True, None)."""
+        """ErrInfo from the handler goes to the caller, which records it ($LAST_ERROR, history)."""
         _state.status.halt_on_metacommand_err = False
 
         def bad_handler(**kw):
             raise ErrInfo("error", other_msg="oops")
 
         mc = MetaCommand(re.compile(r"^\s*FAIL\s*$", re.I), bad_handler, set_error_flag=True)
-        matched, rv = mc.run("FAIL")
-        assert matched is True
-        assert rv is None
-        assert _state.status.metacommand_error is True
+        with pytest.raises(ErrInfo, match="oops"):
+            mc.run("FAIL")
+        assert mc.hitcount == 0
 
     def test_handler_raises_general_exception_no_halt(self, engine_state):
         """Generic exception from handler is converted to ErrInfo."""
@@ -120,10 +119,19 @@ class TestMetaCommandRun:
             raise ValueError("boom")
 
         mc = MetaCommand(re.compile(r"^\s*BOOM\s*$", re.I), bad_handler, set_error_flag=True)
-        matched, rv = mc.run("BOOM")
-        assert matched is True
-        assert rv is None
-        assert _state.status.metacommand_error is True
+        with pytest.raises(ErrInfo) as excinfo:
+            mc.run("BOOM")
+        assert isinstance(excinfo.value.__cause__, ValueError)
+
+    def test_set_error_flag_false_error_without_halt_is_no_match(self, engine_state):
+        """As upstream: a failing METACOMMAND_ERROR_HALT-style command reports no match."""
+        _state.status.halt_on_metacommand_err = False
+
+        def bad_handler(**kw):
+            raise ErrInfo("error", other_msg="nope")
+
+        mc = MetaCommand(re.compile(r"^\s*NOFLAG\s*$", re.I), bad_handler, set_error_flag=False)
+        assert mc.run("NOFLAG") == (False, None)
 
     def test_successful_run_clears_metacommand_error(self, engine_state):
         _state.status.metacommand_error = True
@@ -154,20 +162,17 @@ class TestMetaCommandRun:
         with pytest.raises(SystemExit):
             mc.run("EXIT")
 
-    def test_halt_on_metacommand_err_calls_exit_now(self, engine_state):
-        """When halt_on_metacommand_err is True and handler raises, exit_now is called."""
+    def test_halting_is_left_to_the_caller(self, engine_state):
+        """With halt_on_metacommand_err, the error is raised; the executor records it and halts."""
         _state.status.halt_on_metacommand_err = True
 
         def bad_handler(**kw):
             raise ErrInfo("error", other_msg="halt me")
 
         mc = MetaCommand(re.compile(r"^\s*HALTNOW\s*$", re.I), bad_handler)
-        # exit_now is imported lazily inside MetaCommand.run(), so patch at its source module
-        with patch("execsql.utils.errors.exit_now") as mock_exit:
-            mock_exit.side_effect = SystemExit(1)
-            with pytest.raises(SystemExit):
-                mc.run("HALTNOW")
-        mock_exit.assert_called_once()
+        with patch("execsql.utils.errors.exit_now") as mock_exit, pytest.raises(ErrInfo, match="halt me"):
+            mc.run("HALTNOW")
+        mock_exit.assert_not_called()
 
     def test_repr_contains_pattern(self):
         mc = MetaCommand(re.compile(r"^\s*ABC\s*$", re.I), lambda **kw: None, "test cmd")

execsql2-2.33.0/tests/test_metacommand_errors.py

@@ -0,0 +1,98 @@
+"""What a failed metacommand leaves for the script: $LAST_ERROR, $ERROR_MESSAGE, METACOMMAND_ERROR().
+
+With METACOMMAND_ERROR_HALT OFF the script carries on and can read both
+variables; with it ON, an ON ERROR_HALT handler can.  The flag clears on the
+next metacommand that succeeds; the variables keep their values until the next
+error.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from execsql import run
+
+_FAILING = '-- !x! IMPORT TO NEW nofile FROM "does_not_exist.csv"\n'
+_FAILED_COMMAND = 'IMPORT TO NEW nofile FROM "does_not_exist.csv"'
+
+
+def _run(tmp_path, monkeypatch, sql: str):
+    monkeypatch.chdir(tmp_path)
+    result = run(sql=sql, dsn=f"sqlite:///{tmp_path / 't.db'}", new_db=True)
+    out = tmp_path / "out.txt"
+    return result, out.read_text().splitlines() if out.exists() else []
+
+
+def test_without_halting_the_script_can_read_the_error(tmp_path, monkeypatch):
+    result, lines = _run(
+        tmp_path,
+        monkeypatch,
+        "-- !x! METACOMMAND_ERROR_HALT OFF\n" + _FAILING + "-- !x! IF (METACOMMAND_ERROR())\n"
+        "-- !x!   WRITE `last=[!!$LAST_ERROR!!]` TO out.txt\n"
+        "-- !x!   WRITE `message=[!!$ERROR_MESSAGE!!]` TO out.txt\n"
+        "-- !x! ENDIF\n",
+    )
+    assert lines[0] == f"last=[{_FAILED_COMMAND}]"
+    assert "does_not_exist.csv does not exist" in "\n".join(lines[1:])
+    # The failure is one of the run's errors, as a non-halting SQL error is.
+    assert not result.success
+    assert [e.sql for e in result.errors] == [_FAILED_COMMAND]
+
+
+def test_the_flag_clears_on_success_and_the_variables_keep_their_values(tmp_path, monkeypatch):
+    _, lines = _run(
+        tmp_path,
+        monkeypatch,
+        "-- !x! METACOMMAND_ERROR_HALT OFF\n" + _FAILING + "-- !x! WRITE `next` TO out.txt\n"
+        "-- !x! IF (NOT METACOMMAND_ERROR())\n"
+        "-- !x!   WRITE `cleared; last=[!!$LAST_ERROR!!]` TO out.txt\n"
+        "-- !x! ENDIF\n",
+    )
+    assert lines == ["next", f"cleared; last=[{_FAILED_COMMAND}]"]
+
+
+def test_an_on_error_halt_handler_can_read_the_error(tmp_path, monkeypatch):
+    result, lines = _run(
+        tmp_path,
+        monkeypatch,
+        "-- !x! BEGIN SCRIPT on_err\n"
+        "-- !x! WRITE `handler last=[!!$LAST_ERROR!!]` TO out.txt\n"
+        "-- !x! END SCRIPT\n"
+        "-- !x! ON ERROR_HALT EXECUTE SCRIPT on_err\n" + _FAILING + "-- !x! WRITE `not reached` TO out.txt\n",
+    )
+    assert lines == [f"handler last=[{_FAILED_COMMAND}]"]
+    assert not result.success
+
+
+def test_the_documented_on_error_halt_write_example(tmp_path, monkeypatch):
+    _, lines = _run(
+        tmp_path,
+        monkeypatch,
+        '-- !x! ON ERROR_HALT WRITE "Error in line: !{$LAST_ERROR}!" TO out.txt\n' + _FAILING,
+    )
+    assert lines == [f"Error in line: {_FAILED_COMMAND}"]
+
+
+def _cli(tmp_path, script: str) -> subprocess.CompletedProcess:
+    (tmp_path / "s.sql").write_text(script)
+    return subprocess.run(
+        [sys.executable, "-m", "execsql", "run", "-tl", "-n", "s.sql", "t.db"],
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        timeout=120,
+        check=False,
+    )
+
+
+def test_the_cli_logs_a_non_halting_error_and_exits_zero(tmp_path):
+    proc = _cli(tmp_path, "-- !x! METACOMMAND_ERROR_HALT OFF\n" + _FAILING)
+    assert proc.returncode == 0, proc.stderr
+    assert "Metacommand error:" in (tmp_path / "execsql.log").read_text()
+
+
+def test_the_cli_still_halts_with_status_1(tmp_path):
+    proc = _cli(tmp_path, _FAILING + "-- !x! WRITE `not reached`\n")
+    assert proc.returncode == 1
+    assert "not reached" not in proc.stdout

{execsql2-2.32.0 → execsql2-2.33.0}/tests/test_script.py

@@ -807,15 +807,15 @@ class TestMetaCommand:
         assert captured["varname"] == "myvar"
         assert captured["value"] == "hello"
 
-    def test_run_sets_error_flag_on_exception(self):
+    def test_run_raises_the_handler_error(self):
         rx = re.compile(r".*", re.I)
 
         def bad_handler(**kw):
             raise ValueError("oops")
 
         mc = MetaCommand(rx, bad_handler, set_error_flag=True)
-        mc.run("anything")
-        assert _state.status.metacommand_error is True
+        with pytest.raises(ErrInfo):
+            mc.run("anything")
 
     def test_run_clears_error_flag_on_success(self):
         _state.status.metacommand_error = True

{execsql2-2.32.0 → execsql2-2.33.0}/uv.lock

@@ -912,7 +912,7 @@ wheels = [
 
 [[package]]
 name = "execsql2"
-version = "2.32.0"
+version = "2.33.0"
 source = { editable = "." }
 dependencies = [
     { name = "python-dateutil" },