execsql2 2.7.1__tar.gz → 2.9.0__tar.gz

{execsql2-2.7.1 → execsql2-2.9.0}/.claude/project_context.md

@@ -272,31 +272,66 @@ ______________________________________________________________________
 
 ### v2.8 — Scripting Power Features
 
-- [ ] **`ASSERT` metacommand** — `-- !x! ASSERT <condition> "message"`. Data validation for CI pipelines and sanity checks.
-- [ ] **`--dry-run` improvements** — show SQL with substitution variables expanded, not just raw metacommands.
-- [ ] **Script profiling (`--profile`)** — per-statement execution times, summary report at end. Leverages existing `Timer` infrastructure.
-- [ ] **Parallel execution blocks** — `PARALLEL BEGIN ... PARALLEL END` for independent statements. See design notes below.
+- [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**~~ — 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.7.1 → execsql2-2.9.0}/CHANGELOG.md

@@ -13,6 +13,28 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [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
+
+- **`--profile` flag** — records wall-clock time for each SQL and metacommand statement and prints a formatted timing summary after the script completes. The summary lists statements sorted by elapsed time descending (top 20 shown), with per-statement percentage of total time, source location, command type, and a preview of the command text.
+- **`ASSERT` metacommand** — evaluates any IF-compatible condition and raises an error (halting the script when `HALT_ON_METACOMMAND_ERROR` is `ON`) if the condition is false. Supports an optional quoted failure message; omitting the message produces `Assertion failed: <condition>`. A passing assertion is logged. ASSERT is silently skipped inside a false IF block.
+
+### Changed
+
+- **`--dry-run` expands substitution variables** — the command list printed by `--dry-run` now shows resolved `!!$VAR!!` / `!!&ENV!!` tokens for variables that are already populated at parse time (environment variables, `--assign-arg` values, config-sourced variables, and built-in start-time variables like `$SCRIPT_START_TIME`). Variables that are set during execution (e.g. `$CURRENT_TIME`, `$DB_NAME`, `$TIMER`) remain unexpanded because the database connection has not yet been established. Local `~`-prefixed script-scope variables are also left unexpanded. If expansion fails (e.g. a cycle is detected), the raw token is displayed instead.
+
+______________________________________________________________________
+
 ## [2.7.1] - 2026-04-01
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.7.1
+Version: 2.9.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                           |
@@ -233,6 +234,7 @@ Run `execsql --help` for the full option list, or `execsql -m` to list all metac
 - Export query results in 20+ formats including CSV, TSV, JSON, YAML, XML, HTML, Markdown, LaTeX, XLSX, OpenDocument, Feather, Parquet, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
 - Copy data between databases, including across different DBMS types.
 - Conditionally execute SQL and metacommands using `IF`/`ELSE`/`ENDIF` based on data values, DBMS type, or user input.
+- Validate data with `ASSERT` — halt the script with a clear error message if a condition is false (ideal for CI pipelines).
 - Loop over blocks of SQL and metacommands using `LOOP`/`ENDLOOP`.
 - Use substitution variables (`SUB`, `$ARG_x`, built-in variables like `$date_tag`) to parameterize scripts.
 - Include or chain scripts with `INCLUDE` and `SCRIPT`.

{execsql2-2.7.1 → execsql2-2.9.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                           |
@@ -123,6 +124,7 @@ Run `execsql --help` for the full option list, or `execsql -m` to list all metac
 - Export query results in 20+ formats including CSV, TSV, JSON, YAML, XML, HTML, Markdown, LaTeX, XLSX, OpenDocument, Feather, Parquet, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
 - Copy data between databases, including across different DBMS types.
 - Conditionally execute SQL and metacommands using `IF`/`ELSE`/`ENDIF` based on data values, DBMS type, or user input.
+- Validate data with `ASSERT` — halt the script with a clear error message if a condition is false (ideal for CI pipelines).
 - Loop over blocks of SQL and metacommands using `LOOP`/`ENDLOOP`.
 - Use substitution variables (`SUB`, `$ARG_x`, built-in variables like `$date_tag`) to parameterize scripts.
 - Include or chain scripts with `INCLUDE` and `SCRIPT`.

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

@@ -13,16 +13,19 @@ ______________________________________________________________________
 
 ### CLI Options
 
-| Flag                            | Description                                                                                                                                                            |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--version`                     | Print version and exit (Rich-formatted).                                                                                                                               |
-| `-c` / `--command`              | Execute an inline SQL or metacommand string instead of a script file.                                                                                                  |
-| `--dsn` / `--connection-string` | Accept a standard database URL (e.g. `postgresql://user:pass@host/db`). Supports `postgresql`, `mysql`, `mssql`, `oracle`, `firebird`, `sqlite`, and `duckdb` schemes. |
-| `--output-dir`                  | Set a default base directory for export output files.                                                                                                                  |
-| `--progress`                    | Show a Rich progress bar during long-running IMPORT operations.                                                                                                        |
-| `--dump-keywords`               | Emit all metacommand keywords, conditionals, config options, and export formats as structured JSON.                                                                    |
-| `--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.                                                               |
+| Flag                            | Description                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--version`                     | Print version and exit (Rich-formatted).                                                                                                                                                                                                                                                                                                |
+| `-c` / `--command`              | Execute an inline SQL or metacommand string instead of a script file.                                                                                                                                                                                                                                                                   |
+| `--dsn` / `--connection-string` | Accept a standard database URL (e.g. `postgresql://user:pass@host/db`). Supports `postgresql`, `mysql`, `mssql`, `oracle`, `firebird`, `sqlite`, and `duckdb` schemes.                                                                                                                                                                  |
+| `--output-dir`                  | Set a default base directory for export output files.                                                                                                                                                                                                                                                                                   |
+| `--progress`                    | Show a Rich progress bar during long-running IMPORT operations.                                                                                                                                                                                                                                                                         |
+| `--dump-keywords`               | Emit all metacommand keywords, conditionals, config options, and export formats as structured JSON.                                                                                                                                                                                                                                     |
+| `--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
 
@@ -36,10 +39,11 @@ ______________________________________________________________________
 
 ### Metacommands
 
-| Metacommand            | Description                                                           |
-| ---------------------- | --------------------------------------------------------------------- |
-| `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. |
+| `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.                                                                                                 |
 
 ### Configuration Options
 

{execsql2-2.7.1 → execsql2-2.9.0}/docs/getting-started/syntax.md

@@ -175,21 +175,61 @@ Valid encoding names can be displayed with the `-y` option. See also [Character
 ### Informational options
 
 `-m`, `--metacommands`
+
 :   List all metacommands and exit.
 
 `-o`, `--online-help`
+
 :   Open the online documentation in the default browser.
 
 `-y`, `--encodings`
+
 :   List all valid character encoding names and exit.
 
 `--dump-keywords`
+
 :   Dump all metacommand keywords, conditional functions, config options, and export formats as JSON and exit. Useful for tooling that consumes execsql's keyword registry (e.g., the VS Code grammar generator).
 
 `--dry-run`
+
 :   Parse the script (or inline `-c` command) and print the full command list — SQL statements and metacommands with source locations — without connecting to a database or executing anything. Useful for validating scripts.
 
+    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.
+
 `--version`
+
 :   Show the version number and exit.
 
 ## Configuration File Defaults { #config_defaults }

{execsql2-2.7.1 → execsql2-2.9.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.7.1 → execsql2-2.9.0}/docs/reference/metacommands.md

@@ -48,6 +48,49 @@ Double quotes (as shown above), apostrophes, or square brackets can be used to d
 
 See the [PROMPT ASK](#prompt_ask) metacommand for a version of this command that uses a GUI window and that can display a data table with the prompt.
 
+## ASSERT { #assert }
+
+```
+ASSERT <condition>
+ASSERT <condition> "<failure message>"
+ASSERT <condition> '<failure message>'
+```
+
+Evaluates `<condition>` using the same expression engine as [IF](#if_cmd). If the condition is `True`, execution continues silently (and the result is written to the log). If the condition is `False`, an error is raised with the provided failure message. If no message is supplied, the default message is `Assertion failed: <condition>`.
+
+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](metacommands.md#conditional_tests) available to `IF`, including:
+
+- `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>)`
+- `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.
+
+**Examples:**
+
+```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"
+
+-- 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! 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
 
 ```

{execsql2-2.7.1 → execsql2-2.9.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|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|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": {

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

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

{execsql2-2.7.1 → execsql2-2.9.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",
@@ -254,6 +273,11 @@ def main(
         "--dump-keywords",
         help="Dump all metacommand keywords as JSON and exit.",
     ),
+    profile: bool = typer.Option(
+        False,
+        "--profile",
+        help="Record per-statement execution times and print a timing summary after the script completes.",
+    ),
     version: bool | None = typer.Option(
         None,
         "--version",
@@ -345,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(
@@ -415,6 +443,9 @@ def main(
         dsn=dsn,
         output_dir=output_dir,
         progress=progress,
+        profile=profile,
+        ping=ping,
+        lint=lint,
     )