execsql2 2.8.0__tar.gz → 2.10.0__tar.gz

{execsql2-2.8.0 → execsql2-2.10.0}/.claude/project_context.md

@@ -275,28 +275,63 @@ ______________________________________________________________________
 - [x] **`ASSERT` metacommand** — `-- !x! ASSERT <condition> "message"`. Reuses IF condition engine. 13 tests.
 - [x] **`--dry-run` improvements** — expands substitution variables populated at parse time. 4 new tests.
 - [x] **Script profiling (`--profile`)** — per-statement `perf_counter()` timing with sorted summary table. 19 tests.
-- [ ] **Parallel execution blocks** — `PARALLEL BEGIN ... PARALLEL END` for independent statements. See design notes below.
+- ~~**Parallel execution blocks**~~ — deferred to v3.0+. See design notes and deferral rationale below.
 
-### v2.9 — Library API & Developer Experience
+### Candidate Features (unscheduled — pick and assign to milestones)
 
-- [ ] **Programmatic Python API** — `execsql.run(script, db=...)` for notebook/pipeline usage. Depends on `RuntimeContext` refactor.
+#### Quick Wins
+
+- [x] **`--ping`** — test database connectivity and exit with a status message. Useful for CI health checks and connection debugging. (shipped v2.8.x)
+- ~~`SUB_FILE`~~ — redundant with existing `SUB_INI` metacommand which already loads variables from INI-format files.
+- [ ] **`WRITE TABLE` metacommand** — pretty-print a query result to the console as a formatted table (like `psql` output). Quick debugging aid without needing a full EXPORT.
+- [ ] **`--env` / `--config` flag** — load a specific config file by path instead of relying on the search hierarchy. `execsql --env prod.conf script.sql`.
+
+#### Scripting & Reliability
+
+- [ ] **`ON ERROR RETRY N`** — retry a failed SQL statement N times with exponential backoff. Handles transient network blips and lock timeouts in ETL scripts.
+- [ ] **`DIFF` metacommand** — compare two query results non-interactively and write differences to a file or set `$DIFF_COUNT`. Unlike `PROMPT COMPARE` (which is GUI/interactive), DIFF is headless and scriptable — designed for CI pipelines, automated validation, and audit trails. Supports arbitrary queries, not just table names.
+- [x] **Script linting (`--lint`)** — parse and report common issues without executing: unmatched IF/ENDIF, unmatched LOOP/END LOOP, undefined variable references, missing INCLUDE files. (shipped v2.8.x)
+
+#### Persistent State (`~/.execsql/state.db`)
+
+A central SQLite database at `~/.execsql/state.db` that tracks per-script
+state across runs. Cross-platform via `Path.home()`. Created automatically
+on first use. All features below depend on this infrastructure.
+
+- [ ] **State DB infrastructure** — `StateDB` class, schema creation, `~/.execsql/` directory management. Foundation for everything below.
+- [ ] **Run numbering (`$RUN_NUMBER`, `$LAST_RUN_TIME`, `$FIRST_RUN_TIME`)** — persistent per-script run counter and timestamps. Always-on, incremented each invocation. `--reset-run-number` CLI flag to reset. Useful for audit trails, incremental file naming (`output_!!$RUN_NUMBER!!.csv`), conditional first-run logic.
+- [ ] **Resumable scripts (`--checkpoint`)** — checkpoint after each statement. Auto-resumes on next `--checkpoint` run if checkpoint exists and script hash matches. Saves position, variables, and DB alias. Deletes checkpoint on successful completion.
+- [ ] **Run history (`--history`)** — log each run (start time, duration, exit status, commands run, script path) to a `run_history` table. `execsql --history script.sql` shows past runs. Useful for auditing and debugging intermittent failures.
+- [ ] **Persistent variables (`PERSIST` / `RECALL`)** — save substitution variables across runs. `-- !x! PERSIST $last_watermark` saves to state DB; next run `-- !x! RECALL $last_watermark` restores it. Enables incremental ETL (remember the last-processed timestamp/ID without external bookkeeping).
+- [ ] **Script scheduling metadata** — store cron-like schedule info per script. `execsql --schedule "0 2 * * *" script.sql` records intent. `execsql --list-schedules` shows all. Doesn't execute (that's cron/Task Scheduler's job) — just a registry so you can answer "what runs when?" from one place.
+
+#### Notifications & Integrations
+
+- [ ] **Webhook notifications** — `ON ERROR_HALT WEBHOOK "https://..."` and `ON COMPLETE WEBHOOK "https://..."`. Like the existing `ON ERROR_HALT EMAIL` but for Slack/Teams/PagerDuty. More relevant than email in 2026.
+- [ ] **HTTP/REST export** — `EXPORT QUERY ... TO POST "https://api.example.com/data" AS JSON`. POST query results directly to a webhook or API endpoint.
+
+#### Developer Experience
+
+- [ ] **Programmatic Python API** — `execsql.run(script, db=...)` for notebook/pipeline usage. Each call gets its own isolated `RuntimeContext`.
 - [ ] **TOML configuration** — `execsql.toml` as modern alternative to legacy INI format (coexist initially).
+- [ ] **Colorized SQL in console output** — syntax-highlight SQL statements in WRITE, dry-run, and error output via Rich/Pygments.
 
-### v2.10 — Testing & CI Hardening
+#### Testing & CI Hardening
 
 - [ ] **Property-based testing (Hypothesis)** — for parsers, type inference, substitution variables.
 - [ ] **Parser fuzzing** — `CondParser` and `NumericParser` handle arbitrary user input; fuzz for edge cases.
 - [ ] **Nightly CI against latest DB driver versions** — catch upstream breakage in psycopg2, pymysql, duckdb, etc.
 - [ ] **CI benchmarks** — track substitution variable and dispatch performance over time.
 
-### v2.11 — Documentation & Community
+#### Documentation & Community
 
-- [ ] **Cookbook / recipes page** — real-world examples: ETL workflows, HTML reports, data validation pipelines.
+- [ ] **Cookbook / recipes page** — real-world examples: ETL workflows, HTML reports, data validation pipelines, CI integration.
 - [ ] **Migration guide from upstream execsql** — what changed, what's new, how to switch.
 - [ ] **Interactive tutorial** — guided walkthrough script against a bundled SQLite DB.
 
-### v3.0+ — Future
+#### v3.0+ — Major Features
 
+- [ ] **Parallel execution blocks** — `PARALLEL BEGIN ... PARALLEL END` for independent statements. See design notes and deferral rationale below.
 - [ ] **Plugin system** — entry points for `execsql.exporters`, `execsql.importers`, `execsql.metacommands` allowing external packages to register new handlers.
 - [ ] **LSP / language server** — for the VS Code extension: autocomplete metacommands, validate substitution variables, jump-to-definition for `INCLUDE`d scripts.
 
@@ -367,6 +402,30 @@ INSERT INTO summary_c SELECT ... FROM raw_data;
   block — but that negates parallelism for most backends, so this is
   mainly useful for independent ETL loads.
 
+**Deferral rationale (2026-04):** Moved from v2.8 to v3.0+. The
+complexity-to-value ratio is poor for the current user base:
+
+1. **Connection pooling does not exist.** `DatabasePool` holds one
+   connection per alias. Workers need their own connections, requiring
+   either a pool-per-alias model or fresh connections from the DSN —
+   significant infrastructure work.
+2. **Global state is not thread-safe.** Even with `RuntimeContext`, the
+   context is shared. Workers writing `$LAST_ROWCOUNT` or reading
+   `_state.subvars` would race. Per-worker read-only snapshots are needed.
+3. **Error semantics are complex.** Partial failure (2 of 4 workers fail)
+   requires decisions about cancellation, rollback, and error aggregation.
+4. **Narrow real-world benefit.** Most execsql users target a single DBMS.
+   Databases like PostgreSQL already parallelize queries internally.
+   Running concurrent INSERTTs against the same server often doesn't help
+   because they compete for locks, I/O, and CPU.
+5. **Better alternatives exist for orchestration.** Users with true
+   parallelism needs are better served by calling `execsql.run()` (v2.9
+   library API) from their own threading/async code, or by tools like
+   Airflow/dbt.
+
+Revisit if the library API (v2.9) reveals demand for in-script
+parallelism that can't be met by external orchestration.
+
 ______________________________________________________________________
 
 ## Open Design Questions

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

@@ -13,6 +13,27 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.10.0] - 2026-04-01
+
+### Added
+
+- **`BREAKPOINT` metacommand** — pauses script execution and drops into an interactive debug REPL. The prompt accepts `continue`/`c` to resume, `abort`/`q` to halt, `vars` to list substitution variables, `$VARNAME` to print a single variable, `SELECT ...;` to run ad-hoc SQL against the current database, `next`/`n` to step one statement at a time, `stack` to inspect the command-list stack, and `help` for a command summary. Silently skipped in non-TTY environments (CI, piped input) so automated pipelines are never blocked.
+
+- **`step_mode` on `RuntimeContext`** — internal boolean flag set by the REPL's `next` command; the script engine re-enters the debug REPL after each subsequent statement while step mode is active.
+
+- **`ROW_COUNT_GT(table, N)`**, **`ROW_COUNT_GTE(table, N)`**, **`ROW_COUNT_EQ(table, N)`**, **`ROW_COUNT_LT(table, N)`** conditional tests — compare the row count of any table or view against an integer threshold using `IF`, `ELSEIF`, or `ASSERT`. Each issues a `SELECT count(*)` query against the current database. An error is raised if the table does not exist or the threshold is not an integer.
+
+______________________________________________________________________
+
+## [2.9.0] - 2026-04-01
+
+### Added
+
+- **`--lint` flag** — parse a script and perform static analysis without connecting to a database or executing anything. Reports unmatched `IF`/`ENDIF`, `LOOP`/`END LOOP`, and `BEGIN BATCH`/`END BATCH` blocks as errors; potentially undefined `!!$VAR!!` variable references and missing `INCLUDE` file targets as warnings. Exits 0 if no errors are found (warnings alone do not affect the exit code); exits 1 if any errors are found. Works with both file scripts and inline `-c` scripts.
+- **`--ping` flag** — test database connectivity without running a script. `execsql --ping --dsn <URL>` connects to the database, queries the server version, prints a one-line success summary (DBMS name, version, and location), and exits 0. On failure it prints the error and exits 1. No script file argument is required when `--ping` is used.
+
+______________________________________________________________________
+
 ## [2.8.0] - 2026-04-01
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.8.0
+Version: 2.10.0
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Repository, https://github.com/geocoug/execsql
 Project-URL: Issues, https://github.com/geocoug/execsql/issues
@@ -221,6 +221,7 @@ execsql script.sql                          # read connection from config file
 | `-w`                                | Skip password prompt when a username is supplied                |
 | `--dsn URL`                         | Connection string (e.g. `postgresql://user:pass@host/db`)       |
 | `--dry-run`                         | Parse the script and report commands without executing          |
+| `--lint`                            | Static analysis: check structure and warn on issues (no DB)     |
 | `--progress`                        | Show a progress bar for long-running IMPORT operations          |
 | `--dump-keywords`                   | Print metacommand keywords as JSON and exit                     |
 | `--gui-framework {tkinter,textual}` | GUI framework for interactive prompts                           |

{execsql2-2.8.0 → execsql2-2.10.0}/README.md

@@ -111,6 +111,7 @@ execsql script.sql                          # read connection from config file
 | `-w`                                | Skip password prompt when a username is supplied                |
 | `--dsn URL`                         | Connection string (e.g. `postgresql://user:pass@host/db`)       |
 | `--dry-run`                         | Parse the script and report commands without executing          |
+| `--lint`                            | Static analysis: check structure and warn on issues (no DB)     |
 | `--progress`                        | Show a progress bar for long-running IMPORT operations          |
 | `--dump-keywords`                   | Print metacommand keywords as JSON and exit                     |
 | `--gui-framework {tkinter,textual}` | GUI framework for interactive prompts                           |

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

@@ -24,6 +24,8 @@ ______________________________________________________________________
 | `--gui-framework`               | Select GUI backend: `tkinter` (default) or `textual` (terminal UI).                                                                                                                                                                                                                                                                     |
 | `--dry-run`                     | Parse the script and print the full command list without connecting to a database or executing anything. Substitution variables already populated at parse time (env vars, `--assign-arg` values, built-in start-time vars) are expanded in the output; execution-time variables (`$DB_NAME`, `$CURRENT_TIME`, etc.) remain unexpanded. |
 | `--profile`                     | Record wall-clock time for each SQL and metacommand statement. After the script completes, print a summary table sorted by elapsed time (descending), showing time, percentage of total, source location, command type, and a command preview. Top 20 slowest statements are shown.                                                     |
+| `--ping`                        | Test database connectivity and exit. Connects using the supplied connection parameters, queries for the server version, and prints a one-line success message (exit 0) or the error (exit 1). No script file argument is required.                                                                                                      |
+| `--lint`                        | Parse the script and perform static analysis without connecting to a database. Reports unmatched IF/ENDIF, LOOP/END LOOP, and BEGIN BATCH/END BATCH blocks (errors), potentially undefined `!!$VAR!!` references (warnings), and missing INCLUDE file targets (warnings). Exits 0 if no errors, 1 if errors found.                      |
 
 ### Export Formats
 
@@ -37,11 +39,21 @@ ______________________________________________________________________
 
 ### Metacommands
 
-| Metacommand            | Description                                                                                                                                                           |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ASSERT`               | Evaluate a condition and raise an error (halting the script) if it is false. Supports all IF conditions. Optional quoted failure message. Skipped in false IF blocks. |
-| `CONFIG SHOW_PROGRESS` | Enable the Rich progress bar for IMPORT operations at runtime.                                                                                                        |
-| `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                 |
+| Metacommand            | Description                                                                                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ASSERT`               | Evaluate a condition and raise an error (halting the script) if it is false. Supports all IF conditions. Optional quoted failure message. Skipped in false IF blocks.          |
+| `BREAKPOINT`           | Pause script execution and drop into an interactive debug REPL. Inspect variables, run ad-hoc SQL, and step through the script. Silently skipped in non-TTY (CI) environments. |
+| `CONFIG SHOW_PROGRESS` | Enable the Rich progress bar for IMPORT operations at runtime.                                                                                                                 |
+| `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                          |
+
+### Conditional Tests
+
+| Conditional               | Description                                                                                              |
+| ------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `ROW_COUNT_GT(table, N)`  | True if the number of rows in *table* is strictly greater than *N* (integer). Queries `SELECT count(*)`. |
+| `ROW_COUNT_GTE(table, N)` | True if the number of rows in *table* is greater than or equal to *N*.                                   |
+| `ROW_COUNT_EQ(table, N)`  | True if the number of rows in *table* is exactly equal to *N*.                                           |
+| `ROW_COUNT_LT(table, N)`  | True if the number of rows in *table* is strictly less than *N*.                                         |
 
 ### Configuration Options
 

{execsql2-2.8.0 → execsql2-2.10.0}/docs/getting-started/syntax.md

@@ -196,6 +196,34 @@ Valid encoding names can be displayed with the `-y` option. See also [Character
 
     Substitution variables that are already populated at parse time are expanded in the output: environment variables (`!!&ENV_VAR!!`), `--assign-arg` values (`!!$ARG_1!!`), and built-in start-time variables like `!!$SCRIPT_START_TIME!!` and `!!$USER!!`. Variables that are set during execution — such as `$CURRENT_TIME`, `$DB_NAME`, and `$TIMER` — remain unexpanded because no database connection is established in dry-run mode. Local `~`-prefixed script-scope variables are also left unexpanded.
 
+`--lint`
+
+:   Parse the script and perform static analysis without connecting to a database or executing anything. A complement to `--dry-run` focused on structural correctness rather than command display.
+
+    Checks performed:
+
+    - **Unmatched IF / ENDIF** — open IF blocks with no closing ENDIF, or orphan ENDIF with no IF (error).
+    - **Unmatched LOOP / END LOOP** — open LOOP with no END LOOP, or orphan END LOOP (error).
+    - **Unmatched BEGIN BATCH / END BATCH** — open batch with no close, or orphan END BATCH (error).
+    - **Potentially undefined variables** — `!!$VAR!!` references where `$VAR` is not a built-in variable, not `$ARG_N`, and was not defined by a preceding `SUB` metacommand in the same script (warning — may be a false-positive if the variable is set in a config file or via `-a`).
+    - **Missing INCLUDE files** — `INCLUDE` targets that do not exist on disk relative to the script's directory (warning; `INCLUDE IF EXISTS` targets are never checked).
+    - **Empty script** — no commands found (warning).
+
+    Exits 0 when no errors are found (warnings alone do not affect the exit code). Exits 1 when any errors are found.
+
+    ```bash
+    execsql --lint script.sql
+    ```
+
+`--ping`
+
+:   Test database connectivity and exit. Connects to the configured database, queries the server version if possible, and prints a one-line summary on success (exit 0). On failure, prints the error message and exits with code 1. No script file is required — `--ping` can be combined with `--dsn` or other connection flags without specifying a `.sql` file.
+
+    ```bash
+    execsql --ping --dsn postgresql://user:pass@host/db
+    execsql --ping --dsn sqlite:///mydb.sqlite
+    ```
+
 `--profile`
 
 :   Record the wall-clock execution time of each SQL statement and metacommand. After the script finishes, print a summary table to the console showing elapsed time, percentage of total time, source file and line number, command type, and a preview of the command text. Statements are sorted from slowest to fastest; the top 20 are displayed. Useful for identifying slow queries or metacommands in long-running scripts.

{execsql2-2.8.0 → execsql2-2.10.0}/docs/reference/configuration.md

@@ -28,7 +28,7 @@ The section and property names that may be used in a configuration file are list
 :   The database server name. This is equivalent to the second command-line argument for client-server databases.
 
 `db`
-:   The database name. This is equivalent to the third command-line argument for client-server databases
+:   The database name. This is equivalent to the third command-line argument for client-server databases. The alias `database` is also accepted.
 
 `db_file`
 :   The name of the database file. This is equivalent to the second command-line argument for file-based databases.
@@ -132,9 +132,9 @@ The section and property names that may be used in a configuration file are list
 
 :   Controls how often row-count progress is written to the execution log during IMPORT operations. Set to a positive integer N to log a status line every N rows (e.g. `import_progress_interval = 10000`). The default is `0` (silent). When enabled, a final completion line (e.g. "IMPORT into schema.table complete: 1000000 rows imported.") is also written. Supported for all database adapters.
 
-`import_only_common_columns` { #import_only_common }
+`import_common_columns_only` { #import_only_common }
 
-:   Determines whether the [IMPORT](metacommands.md#import) metacommand will import data from a CSV file when the file has more data columns than the target table. The property value should be either "Yes" or "No". The default, "No", indicates that the target table must have all of the columns present in the CSV file; if the target table has fewer columns, an error will result. A property value of "Yes" will result in import of only the columns in common between the CSV file and the target table.
+:   Determines whether the [IMPORT](metacommands.md#import) metacommand will import data from a CSV file when the file has more data columns than the target table. The property value should be either "Yes" or "No". The default, "No", indicates that the target table must have all of the columns present in the CSV file; if the target table has fewer columns, an error will result. A property value of "Yes" will result in import of only the columns in common between the CSV file and the target table. The legacy alias `import_only_common_columns` is also accepted.
 
 `import_row_buffer`
 
@@ -171,7 +171,7 @@ The section and property names that may be used in a configuration file are list
 ## Section `output` { #config_output }
 
 `log_write_messages`
-:   Specifies whether output of the [WRITE](metacommands.md#write) metacommand will also be written to *execsql*'s log file. The property value should be either "Yes" or "No". This configuration property can also be controlled within a script with the [CONFIG LOG_WRITE_MESSAGES](metacommands.md#logwritemessages) metacommand.
+:   Specifies whether output of the [WRITE](metacommands.md#write) metacommand will also be written to *execsql*'s log file. The property value should be either "Yes" or "No". The default is "No". This configuration property can also be controlled within a script with the [CONFIG LOG_WRITE_MESSAGES](metacommands.md#logwritemessages) metacommand.
 
 `make_export_dirs`
 :   The output directories used in the [EXPORT](metacommands.md#export) and [WRITE](metacommands.md#write) metacommands will be automatically created if they do not exist (and the user has the necessary permission). The property value should be either "Yes" or "No". This is equivalent to the "-d" command-line option.
@@ -186,12 +186,12 @@ The section and property names that may be used in a configuration file are list
 :   The number of data rows to be buffered from the database when exporting data. Larger values result in faster exports, up to a point, and at a diminishing rate of return. Larger values also require more memory. The setting value must be a positive integer greater than zero. The default value is 1000 rows. This value cannot be customized when using DuckDB.
 
 `hdf5_text_len`
-:   The length to be assigned to columns that have the 'text' data type when data are exported in the HDF5 format.
+:   The length to be assigned to columns that have the 'text' data type when data are exported in the HDF5 format. The default is `1000`.
 
 `css_file`
 :   The URI of a CSS file to be included in the header of an HTML file created with the [EXPORT](metacommands.md#export) metacommand. If this is specified, it will replace the CSS styles that *execsql* would otherwise use.
 
-`css_style`
+`css_styles`
 :   A set of CSS style specifications to be included in the header of an HTML file created with the [EXPORT](metacommands.md#export) metacommand. If this is specified, it will replace the CSS styles that *execsql* would otherwise use. Both css_file and css_style may be specified; if they are, they will be included in the header of the HTML file in that order.
 
 `template_processor`
@@ -240,6 +240,10 @@ The section and property names that may be used in a configuration file are list
     - 2: Also use a GUI dialog if a message is included with the [HALT](metacommands.md#halt) metacommand, and prompt for the initial database to use if no database connection parameters are specified in a configuration file or on the command line.
     - 3: Additionally, open a GUI console when *execsql* starts.
 
+`gui_framework` { #gui_framework }
+
+:   The GUI framework to use when `gui_level` is greater than 0. The property value must be either `tkinter` (the default) or `textual`. `tkinter` uses native desktop dialogs via Tk; `textual` provides a terminal-based UI that works in headless/SSH environments. This can also be set via the `--gui-framework` command-line option.
+
 ## Section `email`
 
 `host`
@@ -305,7 +309,7 @@ The section and property names that may be used in a configuration file are list
 :   The full name or path to an additional configuration file to be read. 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.
 
 `dao_flush_delay_secs`
-:   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 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.

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

@@ -60,14 +60,18 @@ Evaluates `<condition>` using the same expression engine as [IF](#if_cmd). If th
 
 When [HALT_ON_METACOMMAND_ERROR](#config) is `ON` (the default), a failed assertion halts the script. When it is `OFF`, execution continues after the failure is logged.
 
-The `<condition>` supports all conditional tests available to `IF`, including:
+The `<condition>` supports all [conditional tests](metacommands.md#conditional_tests) available to `IF`, including:
 
-- `TABLE_EXISTS <table>` / `TABLE_NOT_EXISTS <table>`
-- `COLUMN_EXISTS <table> <column>` / `COLUMN_NOT_EXISTS <table> <column>`
-- `ROWCOUNT <op> <n>` (e.g. `ROWCOUNT > 0`)
-- Variable comparisons: `$varname = 'value'`, `$varname != 'value'`
-- Numeric comparisons: `$varname > <n>`, `$varname <= <n>`
-- `DATABASE_TYPE <type>` / `DATABASE_TYPE_NOT <type>`
+- `TABLE_EXISTS(<table>)` / `NOT TABLE_EXISTS(<table>)`
+- `COLUMN_EXISTS(<table>, <column>)` / `NOT COLUMN_EXISTS(<table>, <column>)`
+- `HAS_ROWS(<table>)` / `NOT HAS_ROWS(<table>)`
+- `EQUAL(<val1>, <val2>)` / `NOT EQUAL(<val1>, <val2>)`
+- `IS_GT(<val1>, <val2>)`, `IS_GTE(<val1>, <val2>)`, `IS_ZERO(<val>)`
+- `ROW_COUNT_GT(<table>, N)`, `ROW_COUNT_GTE(<table>, N)`, `ROW_COUNT_EQ(<table>, N)`, `ROW_COUNT_LT(<table>, N)`
+- `DBMS(<type>)`, `SCHEMA_EXISTS(<schema>)`, `VIEW_EXISTS(<view>)`
+- Boolean combinators: `AND`, `OR`, `NOT`
+
+Substitution variables in the condition are expanded before evaluation. Use the `!!varname!!` syntax (e.g., `!!$myvar!!`).
 
 ASSERT is silently skipped inside a `False` [IF](#if_cmd) block.
 
@@ -75,13 +79,17 @@ ASSERT is silently skipped inside a `False` [IF](#if_cmd) block.
 
 ```sql
 -- Halt with a custom message if the staging table is missing.
--- !x! ASSERT TABLE_EXISTS staging "staging table must exist before running this script"
+-- !x! ASSERT TABLE_EXISTS(staging) "staging table must exist before running this script"
 
--- Halt with the default message if no rows were returned.
--- !x! ASSERT ROWCOUNT > 0
+-- Halt with the default message if the table has no rows.
+-- !x! ASSERT HAS_ROWS(staging)
 
 -- Verify a substitution variable has the expected value.
--- !x! ASSERT $env = 'prod' 'expected production environment'
+-- !x! SUB env prod
+-- !x! ASSERT EQUAL(!!env!!, prod) 'expected production environment'
+
+-- Combine conditions with AND/OR/NOT.
+-- !x! ASSERT TABLE_EXISTS(orders) AND HAS_ROWS(orders) "orders table missing or empty"
 ```
 
 ## AUTOCOMMIT
@@ -109,6 +117,43 @@ The AUTOCOMMIT metacommand is database-specific, and affects only the database i
 The [IMPORT](#import) and [COPY](#copy) metacommands do not commit data changes while AUTOCOMMIT is off (except when the NEW or REPLACEMENT clauses are used with Firebird; in those cases the 'create table' statement that *execsql* generates and runs will be committed). The SQL statements generated by the [IMPORT](#import) and [COPY](#copy) metacommands are sent to the database, however. Therefore the AUTOCOMMIT metacommand is recommended when explicit transaction control is to be applied to the [IMPORT](#import) and [COPY](#copy) metacommands.
 
 
+## BREAKPOINT { #breakpoint }
+
+```
+BREAKPOINT
+```
+
+Pauses script execution and drops into an interactive debug REPL (read-eval-print loop) on the console. Use this to inspect state and step through a script interactively while debugging.
+
+**Non-interactive safety:** If `sys.stdin` is not a TTY (e.g. CI pipelines, piped input, batch execution) the metacommand is silently skipped. Scripts will never hang in automation.
+
+**REPL commands:**
+
+| Command | Description |
+|---------|-------------|
+| `continue` or `c` | Resume script execution |
+| `abort`, `q`, or `quit` | Halt the script with exit status 1 |
+| `vars` | List all substitution variables and their current values |
+| `$VARNAME` | Print the value of a single variable (also `&VAR`, `@VAR`) |
+| `SELECT ...;` | Run an ad-hoc SQL query against the current database and pretty-print results |
+| `next` or `n` | Execute the next script statement, then pause again (step mode) |
+| `stack` | Show the command-list stack: script name, cursor index, and nesting depth |
+| `help` | Show the list of available REPL commands |
+
+Pressing Ctrl-D (EOF) or Ctrl-C (KeyboardInterrupt) at the `execsql debug>` prompt resumes execution, the same as typing `continue`.
+
+**Example:**
+
+```sql
+INSERT INTO staging SELECT * FROM raw_data;
+-- !x! BREAKPOINT
+-- Script pauses here. Inspect variables, run queries, then continue.
+SELECT count(*) FROM staging;
+```
+
+BREAKPOINT is silently skipped inside a `False` [IF](#if_cmd) block.
+
+
 ## BEGIN BATCH and END BATCH { #batch }
 
 ```
@@ -1428,6 +1473,62 @@ IS_GTE(<value1>, <value2>)
 Evaluates whether or not the first of the specified values is greater than or equal to the second value. If the values are not numeric, an error will occur, and script processing will halt.
 
 
+### *ROW_COUNT_GT* { #row_count_gt }
+
+```
+ROW_COUNT_GT(<table_name>, <N>)
+```
+
+Evaluates whether the number of rows in the specified table or view is strictly greater than the integer *N*. Issues a `SELECT count(*)` query against the current database. An error will occur if the table does not exist or is not accessible.
+
+
+### *ROW_COUNT_GTE* { #row_count_gte }
+
+```
+ROW_COUNT_GTE(<table_name>, <N>)
+```
+
+Evaluates whether the number of rows in the specified table or view is greater than or equal to the integer *N*.
+
+
+### *ROW_COUNT_EQ* { #row_count_eq }
+
+```
+ROW_COUNT_EQ(<table_name>, <N>)
+```
+
+Evaluates whether the number of rows in the specified table or view is exactly equal to the integer *N*.
+
+
+### *ROW_COUNT_LT* { #row_count_lt }
+
+```
+ROW_COUNT_LT(<table_name>, <N>)
+```
+
+Evaluates whether the number of rows in the specified table or view is strictly less than the integer *N*.
+
+**Examples:**
+
+```sql
+-- Halt if the orders table is empty.
+-- !x! ASSERT ROW_COUNT_GT(orders, 0) "orders table must not be empty"
+
+-- Only process if staging has at least 1000 rows.
+-- !x! IF (ROW_COUNT_GTE(staging, 1000))
+-- !x!   WRITE "staging is ready"
+-- !x! ENDIF
+
+-- Verify exactly 12 monthly records were loaded.
+-- !x! ASSERT ROW_COUNT_EQ(monthly_totals, 12) "expected 12 monthly rows"
+
+-- Skip cleanup if the temp table already has fewer than 100 rows.
+-- !x! IF (ROW_COUNT_LT(temp_work, 100))
+-- !x!   WRITE "temp_work is small, skipping truncate"
+-- !x! ENDIF
+```
+
+
 ### *IS_NULL*
 
 ```

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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.8.0"
+version = "2.10.0"
 description = "Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE.txt" }
@@ -158,7 +158,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.8.0"
+current_version = "2.10.0"
 commit = true
 commit_args = "--no-verify"
 tag = true

{execsql2-2.8.0 → execsql2-2.10.0}/src/execsql/cli/__init__.py

@@ -223,6 +223,25 @@ def main(
         "--dry-run",
         help=("Parse the script and print the command list without connecting to a database or executing anything."),
     ),
+    lint: bool = typer.Option(
+        False,
+        "--lint",
+        help=(
+            "Parse the script and perform static analysis without connecting to a database or executing anything. "
+            "Reports unmatched IF/ENDIF/LOOP/BATCH blocks (errors), potentially undefined variables, "
+            "and missing INCLUDE files (warnings). Exits 0 if no errors, 1 if errors found."
+        ),
+    ),
+    ping: bool = typer.Option(
+        False,
+        "--ping",
+        help=(
+            "Test database connectivity and exit. "
+            "Prints connection details and the server version on success (exit 0), "
+            "or the error message on failure (exit 1). "
+            "No script file is required."
+        ),
+    ),
     dsn: str | None = typer.Option(
         None,
         "--dsn",
@@ -350,6 +369,10 @@ def main(
     positional = args or []
     if command is not None:
         script_name = None  # inline mode — no script file
+    elif ping:
+        # --ping does not require a script file; positional args are still
+        # available for server/db arguments if --dsn is not used.
+        script_name = None
     else:
         if not positional:
             _err_console.print(
@@ -421,6 +444,8 @@ def main(
         output_dir=output_dir,
         progress=progress,
         profile=profile,
+        ping=ping,
+        lint=lint,
     )