execsql2 2.24.0__tar.gz → 2.25.1__tar.gz

execsql2-2.25.1/.github/dependabot.yml

@@ -0,0 +1,48 @@
+# Dependabot keeps the SHA-pinned GitHub Actions in ci-cd.yml up to
+# date. The audit's B22 finding (F059) called out that pinning to
+# major-version tags (e.g. `actions/checkout@v6`) is supply-chain
+# exposure — an attacker who compromises the repo can retag any v6.x
+# release to point at malicious code and every consumer pulls it on
+# the next run. Pinning to a 40-char SHA closes that hole, but the
+# pins must be refreshed when upstream ships a real new release;
+# Dependabot files a PR with the new SHA and a CHANGELOG link.
+version: 2
+updates:
+    - package-ecosystem: github-actions
+      directory: /
+      schedule:
+          interval: weekly
+      groups:
+          actions-minor-and-patch:
+              patterns:
+                  - "*"
+              update-types:
+                  - minor
+                  - patch
+    # Python packages in uv.lock (the development environment; users resolve
+    # their own versions from pyproject.toml). ruff is bumped through the
+    # pre-commit entry below: tests/test_tooling_versions.py requires the
+    # uv.lock ruff to equal the pre-commit rev, so on that PR run
+    # `uv lock --upgrade-package ruff==<new version>` and push.
+    - package-ecosystem: uv
+      directory: /
+      schedule:
+          interval: weekly
+      ignore:
+          - dependency-name: ruff
+      groups:
+          python-minor-and-patch:
+              patterns:
+                  - "*"
+              update-types:
+                  - minor
+                  - patch
+    # Hook revs in .pre-commit-config.yaml.
+    - package-ecosystem: pre-commit
+      directory: /
+      schedule:
+          interval: weekly
+      groups:
+          pre-commit-hooks:
+              patterns:
+                  - "*"

{execsql2-2.24.0 → execsql2-2.25.1}/.github/workflows/ci-cd.yml

@@ -24,7 +24,13 @@ jobs:
             - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
               with:
                   python-version: "3.13"
-            - run: python -m pip install ruff
+            # The ruff that pre-commit runs, so the two jobs cannot disagree;
+            # tests/test_tooling_versions.py keeps uv.lock on the same version.
+            - name: Install the ruff pinned in .pre-commit-config.yaml
+              run: |
+                  version=$(grep -A1 'astral-sh/ruff-pre-commit' .pre-commit-config.yaml | grep -oP 'rev: v\K[0-9.]+')
+                  echo "ruff $version"
+                  python -m pip install "ruff==$version"
             - run: ruff check src/ tests/
             - run: ruff format --check src/ tests/
 
@@ -38,10 +44,12 @@ jobs:
             - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
               with:
                   python-version: "3.13"
-                  cache: "pip"
-            - run: python -m pip install --upgrade pip
-            - run: python -m pip install ".[dev]"
-            - run: mypy src/execsql/
+            - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10.2.0
+            # The environment `just setup` builds: mypy and the packages it
+            # type-checks against come from uv.lock, so CI and local runs agree.
+            # --locked also fails the job when uv.lock is out of date.
+            - run: uv sync --locked --all-extras
+            - run: uv run --no-sync mypy src/execsql/
 
     formatter-corpus:
         name: formatter-corpus
@@ -342,6 +350,16 @@ jobs:
               with:
                   python-version: "3.13"
                   cache: "pip"
+            - name: Check the tag matches the package version
+              # A tag on a commit whose pyproject.toml has another version
+              # would build, and release, the wrong version under the tag.
+              if: startsWith(github.ref, 'refs/tags/v')
+              run: |
+                  version="$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")"
+                  if [ "${GITHUB_REF_NAME#v}" != "$version" ]; then
+                      echo "::error::Tag $GITHUB_REF_NAME does not match project.version $version in pyproject.toml"
+                      exit 1
+                  fi
             - name: Build sdist + wheel
               run: |
                   python -m pip install --upgrade pip
@@ -380,11 +398,12 @@ jobs:
               uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
               with:
                   packages-dir: dist
-                  skip-existing: true
 
     generate-release:
         name: Generate GitHub Release
-        needs: [ build ]
+        # After the PyPI upload, so a release is never announced for a
+        # version that pip cannot install.
+        needs: [ publish ]
         if: startsWith(github.ref, 'refs/tags/v')
         runs-on: ubuntu-latest
         permissions:
@@ -397,75 +416,21 @@ jobs:
               with:
                   name: ${{ github.event.repository.name }}
                   path: dist/
+            - name: Detect pre-release tag
+              id: tag
+              # PEP 440 pre-release suffix (a1, b2, rc1) on the tag -> mark the
+              # GitHub Release as a pre-release so it never becomes "latest".
+              run: |
+                  if [[ "${GITHUB_REF_NAME#v}" =~ (a|b|rc)[0-9]+$ ]]; then
+                      echo "prerelease=true" >> "$GITHUB_OUTPUT"
+                  else
+                      echo "prerelease=false" >> "$GITHUB_OUTPUT"
+                  fi
             - name: Create release
               uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64  # v3.0.3
               with:
                   draft: false
-                  prerelease: false
+                  prerelease: ${{ steps.tag.outputs.prerelease }}
                   generate_release_notes: true
                   files: |
                       dist/*
-
-    publish-vscode:
-        name: Publish VS Code extension 🧩
-        needs: [ build ]
-        # Only on a version tag, and only when a Marketplace token is configured.
-        # Without VSCE_PAT the job is skipped rather than failed, so a release
-        # still completes for anyone who has not set the secret up.
-        if: startsWith(github.ref, 'refs/tags/v')
-        runs-on: ubuntu-latest
-        permissions:
-            contents: read
-        steps:
-            - name: Checkout
-              uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
-            - name: Check for a Marketplace token
-              id: gate
-              # Read through env, never interpolated into the command line.
-              env:
-                  VSCE_PAT: ${{ secrets.VSCE_PAT }}
-              run: |
-                  if [ -n "$VSCE_PAT" ]; then
-                      echo "ready=true" >> "$GITHUB_OUTPUT"
-                  else
-                      echo "ready=false" >> "$GITHUB_OUTPUT"
-                      echo "VSCE_PAT is not set — skipping the Marketplace publish." >> "$GITHUB_STEP_SUMMARY"
-                  fi
-            - name: Setup Python
-              if: steps.gate.outputs.ready == 'true'
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
-              with:
-                  python-version: "3.13"
-            # The grammar is generated from the metacommand dispatch table, so it
-            # is rebuilt here rather than trusted to be current in the tree.
-            - name: Regenerate the TextMate grammar
-              if: steps.gate.outputs.ready == 'true'
-              run: |
-                  python -m pip install --upgrade pip
-                  python -m pip install .
-                  python scripts/generate_vscode_grammar.py
-            - name: Fail if the committed grammar is stale
-              if: steps.gate.outputs.ready == 'true'
-              run: git diff --exit-code -- extras/vscode-execsql/syntaxes/
-            # The Marketplace refuses a version it already has, so the
-            # extension version tracks the tag rather than being bumped by hand
-            # in a second place.
-            - name: Set the extension version from the tag
-              if: steps.gate.outputs.ready == 'true'
-              working-directory: extras/vscode-execsql
-              run: |
-                  version="${GITHUB_REF_NAME#v}"
-                  python - "$version" <<'PY'
-                  import json, pathlib, sys
-                  p = pathlib.Path("package.json")
-                  data = json.loads(p.read_text())
-                  data["version"] = sys.argv[1]
-                  p.write_text(json.dumps(data, indent=2) + "\n")
-                  print("extension version set to", sys.argv[1])
-                  PY
-            - name: Publish
-              if: steps.gate.outputs.ready == 'true'
-              working-directory: extras/vscode-execsql
-              run: npx --yes @vscode/vsce@latest publish
-              env:
-                  VSCE_PAT: ${{ secrets.VSCE_PAT }}

{execsql2-2.24.0 → execsql2-2.25.1}/.pre-commit-config.yaml

@@ -67,6 +67,7 @@ repos:
     rev: v1.44.0
     hooks:
       - id: typos
+        args: [--force-exclude]
   # Lint & format with ruff
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.7

{execsql2-2.24.0 → execsql2-2.25.1}/CHANGELOG.md

@@ -13,6 +13,82 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.25.1] - 2026-10-09
+
+### Fixed
+
+- **`execsql lint` `V001` / `V002` and nested variable names:** `!!N_!!CHECK_GROUP!!_CHECKS!!` no longer reports `!!N_!!` and `!!_CHECKS!!` as undefined; the inner `!!CHECK_GROUP!!` is checked, and counts as used.
+- **`execsql lint` and `SUB_INI`:** a script whose `SUB_INI` names a FIFO or device (`/dev/zero`) no longer hangs lint, and an INI file that does not parse no longer stops it.
+
+______________________________________________________________________
+
+## [2.25.0] - 2026-10-09
+
+### Added
+
+- **`execsql lint` rule `P002` (`split-dollar-quote`):** reports a `$$ ... $$` function or `DO` body that is not between `BEGIN SQL` and `END SQL`, which execsql would send in pieces at the first line ending in `;`.
+- **`execsql lint` rule `P003` (`unknown-metacommand`):** reports a misspelled or malformed metacommand, such as `SUBSTITUTE x 1` for `SUB x 1`, or `EXPORT t TOO out.csv`, that `execsql run` would stop at with `Unknown metacommand`.
+- **`execsql lint` rule `P004` (`unknown-condition`):** reports a condition with an unknown test, such as `IF(hasrowz(t))`, or one that cannot be parsed, such as `ASSERT !!flag!! = TRUE`, in `IF`, `ELSEIF`, `ANDIF`, `ORIF`, `LOOP`, `EXECUTE SCRIPT ... WHILE`, `ASSERT` and `WAIT_UNTIL`.
+- **`[email] ca_file` and `verify_certificate` settings** for the SMTP server's TLS certificate: trust an internal CA, or turn verification off for a test relay.
+
+### Changed
+
+- **`EMAIL` over TLS verifies the server certificate.** With `use_ssl` or `use_tls`, a mail server whose certificate is untrusted or does not match `host` stops the `EMAIL` metacommand before the password is sent. For a relay with an internal certificate, set `[email] ca_file`; to turn the check off, set `verify_certificate = No`.
+- **A `--dsn` / `execsql.run(dsn=...)` user, password or database is percent-decoded**, so `@`, `:`, `/`, `?`, `#` and `%` can be given encoded (`p%40ss`). A password that contains `%` followed by two hex digits must now be written with `%25`.
+- **A relative `WRITE ... TO` path after `CD`** lands in the new directory, as `EXPORT` output already did. Use an absolute path to keep writing to the directory execsql started in.
+- **A locked output file can delay the end of a run.** At the end of a script and before `SYSTEM_CMD`, the CLI waits up to `outfile_open_timeout` (default 600 s) for a `WRITE` / `EXPORT` file another process has locked; if it stays locked, the run fails naming the file and how many lines were lost. Lower `outfile_open_timeout` for unattended runs.
+- **Output that cannot be written fails the run.** When writing a `WRITE`, `EXPORT` or `TEE` file fails (a full disk, a network share that drops), its output is lost, other files are still written, and the run ends with an error naming the file: exit status 1, or `success=False` from `execsql.run()`. A target that can never be opened, such as a directory, fails at once.
+- **Error messages from the database or a driver** show just the error, such as `OperationalError: table t already exists`, without a path into execsql's source. `execsql.log` records where in execsql the error was raised, for bug reports.
+- **`execsql lint` on a script with block-structure errors** reports every unmatched or unclosed `IF`, `LOOP`, `BEGIN BATCH`, `BEGIN SCRIPT` and `BEGIN SQL` as a `P001` on its own line, and runs every other rule on the rest of the script.
+- **Faster start-up:** every `execsql` command and `import execsql` start about 0.7 s sooner.
+
+### Removed
+
+- **`execsql.utils.fileio` writer globals:** `filewriter`, `fw_input` and `fw_output` are gone, and `FileWriter` no longer takes queue arguments. Code that started a writer by hand before calling `execsql.run()` (the workaround for [#46](https://github.com/geocoug/execsql/issues/46) before 2.23.0) can drop it.
+
+### Fixed
+
+- **Output lost when a script halts is reported.** A `WRITE`, `TEE` or `ON ERROR_HALT WRITE` file still locked when the script halts gets up to 10 seconds; output still lost is reported on the console, in the log, in the `--manifest` file and in `execsql.run()`'s errors.
+- **SIGTERM** (`kill`, `timeout`, `docker stop`, a cancelled CI job) ends a `run` like Ctrl-C: the open transaction is rolled back, a running `SYSTEM_CMD` is stopped, and `execsql.log` gets an `exit` record of type `terminated` (exit status 143).
+- **`execsql.log` `exit` record** is written for a run that ends with an error, a `HALT` or a cancelled prompt (type `error` or `halt`, with the message). Ctrl-C is recorded as `interrupted`.
+- **`execsql.log` `run_db_file` record** names the database file for SQLite, DuckDB and Access runs.
+- **`execsql.log` no longer shows `-a` values** in the `run` record; it gives how many there were.
+- **Passwords in `execsql.log`** from a `--dsn` URL, the `[email]` section, the password prompt or keyring, `PROMPT ENTER_SUB ... PASSWORD`, `PROMPT CREDENTIALS` and `SUB_DECRYPT` are replaced with `***`, such as in SQL logged with `LOG_SQL ON` or a `SYSTEM_CMD` line.
+- **Stored passwords (keyring) are saved only after the connection succeeds**, so a mistyped password is no longer stored.
+- **A stored password is deleted, and you are prompted again, only when the server rejects it.** A timeout, a closed port or a missing database keeps it, so an unattended run no longer stops at a prompt.
+- **Keyring entries are named with the server's port** (`execsql/PostgreSQL/host:5432/db`), so two servers on one host no longer share a password. An entry stored without the port is still used on the default port, and renamed once it works.
+- **Oracle (`-t o`, `oracle://`) connects with the `oracledb` driver** that `execsql2[oracle]` installs.
+- **`-n` with `-e` on PostgreSQL** creates the database with the given encoding, as `CONNECT TO POSTGRESQL(..., ENCODING=..., NEW)` does. PostgreSQL refuses an encoding other than its template database's (usually UTF8), so `-n -e LATIN1` on such a server stops with PostgreSQL's error.
+- **`-d` / `--directories`** rejects a value other than `0`, `1`, `t`, `f`, `y` or `n` (exit 2), as upstream did, so `-d script.sql` names the bad value.
+- **`access_use_numeric`** (config section `input`) works again: with `Yes`, `IMPORT` and `COPY` create MS-Access decimal columns as `NUMERIC(precision,scale)` instead of `DOUBLE`.
+- **`IMPORT ... TO NEW` and `COPY ... TO NEW` onto a table that already exists** stop with `Table <name> already exists` before creating anything, on every DBMS. A name without a schema counts only in the schema the table would be created in (on MySQL, the current database).
+- **`IMPORT` / `COPY ... TO REPLACEMENT` of a table whose name needs quoting** (a space, a hyphen, ...) replaces it on SQLite, SQL Server, Oracle, Firebird and Access, and a schema-qualified name such as `staging.t` is dropped correctly on SQL Server, Oracle and Firebird.
+- **`COPY` and `COPY QUERY` copy text values as written:** a text column of `1`/`0`, dates or numbers is no longer created as boolean, timestamp or numeric by `NEW` / `REPLACEMENT`, and `1` copied into a text column stays `1`.
+- **`COPY ... TO NEW` / `REPLACEMENT` no longer holds every source row in memory.**
+- **`IMPORT` / `COPY` into DuckDB that fails part-way keeps no rows**, as on SQLite and PostgreSQL, so a re-run no longer duplicates them.
+- **`IMPORT` of a data line with fewer values than the header** loads the missing values as NULL on every DBMS.
+- **`IMPORT` of a delimited file with a blank line** imports the rows after it. The blank line itself is a row of NULLs, or dropped with `CONFIG EMPTY_ROWS NO`; blank lines at the end of the file are ignored.
+- **PostgreSQL `IMPORT` of a quoted file with a blank line** no longer fails with `missing data for column`.
+- **`IMPORT ... TO NEW` / `REPLACEMENT` type inference** no longer takes `1-2`, `5/6`, `March 5`, `Jan` or `Monday` for a date; such a column is created as text. A date must give the year (`2024-01-05`, `1/5/2024`), or a two-digit year month-first (`1/5/24`).
+- **`IMPORT ... TO NEW` / `REPLACEMENT` of a timestamp column mixing values with and without a UTC offset** creates the column as text and keeps every value as written, instead of converting with the importing machine's time zone.
+- **MySQL `IMPORT` of values with backslashes:** `C:\new\tbl`, `\N` and regular expressions load as written, and a file whose path contains a backslash imports.
+- **`EXPORT ... AS XLSX`** writes text that starts with `=` as text, not as a formula.
+- **`execsql.run()` from a script without an `if __name__ == "__main__":` guard** no longer runs the script's SQL twice on macOS and Windows.
+- **Concurrent `execsql.run()` calls** each write files through their own writer, so two threads both get complete output, and a run that halts does not discard another run's output.
+- **Repeated `execsql.run()` calls in one process** no longer pile up exit hooks or duplicate plugin metacommands.
+- **`execsql.run()` cleans up when it returns:** its temp files are removed, and a run interrupted with Ctrl-C closes the connection it opened.
+- **`execsql.run()` with `--manifest`** no longer records into a manifest that belongs to another run in the same thread.
+- **`execsql.run()` error details:** a run halted by a failed SQL statement or metacommand reports that error (and the failed statement in `ScriptError.sql`), a `HALT` reports its exit status, and `result.errors` lists errors in the order they happened.
+- **`execsql.run()` setup failures** (an unreadable script, a missing or invalid `config_file`, a `dsn` that cannot be parsed or opened) return `success=False` with an error whose `source` is the script, `<config>` or `<connect>`, instead of raising.
+- **`execsql lint` `V001` (`undefined-variable`)** no longer reports variables set by `PROMPT ENTER_SUB`, `ASK ... SUB`, `PROMPT ASK ... SUB`, `PROMPT OPENFILE` / `SAVEFILE` / `DIRECTORY SUB`, `PROMPT CREDENTIALS`, `SUB_TEMPFILE` and the keys of `SUB_QUERYSTRING`.
+- **`execsql lint` `V001`** reports a user variable named like a system variable without its `$` (`!!date_tag!!`), and a `SUB` variable written with a `$` (`!!$region!!`).
+- **`execsql lint` `V002` (`unused-variable`)** no longer reports a variable read only by `sub_defined(...)` or `sub_empty(...)`.
+- **`execsql lint` `F001`** no longer calls `IF(1=1)`, `IF(1=0)` or `IF(0=1)` a constant condition; `execsql run` rejects them, and lint reports them as `P004`.
+- **Install hints in error messages** name the right extra: `formats` for XLSX (not `excel`), and none for Textual, which execsql2 includes.
+- **Documentation:** install instructions use `uv tool install` / `pipx install` and quote every extra (`"execsql2[postgres]"`); `SERVE` and `allow_serve` are described correctly (`SERVE` opens no network port); the 2.17.0 `PG_UPSERT` migration note's `ASSERT !!$PG_UPSERT_QA_PASSED!! = TRUE`, which always fails, is corrected to `ASSERT IS_TRUE(!!$PG_UPSERT_QA_PASSED!!) "QA failed"`.
+
+______________________________________________________________________
+
 ## [2.24.0] - 2026-10-01
 
 ### Added
@@ -398,7 +474,7 @@ ______________________________________________________________________
 
 ### Changed
 
-- **Behavior change.** `PG_UPSERT`, `PG_UPSERT QA`, and `PG_UPSERT CHECK` no longer raise a metacommand error when QA checks fail. The outcome is reported via `$PG_UPSERT_QA_PASSED`, `$PG_UPSERT_TABLE_QA_PASSED`, and `$PG_UPSERT_RESULT_JSON`, so the script controls flow with `IF` or `ASSERT`. `EXPORT_FAILURES` still runs and the upsert is still skipped on QA failure. Migration: add `ASSERT !!$PG_UPSERT_QA_PASSED!! = TRUE` at the call site to preserve the previous halt-on-failure behavior.
+- **Behavior change.** `PG_UPSERT`, `PG_UPSERT QA`, and `PG_UPSERT CHECK` no longer raise a metacommand error when QA checks fail. The outcome is reported via `$PG_UPSERT_QA_PASSED`, `$PG_UPSERT_TABLE_QA_PASSED`, and `$PG_UPSERT_RESULT_JSON`, so the script controls flow with `IF` or `ASSERT`. `EXPORT_FAILURES` still runs and the upsert is still skipped on QA failure. Migration: add `ASSERT IS_TRUE(!!$PG_UPSERT_QA_PASSED!!) "QA failed"` at the call site to preserve the previous halt-on-failure behavior. (Corrected after release: this note first gave an `=` comparison, which is not a valid condition and fails on every run.)
 
 ### Fixed
 

{execsql2-2.24.0 → execsql2-2.25.1}/CONTRIBUTING.md

@@ -98,6 +98,10 @@ git push origin <branch> --follow-tags
 
 Pre-releases are published to PyPI but are not installed by default — `pip install execsql2` will not pick them up unless `--pre` is passed.
 
+The GitHub Release for a pre-release tag is marked as a pre-release. Promote to the final version with the same recipe and the final version string (`just bump-pre 2.0.0`). `just bump-patch` from `2.0.0rc1` would skip ahead to `2.0.1`.
+
+Always preview a bump first: `uv run bump-my-version bump --new-version 2.0.0a1 patch --dry-run -v` should print `New version will be '2.0.0a1'`.
+
 ### CI/CD pipeline (`ci-cd.yml`)
 
 Triggered on pushes to `main`, any `v*.*.*` tag, and pull requests.

{execsql2-2.24.0 → execsql2-2.25.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execsql2
-Version: 2.24.0
+Version: 2.25.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
@@ -161,7 +161,7 @@ Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), whic
 | Command                                    | What it does                                                            | Needs a database? |
 | ------------------------------------------ | ----------------------------------------------------------------------- | ----------------- |
 | `execsql format`                           | Normalize keywords, indentation, and SQL layout                         | No                |
-| `execsql lint`                             | Static analysis: structure, undefined variables, bad targets            | No                |
+| `execsql lint`                             | Static analysis: structure, unknown metacommands, variables, targets    | No                |
 | `execsql run`                              | Run the script against PostgreSQL, MySQL, SQLite, DuckDB, …             | Yes               |
 | `execsql config`                           | Show every config option, its value, and the file that set it           | No                |
 | `execsql list`                             | Metacommands, encodings, plugins, or the keyword vocabulary             | No                |
@@ -180,14 +180,14 @@ Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), whic
 `format` and `lint` work on a bare `.sql` file, with no server and no config. Try them first:
 
 ```bash
-pip install execsql2[formatter]
+uv tool install "execsql2[formatter]"     # or: pipx install "execsql2[formatter]"
 
 execsql format --check scripts/   # is it formatted?
 execsql format -i scripts/        # format it
 execsql lint scripts/             # find problems before they cost you a run
 ```
 
-`lint` reports unmatched blocks, undefined and unused substitution variables, unreachable branches, and `INCLUDE`/`SCRIPT` targets that do not exist: the failures that otherwise surface halfway through a run against a live database:
+`lint` reports unmatched blocks, misspelled or malformed metacommands and conditions, undefined and unused substitution variables, unreachable branches, and `INCLUDE`/`SCRIPT` targets that do not exist: the failures that otherwise surface halfway through a run against a live database:
 
 ```text
 $ execsql lint load_data.sql
@@ -244,11 +244,16 @@ The `PROMPT` metacommand produces a GUI display of the data:
 ## Installation
 
 ```bash
-pip install execsql2                # core: SQLite works with no extras
-pip install "execsql2[postgres]"    # add a driver: postgres, mysql, mssql, duckdb, firebird, oracle, odbc
-pip install "execsql2[all]"         # everything: all drivers plus all feature extras
+uv tool install execsql2                  # core: SQLite works with no extras
+uv tool install "execsql2[postgres]"      # with a driver: postgres, mysql, mssql, duckdb, firebird, oracle, odbc
+uv tool install "execsql2[all]"           # everything: all drivers plus all feature extras
 ```
 
+`pipx install` takes the same arguments. Quote the name when it has extras
+(zsh reports `no matches found` otherwise). To call execsql from Python code,
+add it to that project instead: `uv add "execsql2[postgres]"` or
+`pip install "execsql2[postgres]"` in its virtual environment.
+
 Feature extras cover spreadsheet and Parquet/Feather formats, keyring authentication, PostgreSQL upsert, and more. See the [installation guide](https://execsql2.readthedocs.io/en/latest/getting-started/installation/) for the full list.
 
 ## Usage
@@ -309,7 +314,7 @@ silences.
 | `-c SCRIPT`                                       | Execute inline SQL or metacommand string                                   |
 | `-a VALUE`                                        | Set substitution variable `$ARG_x`                                         |
 | `--var NAME=VALUE`                                | Set the substitution variable `!!NAME!!`                                   |
-| `-v {0,1,2,3}`                                    | GUI level (0=none, 1=password, 2=selection, 3=full)                        |
+| `-v {0,1,2,3}`                                    | GUI level (0=none, 1=password/PAUSE, 2=+HALT and DB selection, 3=console)  |
 | `--config FILE`                                   | Load an explicit config file                                               |
 | `--dry-run`                                       | Parse the script and report commands without executing                     |
 | `--manifest FILE`                                 | Write a JSON record of the run: files read and written, statements, errors |
@@ -360,7 +365,8 @@ result = run(
     new_db=True,
 )
 
-# With substitution variables
+# With substitution variables: each key becomes a $ variable,
+# so the script refers to these as !!$SCHEMA!! and !!$DATE!!
 result = run(
     script="etl.sql",
     dsn="sqlite:///data.db",
@@ -371,7 +377,7 @@ result = run(
 print(result.success)       # True
 print(result.commands_run)  # 2
 print(result.elapsed)       # 0.003 (seconds)
-print(result.variables)     # {"SCHEMA": "public", ...}
+print(result.variables)     # {"schema": "public", ...} (names lower-cased, no $)
 ```
 
 Error handling:
@@ -428,7 +434,7 @@ The `execsql format` command normalizes execsql script files: it uppercases meta
 
 ```bash
 # Install with the SQL-reformatting extra
-pip install execsql2[formatter]
+uv tool install "execsql2[formatter]"
 
 # Format files in place
 execsql format --in-place scripts/
@@ -445,7 +451,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.24.0
+    rev: v2.25.1
     hooks:
       - id: execsql-format
       - id: execsql-lint

{execsql2-2.24.0 → execsql2-2.25.1}/README.md

@@ -30,7 +30,7 @@ Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), whic
 | Command                                    | What it does                                                            | Needs a database? |
 | ------------------------------------------ | ----------------------------------------------------------------------- | ----------------- |
 | `execsql format`                           | Normalize keywords, indentation, and SQL layout                         | No                |
-| `execsql lint`                             | Static analysis: structure, undefined variables, bad targets            | No                |
+| `execsql lint`                             | Static analysis: structure, unknown metacommands, variables, targets    | No                |
 | `execsql run`                              | Run the script against PostgreSQL, MySQL, SQLite, DuckDB, …             | Yes               |
 | `execsql config`                           | Show every config option, its value, and the file that set it           | No                |
 | `execsql list`                             | Metacommands, encodings, plugins, or the keyword vocabulary             | No                |
@@ -49,14 +49,14 @@ Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), whic
 `format` and `lint` work on a bare `.sql` file, with no server and no config. Try them first:
 
 ```bash
-pip install execsql2[formatter]
+uv tool install "execsql2[formatter]"     # or: pipx install "execsql2[formatter]"
 
 execsql format --check scripts/   # is it formatted?
 execsql format -i scripts/        # format it
 execsql lint scripts/             # find problems before they cost you a run
 ```
 
-`lint` reports unmatched blocks, undefined and unused substitution variables, unreachable branches, and `INCLUDE`/`SCRIPT` targets that do not exist: the failures that otherwise surface halfway through a run against a live database:
+`lint` reports unmatched blocks, misspelled or malformed metacommands and conditions, undefined and unused substitution variables, unreachable branches, and `INCLUDE`/`SCRIPT` targets that do not exist: the failures that otherwise surface halfway through a run against a live database:
 
 ```text
 $ execsql lint load_data.sql
@@ -113,11 +113,16 @@ The `PROMPT` metacommand produces a GUI display of the data:
 ## Installation
 
 ```bash
-pip install execsql2                # core: SQLite works with no extras
-pip install "execsql2[postgres]"    # add a driver: postgres, mysql, mssql, duckdb, firebird, oracle, odbc
-pip install "execsql2[all]"         # everything: all drivers plus all feature extras
+uv tool install execsql2                  # core: SQLite works with no extras
+uv tool install "execsql2[postgres]"      # with a driver: postgres, mysql, mssql, duckdb, firebird, oracle, odbc
+uv tool install "execsql2[all]"           # everything: all drivers plus all feature extras
 ```
 
+`pipx install` takes the same arguments. Quote the name when it has extras
+(zsh reports `no matches found` otherwise). To call execsql from Python code,
+add it to that project instead: `uv add "execsql2[postgres]"` or
+`pip install "execsql2[postgres]"` in its virtual environment.
+
 Feature extras cover spreadsheet and Parquet/Feather formats, keyring authentication, PostgreSQL upsert, and more. See the [installation guide](https://execsql2.readthedocs.io/en/latest/getting-started/installation/) for the full list.
 
 ## Usage
@@ -178,7 +183,7 @@ silences.
 | `-c SCRIPT`                                       | Execute inline SQL or metacommand string                                   |
 | `-a VALUE`                                        | Set substitution variable `$ARG_x`                                         |
 | `--var NAME=VALUE`                                | Set the substitution variable `!!NAME!!`                                   |
-| `-v {0,1,2,3}`                                    | GUI level (0=none, 1=password, 2=selection, 3=full)                        |
+| `-v {0,1,2,3}`                                    | GUI level (0=none, 1=password/PAUSE, 2=+HALT and DB selection, 3=console)  |
 | `--config FILE`                                   | Load an explicit config file                                               |
 | `--dry-run`                                       | Parse the script and report commands without executing                     |
 | `--manifest FILE`                                 | Write a JSON record of the run: files read and written, statements, errors |
@@ -229,7 +234,8 @@ result = run(
     new_db=True,
 )
 
-# With substitution variables
+# With substitution variables: each key becomes a $ variable,
+# so the script refers to these as !!$SCHEMA!! and !!$DATE!!
 result = run(
     script="etl.sql",
     dsn="sqlite:///data.db",
@@ -240,7 +246,7 @@ result = run(
 print(result.success)       # True
 print(result.commands_run)  # 2
 print(result.elapsed)       # 0.003 (seconds)
-print(result.variables)     # {"SCHEMA": "public", ...}
+print(result.variables)     # {"schema": "public", ...} (names lower-cased, no $)
 ```
 
 Error handling:
@@ -297,7 +303,7 @@ The `execsql format` command normalizes execsql script files: it uppercases meta
 
 ```bash
 # Install with the SQL-reformatting extra
-pip install execsql2[formatter]
+uv tool install "execsql2[formatter]"
 
 # Format files in place
 execsql format --in-place scripts/
@@ -314,7 +320,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.24.0
+    rev: v2.25.1
     hooks:
       - id: execsql-format
       - id: execsql-lint