execsql2 2.14.1__tar.gz → 2.15.1__tar.gz

{execsql2-2.14.1 → execsql2-2.15.1}/.gitignore

@@ -33,12 +33,8 @@ coverage.xml
 .tox/
 htmlcov/
 execsql.log
-scripts/execsql.conf
-scripts/*.csv
-scripts/test_import_sqlite.sql
-scripts/test_script.sql
-scripts/test.db
-scripts/*.log
+!scripts/generate_vscode_grammar.py
+scripts/
 
 # Distribution
 *.whl
@@ -48,5 +44,6 @@ scripts/*.log
 _execsql/
 
 # Claude
-.claude/settings.local.json
+.claude/
 ANALYSIS.md
+FINDINGS.md

{execsql2-2.14.1 → execsql2-2.15.1}/CHANGELOG.md

@@ -13,8 +13,67 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.15.1] - 2026-04-14
+
+### Added
+
+- Cell-level diff marking in `PROMPT COMPARE` dialog — when "Highlight Diffs" is toggled, differing cells within changed rows are prefixed with a bullet marker so users can see exactly which columns differ. Works across all three backends (Tkinter, Textual, and console).
+- `macos_config_file` option in `execsql.conf` `[config]` section — specifies an additional configuration file to read on macOS (`sys.platform == "darwin"`). Behaves identically to `linux_config_file` with tilde expansion support.
+- EXPORT operations now log structured `action` records to `execsql.log` with the query name, output file, and source line number.
+
+### Removed
+
+- `Logger.log_action_prompt_quit()` — dead code inherited from upstream, never called. Prompt halt events are already captured by `log_exit_halt()`.
+- `constants.py` — 370 lines of map tile servers, XBM bitmaps, and X11 color names never imported by any module. Vestigial from the upstream monolith.
+- `Tz` class in `types.py` — custom `tzinfo` subclass orphaned by the `python-dateutil` migration.
+- Duplicate `file_size_date()`, `chainfuncs()`, and `as_none()` definitions in `conditions.py` — canonical versions in `utils/errors.py`. `chainfuncs()` and `as_none()` were also removed from `utils/errors.py` as they had zero callers.
+
+### Changed
+
+- `linux_config_file` config option now only applies on Linux (`sys.platform == "linux"`), not all POSIX systems. macOS users should use the new `macos_config_file` option instead.
+- Date/time parsing now uses `python-dateutil` instead of 231 hardcoded `strptime` format strings. Handles ISO 8601 with `T` separator, microseconds, `Z` suffix, and named timezones that the old format list could not parse.
+- Refactored `ConfigData` to use private helper methods (`_get_str`, `_get_enum`, `_get_bool`, `_get_int`, `_get_float`) — reduces ~370 lines of repetitive option parsing to ~80 lines with identical behavior.
+
+### Fixed
+
+- `NumericParser` now uses left-associative parsing for arithmetic operators. Previously, right-recursive descent caused `10 - 3 - 2` to evaluate as `10 - (3 - 2) = 9` instead of the correct `(10 - 3) - 2 = 5`. Same fix for division.
+- Operator precedence bug in `DataTable` and `Database.populate_table()` empty-column check — a redundant `and conf.del_empty_cols` inside an already-guarded block caused incorrect short-circuit evaluation due to Python operator precedence.
+- SQLite `populate_table()` now applies `trim_strings`, `replace_newlines`, and `empty_strings` processing before extracting column data. Previously, processing was applied after the insert data was copied, so trimming and null-conversion never took effect.
+- `$CURRENT_DATABASE` and `$CURRENT_DBMS` system variables now refresh on `USE` metacommand. Previously they were only set at startup and on `CONNECT`, becoming stale after switching the active database with `USE`.
+- Documentation: `$CONSOLE_WAIT_WHEN_ERROR_HALT_STATE` variable name corrected in substitution variables reference (was incorrectly documented as `$CONSOLE_WAIT_WHEN_ERROR_STATE`).
+- `PROMPT COMPARE` diff logic now uses native Python equality instead of string comparison — `int(1)` vs `float(1.0)`, `Decimal("10.00")` vs `Decimal("10.0")`, and `True` vs `1` are correctly treated as equal instead of producing false diffs.
+- `PROMPT COMPARE` diff logic now treats `None` (SQL NULL) as distinct from empty string `""`. Previously both were normalized to `""` and compared as equal.
+- `PROMPT COMPARE` summary stats now match by column name instead of position — tables with the same columns in different order no longer produce false diffs.
+- `PROMPT COMPARE` summary stats no longer include key columns in the diff comparison — only non-key shared columns are compared, consistent with the cell-level diff engine.
+- `PROMPT COMPARE` diff engine now keeps the first row when duplicate PK values exist, instead of silently using the last.
+- `compare_stats()` now delegates to `compute_row_diffs()` so the summary line and cell-level highlighting always agree.
+- `PG_UPSERT` metacommand no longer writes pg-upsert output to `execsql.log`. Logging now only goes to the file specified by the `LOGFILE` keyword.
+- `win_config_file` config option now works on Windows. Previously checked `os.name == "windows"` which is never true (Python returns `"nt"`). Inherited from upstream.
+
+______________________________________________________________________
+
+## [2.15.0] - 2026-04-09
+
+### Added
+
+- `PG_UPSERT` metacommand: new `EXPORT_FAILURES <dir>`, `EXPORT_FORMAT csv|json|xlsx`, and `EXPORT_MAX_ROWS <n>` keywords that write a "fix sheet" of failing QA rows — one row per unique violating staging row with a consolidated `_issues` column — to CSV, JSON, or XLSX. Works in all three modes (full pipeline, QA-only, schema check) and runs even when QA fails. New `$PG_UPSERT_EXPORT_PATH` substitution variable holds the directory written. A user-visible message reporting the export directory and format is emitted to both the console and the execsql log after every export.
+
+### Changed
+
+- `[upsert]` extra now requires `pg-upsert>=1.21.0` (up from `>=1.20.0`) for the fix-sheet export feature.
+
+### Fixed
+
+- `PROMPT MESSAGE ... CREDENTIALS <user_var> <pw_var>` no longer crashes in console-fallback mode with `TypeError: get_password() missing 2 required positional arguments: 'database_name' and 'user_name'`. The fallback now uses `getpass.getpass()` to read the password, matching the intent (keyring-aware `auth.get_password()` is for CONNECT, not for bare credential prompts).
+
+______________________________________________________________________
+
 ## [2.14.1] - 2026-04-07
 
+### Fixed
+
+- Fix Windows CI: use `zf.namelist()[0]` instead of path for zip entry lookup.
+
 ______________________________________________________________________
 
 ## [2.14.0] - 2026-04-07

{execsql2-2.14.1 → execsql2-2.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.14.1
+Version: 2.15.1
 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
 Project-URL: Repository, https://github.com/geocoug/execsql
@@ -39,6 +39,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Database
 Classifier: Topic :: Database :: Front-Ends
 Requires-Python: >=3.10
+Requires-Dist: python-dateutil>=2.8
 Requires-Dist: rich>=13.0
 Requires-Dist: sqlglot>=25.0
 Requires-Dist: textual>=0.47.0
@@ -51,7 +52,7 @@ Requires-Dist: keyring; extra == 'all'
 Requires-Dist: odfpy; extra == 'all'
 Requires-Dist: openpyxl; extra == 'all'
 Requires-Dist: oracledb; extra == 'all'
-Requires-Dist: pg-upsert>=1.20.0; extra == 'all'
+Requires-Dist: pg-upsert>=1.21.0; extra == 'all'
 Requires-Dist: polars; extra == 'all'
 Requires-Dist: psycopg2-binary; extra == 'all'
 Requires-Dist: pymysql; extra == 'all'
@@ -109,7 +110,7 @@ Requires-Dist: oracledb; extra == 'oracle'
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary; extra == 'postgres'
 Provides-Extra: upsert
-Requires-Dist: pg-upsert>=1.20.0; extra == 'upsert'
+Requires-Dist: pg-upsert>=1.21.0; extra == 'upsert'
 Description-Content-Type: text/markdown
 
 > [!NOTE]

{execsql2-2.14.1 → execsql2-2.15.1}/docs/about/divergence.md

@@ -41,14 +41,14 @@ ______________________________________________________________________
 
 ### 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. Integrates [pg-upsert](https://pg-upsert.readthedocs.io/) as an optional dependency. Three modes: full pipeline, QA-only, and schema check. |
-| `IMPORT … FROM JSON`   | Import a JSON file (array of objects or NDJSON) into a database table. Nested objects are flattened with dot-separated column names; arrays are stored as JSON strings.                                                          |
+| 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. Integrates [pg-upsert](https://pg-upsert.readthedocs.io/) as an optional dependency. Three modes: full pipeline, QA-only, and schema check. Supports `EXPORT_FAILURES`, `EXPORT_FORMAT`, and `EXPORT_MAX_ROWS` keywords to write a "fix sheet" of failing QA rows to CSV/JSON/XLSX (requires `pg-upsert>=1.21.0`). |
+| `IMPORT … FROM JSON`   | Import a JSON file (array of objects or NDJSON) into a database table. Nested objects are flattened with dot-separated column names; arrays are stored as JSON strings.                                                                                                                                                                                                                                 |
 
 ### Conditional Tests
 
@@ -63,13 +63,15 @@ ______________________________________________________________________
 
 New options in `execsql.conf`:
 
-| Option                     | Section     | Description                                                       |
-| -------------------------- | ----------- | ----------------------------------------------------------------- |
-| `use_keyring`              | `[connect]` | Use the OS keyring for credential storage (default: `yes`).       |
-| `show_progress`            | `[input]`   | Enable Rich progress bar for IMPORT (default: `no`).              |
-| `import_progress_interval` | `[input]`   | Log a status line every N rows during IMPORT (default: `0`).      |
-| `log_sql`                  | `[config]`  | Enable SQL audit logging (default: `no`).                         |
-| `max_log_size_mb`          | `[config]`  | Rotate the log file at this size in MB (default: `0` = disabled). |
+| Option                     | Section       | Description                                                       |
+| -------------------------- | ------------- | ----------------------------------------------------------------- |
+| `use_keyring`              | `[connect]`   | Use the OS keyring for credential storage (default: `yes`).       |
+| `show_progress`            | `[input]`     | Enable Rich progress bar for IMPORT (default: `no`).              |
+| `import_progress_interval` | `[input]`     | Log a status line every N rows during IMPORT (default: `0`).      |
+| `gui_framework`            | `[interface]` | GUI backend: `tkinter` (default) or `textual` (terminal UI).      |
+| `log_sql`                  | `[config]`    | Enable SQL audit logging (default: `no`).                         |
+| `max_log_size_mb`          | `[config]`    | Rotate the log file at this size in MB (default: `0` = disabled). |
+| `macos_config_file`        | `[config]`    | Additional config file path, active only on macOS.                |
 
 ### Tools
 
@@ -79,14 +81,15 @@ New options in `execsql.conf`:
 
 ### GUI
 
-| Feature              | Description                                                                                                                                             |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Textual TUI backend  | Full terminal-UI backend via the `textual` library. Provides all dialog types (password, pause, message, entry, compare, action, etc.) in the terminal. |
-| Console fallback     | Text-only backend that handles GUI calls in headless environments by printing to stdout.                                                                |
-| Table row counts     | All GUI backends (Tkinter, Textual, Console) display a row count footer below every table widget (e.g. "3 rows", "1 row").                              |
-| Help URL button      | Dialogs that accept the `HELP` keyword display a clickable Help button that opens the URL in the system browser.                                        |
-| Compare diff summary | The compare dialog shows a one-line summary of matching, differing, and table-exclusive rows when key columns are specified.                            |
-| Form validation      | `PROMPT ENTRY_FORM` enforces `validation_regex` (on submit) and `validation_key_regex` (per-keystroke) across all backends. Required fields validated.  |
+| Feature              | Description                                                                                                                                                            |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Textual TUI backend  | Full terminal-UI backend via the `textual` library. Provides all dialog types (password, pause, message, entry, compare, action, etc.) in the terminal.                |
+| Console fallback     | Text-only backend that handles GUI calls in headless environments by printing to stdout.                                                                               |
+| Table row counts     | All GUI backends (Tkinter, Textual, Console) display a row count footer below every table widget (e.g. "3 rows", "1 row").                                             |
+| Help URL button      | Dialogs that accept the `HELP` keyword display a clickable Help button that opens the URL in the system browser.                                                       |
+| Compare diff summary | The compare dialog shows a one-line summary of matching, differing, and table-exclusive rows when key columns are specified.                                           |
+| Compare cell markers | When diff highlighting is active, individual cells that differ within a changed row are prefixed with a bullet marker across all backends (Tkinter, Textual, console). |
+| Form validation      | `PROMPT ENTRY_FORM` enforces `validation_regex` (on submit) and `validation_key_regex` (per-keystroke) across all backends. Required fields validated.                 |
 
 ### Authentication
 
@@ -107,11 +110,12 @@ New options in `execsql.conf`:
 
 ### Developer / Packaging
 
-| Feature                     | Description                                                                                                     |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| VS Code syntax highlighting | Auto-generated `tmLanguage.json` grammar from the dispatch table.                                               |
-| `py.typed` marker           | PEP 561 marker enabling downstream static type checking.                                                        |
-| Structured keyword registry | `--dump-keywords` introspects the dispatch table and outputs JSON used by the grammar generator and test suite. |
+| Feature                      | Description                                                                                                                                                                                  |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| VS Code syntax highlighting  | Auto-generated `tmLanguage.json` grammar from the dispatch table.                                                                                                                            |
+| `py.typed` marker            | PEP 561 marker enabling downstream static type checking.                                                                                                                                     |
+| Structured keyword registry  | `--dump-keywords` introspects the dispatch table and outputs JSON used by the grammar generator and test suite.                                                                              |
+| `python-dateutil` dependency | Date/time parsing delegates to `dateutil.parser.parse()` instead of 231 hardcoded `strptime` format strings. Handles ISO 8601 `T` separators, microseconds, `Z` suffix, and named timezones. |
 
 ### Debugging { #debugging }
 
@@ -161,6 +165,10 @@ ______________________________________________________________________
 
 The CLI framework changed from `optparse` to [Typer](https://typer.tiangolo.com/) with Rich-formatted help text. All original short flags (`-a` through `-z`) are preserved. The tool can be invoked as either `execsql` or `execsql2`.
 
+### Configuration
+
+- **`linux_config_file`** — now only active on Linux (`sys.platform == "linux"`). Upstream applied it to all POSIX systems, including macOS. A new `macos_config_file` option handles macOS specifically.
+
 ### Internal State Management
 
 All 33 mutable runtime globals in `state.py` have been consolidated into a `RuntimeContext` object. The module uses a transparent proxy so existing code is unaffected, but the architecture now supports isolated contexts for testing and future concurrent execution.
@@ -223,17 +231,23 @@ These are behavioral changes driven by security or correctness issues in the ups
 
 ### Bug Fixes
 
-| Area                              | Fix                                                                                                                                                                                           |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Oracle default port               | Corrected from `5432` (PostgreSQL) to `1521`.                                                                                                                                                 |
-| MySQL `LOAD DATA INFILE` encoding | Python encoding names are now mapped to MySQL charset names.                                                                                                                                  |
-| `dt_cast` type converters         | Base `Database` class auto-populates 8 type converters that were previously left empty after the refactor.                                                                                    |
-| `FileWriter` CPU busy-loop        | Uses blocking `queue.get(timeout=0.1)` instead of `get_nowait()` in a tight loop.                                                                                                             |
-| Substitution variable cycles      | 100-iteration limit prevents infinite loops on cyclic variable references.                                                                                                                    |
-| Script location in error messages | `ErrInfo.script_file` and `script_line_no` are now populated via `stamp_errinfo()` so error output includes "Line N of script foo.sql" context — restoring behavior present in the monolith.  |
-| `$ERROR_MESSAGE` not updated      | `$ERROR_MESSAGE` is now set on every error path: `exit_now()`, non-halting SQL errors, and non-halting metacommand errors. Previously it was initialized to `""` and never changed.           |
-| Metacommand error message lost    | When `halt_on_metacommand_err` is `ON`, the original handler `ErrInfo` is now re-raised; the generic "Unknown metacommand" message no longer replaces the specific error from the handler.    |
-| Empty script name in error msg    | `_execute_script_direct()` and `_execute_script_textual_console()` no longer append "in script , line 0" to uncaught-exception messages when `current_script_line()` returns an empty string. |
+| Area                                                | Fix                                                                                                                                                                                                                                                                                                    |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Oracle default port                                 | Corrected from `5432` (PostgreSQL) to `1521`.                                                                                                                                                                                                                                                          |
+| MySQL `LOAD DATA INFILE` encoding                   | Python encoding names are now mapped to MySQL charset names.                                                                                                                                                                                                                                           |
+| `dt_cast` type converters                           | Base `Database` class auto-populates 8 type converters that were previously left empty after the refactor.                                                                                                                                                                                             |
+| `FileWriter` CPU busy-loop                          | Uses blocking `queue.get(timeout=0.1)` instead of `get_nowait()` in a tight loop.                                                                                                                                                                                                                      |
+| Substitution variable cycles                        | 100-iteration limit prevents infinite loops on cyclic variable references.                                                                                                                                                                                                                             |
+| Script location in error messages                   | `ErrInfo.script_file` and `script_line_no` are now populated via `stamp_errinfo()` so error output includes "Line N of script foo.sql" context — restoring behavior present in the monolith.                                                                                                           |
+| `$ERROR_MESSAGE` not updated                        | `$ERROR_MESSAGE` is now set on every error path: `exit_now()`, non-halting SQL errors, and non-halting metacommand errors. Previously it was initialized to `""` and never changed.                                                                                                                    |
+| Metacommand error message lost                      | When `halt_on_metacommand_err` is `ON`, the original handler `ErrInfo` is now re-raised; the generic "Unknown metacommand" message no longer replaces the specific error from the handler.                                                                                                             |
+| Empty script name in error msg                      | `_execute_script_direct()` and `_execute_script_textual_console()` no longer append "in script , line 0" to uncaught-exception messages when `current_script_line()` returns an empty string.                                                                                                          |
+| `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. |
+| `win_config_file` broken                            | Checked `os.name == "windows"` which Python never returns (correct value is `"nt"`). Fixed to `os.name == "nt"`. Inherited from upstream.                                                                                                                                                              |
+| `NumericParser` right-associative                   | Arithmetic operators were parsed right-to-left. `10 - 3 - 2` evaluated as `9` instead of `5`. Fixed to left-associative parsing. Inherited from upstream.                                                                                                                                              |
+| Empty-column check precedence                       | `DataTable` and `Database.populate_table()` had an operator precedence bug in the extra-column emptiness check — a redundant `and conf.del_empty_cols` caused incorrect short-circuit evaluation. Inherited from upstream.                                                                             |
+| SQLite import string processing                     | `SQLiteDatabase.populate_table()` applied `trim_strings`, `replace_newlines`, and `empty_strings` after copying row data, so processing never reached the INSERT. Fixed to process before extraction. Inherited from upstream.                                                                         |
+| `$CURRENT_DATABASE`/`$CURRENT_DBMS` stale after USE | These variables were only set at startup and on CONNECT, not refreshed when `USE` switched the active database. Now set in `set_static_system_vars()` so they update on any connection change.                                                                                                         |
 
 ______________________________________________________________________
 

{execsql2-2.14.1 → execsql2-2.15.1}/docs/reference/configuration.md

@@ -312,7 +312,10 @@ The section and property names that may be used in a configuration file are list
 :   The number of seconds that *execsql* should wait between the time that a query is created in Access (which uses DAO) and the time that the next statement is executed using ODBC. This value must be greater than or equal to 5.0. The default is `5.0`.
 
 `linux_config_file`
-:   The full name or path to an additional configuration file to be read if *execsql* is running on Linux. If only a path is specified, the name of the configuration file should be `execsql.conf`. The configuration file specified will be read immediately following the configuration file in which it is named. No configuration file will be read more than once. If the name or path are invalid, this setting will be silently ignored. This setting may include [substitution variables](substitution_vars.md#substitution_vars); at the time that configuration files are read, however, only environment variables and system variables related to the script name and path are defined.
+:   The full name or path to an additional configuration file to be read if *execsql* is running on Linux (`sys.platform == "linux"`). If only a path is specified, the name of the configuration file should be `execsql.conf`. The configuration file specified will be read immediately following the configuration file in which it is named. No configuration file will be read more than once. If the name or path are invalid, this setting will be silently ignored. This setting may include [substitution variables](substitution_vars.md#substitution_vars); at the time that configuration files are read, however, only environment variables and system variables related to the script name and path are defined.
+
+`macos_config_file`
+:   The full name or path to an additional configuration file to be read if *execsql* is running on macOS (`sys.platform == "darwin"`). Behaves identically to `linux_config_file` but is only active on macOS. Tilde expansion (`~`) is supported.
 
 `log_sql` { #log_sql }
 :   When set to "Yes", all executed SQL statements are written to the log file with a `sql` record type, including the database name, line number, and query text. The property value should be either "Yes" or "No". The default is "No". This can also be enabled via the `CONFIG LOG_SQL` metacommand.

{execsql2-2.14.1 → execsql2-2.15.1}/docs/reference/metacommands.md

@@ -2127,6 +2127,9 @@ Keywords can appear in any order after the table list.
 | `COMPACT` | Use compact grid format for QA summary instead of detailed per-table panels. |
 | `LOGFILE <path>` | Append pg-upsert's plain-text log output to the given file. Supports quoted paths for spaces: `LOGFILE "path/to/log.txt"`. |
 | `CLEANUP` | Drop all `ups_*` temporary tables and views after execution. Without it, temp objects persist for inspection (default). |
+| `EXPORT_FAILURES <dir>` | Write a "fix sheet" of failing QA rows into `<dir>` (directory is created if missing). One row per unique violating staging row, with an `_issues` column summarizing every problem on that row. Supports quoted paths for spaces. Export runs even when QA fails — that is the whole point. A confirmation message (`PG_UPSERT: exported QA failures to <dir> (<format>)`) is written to the terminal, the execsql log, and the `LOGFILE` target if one is given. |
+| `EXPORT_FORMAT csv\|json\|xlsx` | Fix sheet format when `EXPORT_FAILURES` is given. `csv` (default) writes one file per table; `json` writes a single nested file; `xlsx` writes a single workbook with one sheet per table (requires `openpyxl`). |
+| `EXPORT_MAX_ROWS <n>` | Maximum rows to capture per check per table for the fix sheet. Default `1000`. Only meaningful with `EXPORT_FAILURES`. |
 
 ### Substitution variables
 
@@ -2150,6 +2153,7 @@ Set after every `PG_UPSERT` execution:
 | `$PG_UPSERT_TABLE_QA_PASSED` | TRUE/FALSE | QA result for the current table (updated per table) |
 | `$PG_UPSERT_TABLE_ROWS_UPDATED` | integer | Rows updated for the current table (updated per table) |
 | `$PG_UPSERT_TABLE_ROWS_INSERTED` | integer | Rows inserted for the current table (updated per table) |
+| `$PG_UPSERT_EXPORT_PATH` | string | Directory path that the QA fix sheet was written to, or empty if `EXPORT_FAILURES` was not given or nothing was exported. |
 
 !!! note "Using `$PG_UPSERT_RESULT_JSON` with WRITE"
     The JSON value is stored as compact single-line JSON. Because it contains double quotes (`"`), square brackets (`[]`), and apostrophes may appear in data, use tilde or backtick delimiters with WRITE:
@@ -2211,6 +2215,13 @@ For the full list of temporary objects and their schemas, see the [pg-upsert Tem
 -- Write the full JSON result using tilde delimiters (JSON contains " and [])
 -- !x! PG_UPSERT FROM staging TO public TABLES books COMMIT
 -- !x! WRITE ~!!$PG_UPSERT_RESULT_JSON!!~
+
+-- Export failing QA rows to an Excel fix sheet (one sheet per table)
+-- !x! PG_UPSERT QA FROM staging TO public TABLES books, authors EXPORT_FAILURES "qa_failures/" EXPORT_FORMAT xlsx
+
+-- Full pipeline with a CSV fix sheet cap of 50 rows per check per table
+-- !x! PG_UPSERT FROM staging TO public TABLES books, authors EXPORT_FAILURES /tmp/fix EXPORT_MAX_ROWS 50 COMMIT
+-- !x! WRITE "Fix sheet: !!$PG_UPSERT_EXPORT_PATH!!"
 ```
 
 
@@ -2331,6 +2342,8 @@ The 'Show mismatches' button will highlight all the rows in each table that have
 
 ![Display of unmatched data with the PROMPT COMPARE metacommand](../images/unmatched.png)
 
+The "Highlight Diffs" button toggles row-level coloring (green for matching rows, yellow for changed rows, red for rows only in one table) and cell-level markers — individual cells that differ within a changed row are prefixed with a bullet marker so you can see exactly which columns have different values. A one-line summary of matching, differing, and table-exclusive row counts is shown below the tables. Cell-level diff marking works across all backends (Tkinter, Textual, and console).
+
 If the 'Continue' button is selected, the script will continue to run. If the 'Cancel' button is selected, the script will immediately halt unless [CANCEL_HALT](#cancel_halt) is set to OFF. The Enter key also carries out the action of the 'Continue' button, and the Escape key carries out the action of the 'Cancel' button.
 
 If a URL is provided with the HELP keyword, the dialog box will include a button that will open that URL when clicked. The URL must be double-quoted if it contains spaces.

{execsql2-2.14.1 → execsql2-2.15.1}/docs/reference/substitution_vars.md

@@ -75,7 +75,7 @@ $CANCEL_HALT_STATE
 $CONSOLE_WAIT_WHEN_DONE_STATE
 :   The value of the status flag that is set by the `console_wait_when_done` configuration setting or by the [CONFIG CONSOLE WAIT_WHEN_DONE](metacommands.md#console_wait_when_done) metacommand. The value of this variable is always either "ON" or "OFF".
 
-$CONSOLE_WAIT_WHEN_ERROR_STATE
+$CONSOLE_WAIT_WHEN_ERROR_HALT_STATE
 :   The value of the status flag that is set by the `console_wait_when_error_halt` configuration setting or by the [CONFIG CONSOLE WAIT_WHEN_ERROR](metacommands.md#console_wait_when_error) metacommand. The value of this variable is always either "ON" or "OFF".
 
 $COUNTER_x

{execsql2-2.14.1 → execsql2-2.15.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.14.1"
+version = "2.15.1"
 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" }
@@ -40,6 +40,7 @@ classifiers = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+    "python-dateutil>=2.8",
     "rich>=13.0",
     "sqlglot>=25.0",
     "textual>=0.47.0",
@@ -58,7 +59,7 @@ odbc = ["pyodbc"]
 # Feature bundles
 formats = ["odfpy", "xlrd", "openpyxl", "Jinja2", "polars", "tables", "PyYAML"]
 auth = ["keyring"]
-upsert = ["pg-upsert>=1.20.0"]
+upsert = ["pg-upsert>=1.21.0"]
 # Convenience groups
 all-db = [
     "psycopg2-binary",
@@ -161,7 +162,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.14.1"
+current_version = "2.15.1"
 commit = true
 commit_args = "--no-verify"
 tag = true