execsql2 2.19.2__tar.gz → 2.21.0__tar.gz

{execsql2-2.19.2 → execsql2-2.21.0}/.github/workflows/ci-cd.yml

@@ -20,7 +20,7 @@ jobs:
         permissions:
             contents: read
         steps:
-            - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+            - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
             - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
               with:
                   python-version: "3.13"
@@ -48,7 +48,7 @@ jobs:
             contents: read
         steps:
             - name: Check out repository code
-              uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+              uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
             - name: Setup Python ${{ matrix.python-version }}
               uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
               with:
@@ -86,7 +86,7 @@ jobs:
                   tox -e py
             - name: Upload coverage to Codecov
               if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
-              uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354  # v6.0.1
+              uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v7.0.0
               with:
                   token: ${{ secrets.CODECOV_TOKEN }}
                   files: coverage.xml
@@ -139,7 +139,7 @@ jobs:
                     --health-interval 10s --health-timeout 5s --health-retries 20
         steps:
             - name: Check out repository code
-              uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+              uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
             - name: Setup Python ${{ matrix.python-version }}
               uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
               with:
@@ -167,7 +167,7 @@ jobs:
               run: |
                   python -m pytest --cov=execsql --cov-branch --cov-report=xml --cov-fail-under=86
             - name: Upload coverage to Codecov
-              uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354  # v6.0.1
+              uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v7.0.0
               with:
                   token: ${{ secrets.CODECOV_TOKEN }}
                   files: coverage.xml
@@ -175,9 +175,10 @@ jobs:
     access-tests-windows:
         name: access-tests-windows
         runs-on: windows-latest
-        # Best-effort: Access Database Engine install can be flaky on hosted
-        # runners.  Failures don't gate the rest of the pipeline.
-        continue-on-error: true
+        # The Access engine install step is best-effort (the redistributable
+        # download from Microsoft can be flaky on hosted runners). The
+        # downstream test step IS gating — a real Access regression should
+        # block the merge.
         strategy:
             fail-fast: false
             matrix:
@@ -186,11 +187,13 @@ jobs:
         permissions:
             contents: read
         steps:
-            - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+            - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
             - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
               with:
                   python-version: ${{ matrix.python-version }}
             - name: Install Microsoft Access Database Engine 2016 (x64)
+              id: install_access
+              continue-on-error: true
               # The chocolatey `accessdatabaseengine-x64` package was removed
               # from the community feed; download the redistributable directly
               # from Microsoft and run it silently instead.
@@ -206,12 +209,21 @@ jobs:
                   # 0 = success, 3010 = success but reboot pending. Anything else is a failure.
                   if ($proc.ExitCode -ne 0 -and $proc.ExitCode -ne 3010) { exit $proc.ExitCode }
               shell: pwsh
+            - name: Annotate skipped Access tests
+              if: steps.install_access.outcome != 'success'
+              run: |
+                  Write-Host "::warning::Access Database Engine install failed; Access real-driver tests skipped this run."
+              shell: pwsh
             - name: Install Python dependencies
+              if: steps.install_access.outcome == 'success'
               run: |
                   python -m pip install --upgrade pip
                   python -m pip install ".[dev,odbc]" pywin32
               shell: pwsh
             - name: Run Access real-driver tests
+              # Gating: a real regression in src/execsql/db/access.py blocks
+              # the merge. Only runs when the install above succeeded.
+              if: steps.install_access.outcome == 'success'
               env:
                   DISPLAY: ""
               run: |
@@ -226,7 +238,7 @@ jobs:
         permissions:
             contents: read
         steps:
-            - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+            - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
             - name: Set up Python
               uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
               with:
@@ -276,7 +288,7 @@ jobs:
             contents: write
         steps:
             - name: Checkout
-              uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+              uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
             - name: Download dist
               uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
               with:

{execsql2-2.19.2 → execsql2-2.21.0}/.pre-commit-hooks.yaml

@@ -5,4 +5,5 @@
   language: python
   types: [file]
   files: \.sql$
+  args: [--in-place]
   additional_dependencies: [sqlglot]

{execsql2-2.19.2 → execsql2-2.21.0}/.readthedocs.yaml

@@ -9,7 +9,7 @@ build:
     python: "3.13"
   jobs:
     install:
-      - pip install zensical mkdocstrings-python
+      - pip install "zensical==0.0.28" mkdocstrings-python
       - pip install -e .
     pre_build:
       - cp CHANGELOG.md docs/about/change_log.md

{execsql2-2.19.2 → execsql2-2.21.0}/CHANGELOG.md

@@ -13,11 +13,44 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.21.0] - 2026-06-24
+
+### Changed
+
+- PostgreSQL connections now use psycopg3 (install the `postgres` extra, which pulls `psycopg[binary]`) instead of psycopg2. The `PG_UPSERT` metacommand now requires `pg-upsert>=1.23.0`.
+
+______________________________________________________________________
+
+## [2.20.0] - 2026-06-11
+
+### Added
+
+- `execsql-format --encoding NAME` flag controls the text encoding used to read and write SQL files (default `utf-8`). Files saved by editors that emit cp1252, latin-1, shift_jis, etc. can now be formatted directly. A `UnicodeDecodeError` reports the file path and suggests `--encoding` instead of dumping a traceback.
+
+### Changed
+
+- Published `execsql-format` pre-commit hook now defaults to `args: [--in-place]`. Downstream configs that listed `- id: execsql-format` with no `args:` previously got a silent no-op (the CLI's default is stdout, which pre-commit doesn't capture); they will now reformat files in place. Override with `args: [--check]` for check-only mode.
+- Pre-commit `rev:` snippets in `README.md` and `docs/guides/formatter.md` now point at `v2.19.2` and are rewritten automatically by `bump-my-version` on every version bump, so they cannot drift.
+- Env-var redaction filter expanded to skip mainstream secret-naming conventions (`AWS_ACCESS_KEY_ID`, `STRIPE_KEY`, `OPENAI_API_KEY`, `SENTRY_DSN`, `SLACK_WEBHOOK`, etc.). `-a` assignment log lines now always show `{***}` instead of the raw value. See `docs/reference/security.md#env_redaction` for the full list and known gaps (`DATABASE_URL`, `GITHUB_PAT`).
+- The duplicate `execsql.conf` reference file shipped at `<sys.prefix>/execsql2_extras/execsql.conf` has been removed. The canonical template still ships inside the package and is loaded via `importlib.resources`; bootstrap a project conf with `execsql --init-config > execsql.conf` (the documented path).
+
+### Fixed
+
+- `[firebird]` extra now connects: the adapter imports `firebird.driver` (provided by `firebird-driver`) instead of the missing `fdb` module. Users who installed `pip install execsql2[firebird]` previously hit `ModuleNotFoundError: No module named 'fdb'` at connect time.
+- MySQL, SQL Server (pyodbc), MS Access (pyodbc), DSN (pyodbc), Firebird, and SMTP connections now use a 30-second connect timeout, matching the existing Postgres default. A silently-dropped peer no longer hangs a script (or a CI run) indefinitely.
+- `execsql-format` now recognizes tagged `$body$ … $body$` / `$func$ … $func$` PL/pgSQL dollar quotes and skips sqlglot inside them, matching the existing `$$` behaviour. Tagged function bodies previously had their `IF / END IF / LOOP / RETURN` rewritten or collapsed.
+- `execsql-format` now uppercases the second word of multi-word metacommands like `PROMPT MAP`, `PROMPT SAVEFILE`, `PROMPT OPENFILE`, `PROMPT CREDENTIALS`, `PROMPT SELECT_ROWS`, `PROMPT ASK COMPARE`, `APPEND SCRIPT`, `PG_UPSERT CHECK`/`QA`, `RESET COUNTER`/`DIALOG_CANCELED`, `SET COUNTER`, `WRITE CREATE_TABLE`/`SCRIPT`. Previously only the first word was uppercased, leaving the rest as the user typed.
+- `execsql-format` no longer short-circuits on the first unreadable file; remaining files are still checked or formatted, and the run exits 1 at the end if any read error or pending change was found.
+- `execsql-format --leading-comma` is now idempotent on SQL with mid-statement comments. The flag is no longer threaded through to sqlglot (which migrates inline `/* marker */` comments between passes); instead the formatter normalizes any leading-comma input to trailing-comma before sqlglot sees it, and applies leading commas as a textual post-pass on the assembled output.
+
+______________________________________________________________________
+
 ## [2.19.2] - 2026-06-03
 
 ### Fixed
 
-- `pre-commit` hook `execsql-format` now installs `sqlglot` into its isolated env. Since 2.19.0 moved `sqlglot` to the `[formatter]` extra, the hook env (which installs the bare package) was missing it and crashed with `ModuleNotFoundError: No module named 'sqlglot'`. Re-run `pre-commit clean && pre-commit install --install-hooks` after upgrading to pick up the new dependency.
+- `pre-commit` hook `execsql-format` now installs `sqlglot` into its isolated env (previously crashed with `ModuleNotFoundError: No module named 'sqlglot'`).
+- After upgrading, re-run `pre-commit clean && pre-commit install --install-hooks` to rebuild the hook env.
 
 ______________________________________________________________________
 
@@ -49,13 +82,7 @@ ______________________________________________________________________
 
 ## [2.18.1] - 2026-05-28
 
-### Changed
-
-- Internal: `execsql.cli.lint_ast` has been folded into `execsql.cli.lint`; the AST walker entry point is now `execsql.cli.lint.lint()`. Code that imported `execsql.cli.lint_ast.lint_ast` should import `execsql.cli.lint.lint` instead.
-
-### Removed
-
-- Internal: the unused `run_when_false` and `run_in_batch` flags on `MetaCommand` (and the matching keyword arguments on `MetaCommandList.add()`) — neither has been consulted since v2.16.0. Code that still passes either kwarg to `mcl.add()` will raise `TypeError`.
+- Internal: `execsql.cli.lint_ast` is now `execsql.cli.lint.lint`; deprecated `MetaCommand.run_when_false` / `run_in_batch` kwargs removed.
 
 ______________________________________________________________________
 

{execsql2-2.19.2 → execsql2-2.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.19.2
+Version: 2.21.0
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Homepage, https://execsql2.readthedocs.io
 Project-URL: Repository, https://github.com/geocoug/execsql
@@ -44,90 +44,89 @@ Requires-Dist: rich>=13.0
 Requires-Dist: textual>=1.0
 Requires-Dist: typer>=0.12
 Provides-Extra: all
-Requires-Dist: defusedxml; extra == 'all'
-Requires-Dist: duckdb; extra == 'all'
-Requires-Dist: firebird-driver; extra == 'all'
-Requires-Dist: jinja2; extra == 'all'
-Requires-Dist: keyring; extra == 'all'
-Requires-Dist: odfpy; extra == 'all'
-Requires-Dist: openpyxl; extra == 'all'
-Requires-Dist: oracledb; extra == 'all'
-Requires-Dist: pg-upsert>=1.22.1; extra == 'all'
-Requires-Dist: polars; extra == 'all'
-Requires-Dist: psycopg2-binary; extra == 'all'
-Requires-Dist: pymysql; extra == 'all'
-Requires-Dist: pyodbc; extra == 'all'
-Requires-Dist: pyyaml; extra == 'all'
+Requires-Dist: defusedxml>=0.7; extra == 'all'
+Requires-Dist: duckdb>=1.0; extra == 'all'
+Requires-Dist: firebird-driver>=1.10; extra == 'all'
+Requires-Dist: jinja2>=3.1; extra == 'all'
+Requires-Dist: keyring>=25.0; extra == 'all'
+Requires-Dist: odfpy>=1.4; extra == 'all'
+Requires-Dist: openpyxl>=3.1; extra == 'all'
+Requires-Dist: oracledb>=3.0; extra == 'all'
+Requires-Dist: pg-upsert>=1.23.0; extra == 'all'
+Requires-Dist: polars>=1.0; extra == 'all'
+Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'all'
+Requires-Dist: pymysql>=1.1; extra == 'all'
+Requires-Dist: pyodbc>=5.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
 Requires-Dist: sqlglot>=25.0; extra == 'all'
-Requires-Dist: tables; extra == 'all'
+Requires-Dist: tables>=3.10; extra == 'all'
 Requires-Dist: tkintermapview>=1.29; extra == 'all'
-Requires-Dist: xlrd; extra == 'all'
+Requires-Dist: xlrd>=2.0; extra == 'all'
 Provides-Extra: all-db
-Requires-Dist: duckdb; extra == 'all-db'
-Requires-Dist: firebird-driver; extra == 'all-db'
-Requires-Dist: oracledb; extra == 'all-db'
-Requires-Dist: psycopg2-binary; extra == 'all-db'
-Requires-Dist: pymysql; extra == 'all-db'
-Requires-Dist: pyodbc; extra == 'all-db'
+Requires-Dist: duckdb>=1.0; extra == 'all-db'
+Requires-Dist: firebird-driver>=1.10; extra == 'all-db'
+Requires-Dist: oracledb>=3.0; extra == 'all-db'
+Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'all-db'
+Requires-Dist: pymysql>=1.1; extra == 'all-db'
+Requires-Dist: pyodbc>=5.0; extra == 'all-db'
 Provides-Extra: auth
-Requires-Dist: keyring; extra == 'auth'
+Requires-Dist: keyring>=25.0; extra == 'auth'
 Provides-Extra: auth-encrypted
-Requires-Dist: keyring; extra == 'auth-encrypted'
-Requires-Dist: keyrings-alt; extra == 'auth-encrypted'
-Requires-Dist: pycryptodome; extra == 'auth-encrypted'
+Requires-Dist: keyring>=25.0; extra == 'auth-encrypted'
+Requires-Dist: keyrings-alt>=5.0; extra == 'auth-encrypted'
+Requires-Dist: pycryptodome>=3.20; extra == 'auth-encrypted'
 Provides-Extra: auth-plaintext
-Requires-Dist: keyring; extra == 'auth-plaintext'
-Requires-Dist: keyrings-alt; extra == 'auth-plaintext'
+Requires-Dist: keyring>=25.0; extra == 'auth-plaintext'
+Requires-Dist: keyrings-alt>=5.0; extra == 'auth-plaintext'
 Provides-Extra: dev
 Requires-Dist: build>=1.2.2.post1; extra == 'dev'
 Requires-Dist: bump-my-version>=1.2.7; extra == 'dev'
-Requires-Dist: defusedxml; extra == 'dev'
-Requires-Dist: jinja2; extra == 'dev'
-Requires-Dist: markdown-include>=0.8; extra == 'dev'
+Requires-Dist: defusedxml>=0.7; extra == 'dev'
+Requires-Dist: jinja2>=3.1; extra == 'dev'
 Requires-Dist: mkdocstrings-python>=2.0.3; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: odfpy; extra == 'dev'
-Requires-Dist: openpyxl; extra == 'dev'
-Requires-Dist: polars; extra == 'dev'
+Requires-Dist: odfpy>=1.4; extra == 'dev'
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: polars>=1.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
-Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: sqlglot>=25.0; extra == 'dev'
-Requires-Dist: tables; extra == 'dev'
+Requires-Dist: tables>=3.10; extra == 'dev'
 Requires-Dist: tox-uv>=1.13.1; extra == 'dev'
 Requires-Dist: twine>=6.1.0; extra == 'dev'
-Requires-Dist: xlrd; extra == 'dev'
-Requires-Dist: zensical>=0.0.28; extra == 'dev'
+Requires-Dist: xlrd>=2.0; extra == 'dev'
+Requires-Dist: zensical==0.0.28; extra == 'dev'
 Provides-Extra: duckdb
-Requires-Dist: duckdb; extra == 'duckdb'
+Requires-Dist: duckdb>=1.0; extra == 'duckdb'
 Provides-Extra: firebird
-Requires-Dist: firebird-driver; extra == 'firebird'
+Requires-Dist: firebird-driver>=1.10; extra == 'firebird'
 Provides-Extra: formats
-Requires-Dist: defusedxml; extra == 'formats'
-Requires-Dist: jinja2; extra == 'formats'
-Requires-Dist: odfpy; extra == 'formats'
-Requires-Dist: openpyxl; extra == 'formats'
-Requires-Dist: polars; extra == 'formats'
-Requires-Dist: pyyaml; extra == 'formats'
-Requires-Dist: tables; extra == 'formats'
-Requires-Dist: xlrd; extra == 'formats'
+Requires-Dist: defusedxml>=0.7; extra == 'formats'
+Requires-Dist: jinja2>=3.1; extra == 'formats'
+Requires-Dist: odfpy>=1.4; extra == 'formats'
+Requires-Dist: openpyxl>=3.1; extra == 'formats'
+Requires-Dist: polars>=1.0; extra == 'formats'
+Requires-Dist: pyyaml>=6.0; extra == 'formats'
+Requires-Dist: tables>=3.10; extra == 'formats'
+Requires-Dist: xlrd>=2.0; extra == 'formats'
 Provides-Extra: formatter
 Requires-Dist: sqlglot>=25.0; extra == 'formatter'
 Provides-Extra: map
 Requires-Dist: tkintermapview>=1.29; extra == 'map'
 Provides-Extra: mssql
-Requires-Dist: pyodbc; extra == 'mssql'
+Requires-Dist: pyodbc>=5.0; extra == 'mssql'
 Provides-Extra: mysql
-Requires-Dist: pymysql; extra == 'mysql'
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
 Provides-Extra: odbc
-Requires-Dist: pyodbc; extra == 'odbc'
+Requires-Dist: pyodbc>=5.0; extra == 'odbc'
 Provides-Extra: oracle
-Requires-Dist: oracledb; extra == 'oracle'
+Requires-Dist: oracledb>=3.0; extra == 'oracle'
 Provides-Extra: postgres
-Requires-Dist: psycopg2-binary; extra == 'postgres'
+Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'postgres'
 Provides-Extra: upsert
-Requires-Dist: pg-upsert>=1.22.1; extra == 'upsert'
+Requires-Dist: pg-upsert>=1.23.0; extra == 'upsert'
 Description-Content-Type: text/markdown
 
 > [!NOTE]
@@ -404,13 +403,12 @@ execsql-format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.18.0
+    rev: v2.21.0
     hooks:
       - id: execsql-format
-        args: [--in-place]
 ```
 
-See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/guides/formatter/) for all options.
+The hook rewrites `*.sql` files in place by default. See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/guides/formatter/) for `--check`, `--indent`, and other options.
 
 # VS Code Syntax Highlighting
 

{execsql2-2.19.2 → execsql2-2.21.0}/README.md

@@ -272,13 +272,12 @@ execsql-format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.18.0
+    rev: v2.21.0
     hooks:
       - id: execsql-format
-        args: [--in-place]
 ```
 
-See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/guides/formatter/) for all options.
+The hook rewrites `*.sql` files in place by default. See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/guides/formatter/) for `--check`, `--indent`, and other options.
 
 # VS Code Syntax Highlighting
 

{execsql2-2.19.2 → execsql2-2.21.0}/docs/about/divergence.md

@@ -102,9 +102,15 @@ New options in `execsql.conf`:
 
 ### Tools
 
-| Tool             | Description                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `execsql-format` | Standalone CLI for normalizing metacommand indentation and uppercasing SQL keywords. Supports `--check`, `--in-place`, `--indent N` (controls both metacommand and SQL indentation), and `--leading-comma` (commas at start of lines) modes. Also available as a [pre-commit hook](../guides/formatter.md). SQL reformatting (the optional sqlglot pass) requires the `[formatter]` extra as of 2.19.0; `--no-sql` works without it. |
+| Tool             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `execsql-format` | Standalone CLI for normalizing metacommand indentation and uppercasing SQL keywords. Supports `--check`, `--in-place`, `--indent N` (controls both metacommand and SQL indentation), and `--leading-comma` (commas at start of lines) modes. Also available as a [pre-commit hook](../guides/formatter.md) — the published hook defaults to `args: [--in-place]` so downstream consumers get formatting on commit without extra wiring. SQL reformatting (the optional sqlglot pass) requires the `[formatter]` extra as of 2.19.0; `--no-sql` works without it. |
+
+Formatter correctness notes added in the 2.19.x line:
+
+- **2.19.1** — All four substitution-variable forms (`!!var!!`, `!'!var!'!`, `!"!var!"!`, and the deferred form `!{var}!`) are hidden from the sqlglot pass. Previously, `!'!var!'!` and `!"!var!"!` were parsed as `NOT` operators and rewritten — e.g. `!'!myvar!'!` → `NOT NOT '!myvar!'`. Scripts using quoted substitution variables are now safe to run through `execsql-format`.
+- **2.19.2** — The published pre-commit hook declares `sqlglot` as an isolated-env dependency. The 2.19.0 move of `sqlglot` to the `[formatter]` extra meant the hook env (which installs the bare package) crashed with `ModuleNotFoundError: No module named 'sqlglot'` on first run. After upgrading, downstream users should run `pre-commit clean && pre-commit install --install-hooks` once to rebuild the env.
+- **Tagged dollar quotes** — Tagged PL/pgSQL function bodies (`$body$ … $body$`, `$func$ … $func$`, any `$tag$`) are now recognized and skipped over by the formatter. Previously the tracker only saw untagged `$$`, so tagged function bodies were sent to sqlglot which mangled `IF / END IF / LOOP / RETURN`.
 
 ### GUI
 
@@ -204,6 +210,7 @@ All 33 mutable runtime globals in `state.py` have been consolidated into a `Runt
 
 ### Database Adapters
 
+- **PostgreSQL driver is psycopg3** — the PostgreSQL adapter uses `psycopg` (psycopg3, installed via the `psycopg[binary]` extra) instead of upstream's `psycopg2`. The connection now passes the libpq `dbname` keyword (psycopg3 rejects psycopg2's `database`), `VACUUM` toggles `conn.autocommit` instead of the removed `set_session()`, server-side `COPY` import uses psycopg3's `cursor.copy()` context manager instead of `copy_expert()`, and binary `IMPORT` sends raw `bytes` instead of `psycopg2.Binary()`. This also makes `db.conn` directly usable by the `PG_UPSERT` metacommand's pg-upsert ≥1.23.0 dependency, which itself requires a psycopg3 connection.
 - **`Database` is an ABC** — `open_db()` and `exec_cmd()` are abstract methods. Subclasses that omit them raise `TypeError` at instantiation instead of at call time.
 - **Connection timeouts** — PostgreSQL and SQLite adapters accept a connection timeout parameter (default 30 seconds).
 - **DuckDB temporal types** — `TIMESTAMPTZ`, `TIMESTAMP`, `DATE`, `TIME` now map to native DuckDB types instead of `TEXT`.
@@ -256,10 +263,11 @@ These are behavioral changes driven by security or correctness issues in the ups
 
 ### Credential and Logging Safety
 
-| Area                         | Fix                                                                                        |
-| ---------------------------- | ------------------------------------------------------------------------------------------ |
-| ODBC password redaction      | Connection strings in log output have `Pwd=***` substituted before logging.                |
-| `enc_password` documentation | Prominent warnings that XOR encryption is obfuscation only — keys are hardcoded in source. |
+| Area                         | Fix                                                                                                                                                                                                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ODBC password redaction      | Connection strings in log output have `Pwd=***` substituted before logging.                                                                                                                                                                                  |
+| `enc_password` documentation | Prominent warnings that XOR encryption is obfuscation only — keys are hardcoded in source.                                                                                                                                                                   |
+| Env-var secret denylist      | Extended `_SENSITIVE_SUBSTRINGS` to cover mainstream cloud / payment / observability / VCS conventions (`*_KEY`, `APIKEY`, `API_KEY`, `DSN`, `WEBHOOK`). `-a` positional assignment log lines now redact unconditionally (`{***}` instead of the raw value). |
 
 ### Bug Fixes
 
@@ -297,6 +305,8 @@ These are behavioral changes driven by security or correctness issues in the ups
 | Temp file creation TOCTOU race                      | `TempFileMgr.new_temp_fn()` discarded the `NamedTemporaryFile` handle, creating a race window. Now uses `tempfile.mkstemp()` for secure creation.                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `shlex.split` on Windows incorrect mode             | Called without `posix=False` on Windows, mishandling backslash-heavy paths in SHELL commands.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | AST executor `~`/`+` variable scoping broken        | The AST executor passed `localvars` through function parameters but never pushed `CommandList` frames onto `commandliststack`. Legacy metacommand handlers (`x_sub`, `x_rm_sub`, `xf_sub_defined`, `SUB_LOCAL`, prompt handlers, REPL) access `commandliststack[-1]` for `~` local and `+` outer-scope variables. This caused `~` vars to be invisible to SQL, `SUB_DEFINED(~var)` to always return false, and the REPL `.vars`/`.stack` to show empty state. Fixed by pushing/popping `CommandList` frames in `execute()` and `_execute_script_native()`. |
+| Firebird adapter import                             | Adapter imported `fdb` (the unmaintained legacy driver) while the `[firebird]` extra declared `firebird-driver`. `pip install execsql2[firebird]` followed by a Firebird connect raised `ModuleNotFoundError: No module named 'fdb'`. Adapter now imports `firebird.driver`, matching the declared dependency.                                                                                                                                                                                                                                             |
+| Connect timeouts on network adapters                | MySQL, SQL Server / Access / DSN (pyodbc), Firebird, and SMTP all now apply a 30 s connect timeout matching the existing PostgreSQL default. A silently-dropped network peer (firewall rule, dead VM) used to hang scripts indefinitely; now the connect fails fast.                                                                                                                                                                                                                                                                                       |
 | AST parser INCLUDE quoted paths broken              | The AST parser captured the full INCLUDE target including surrounding quotes (`"path"`), but the legacy dispatch regex stripped them. Quoted INCLUDE paths failed with "File does not exist" even when the file was present. Fixed by stripping matched quote pairs in the parser.                                                                                                                                                                                                                                                                         |
 | AST parser `BEGIN SCRIPT name(params)` rejected     | The regex required whitespace between the script name and parameter list. `BEGIN SCRIPT foo(a,b)` (no space before `(`) silently failed to match, causing the matching `END SCRIPT` to raise "Unmatched END SCRIPT metacommand." Fixed by allowing optional whitespace before the parameter expression.                                                                                                                                                                                                                                                    |
 | AST executor forward SCRIPT references broken       | The legacy engine registered all `BEGIN SCRIPT` blocks at parse time (two-pass), so `EXECUTE SCRIPT foo` could appear before the `BEGIN SCRIPT foo` definition. The AST executor walked the tree in a single pass, so forward references failed with "There is no SCRIPT named foo." Fixed by adding a pre-registration scan of all SCRIPT blocks before execution begins.                                                                                                                                                                                 |

{execsql2-2.19.2 → execsql2-2.21.0}/docs/dev/adding_db_adapters.md

@@ -59,7 +59,7 @@ class MyDBDatabase(Database):
         self.need_passwd = False
         self.encoding = "UTF-8"
         self.encode_commands = False
-        self.paramstr = "?"      # placeholder style: "?" for most drivers, "%s" for psycopg2
+        self.paramstr = "?"      # placeholder style: "?" for most drivers, "%s" for psycopg
         self.conn = None
         self.autocommit = True
         self.open_db()
@@ -137,7 +137,7 @@ These are the instance attributes and methods you must configure correctly:
 | Attribute / Method     | Type              | Purpose                                                                           |
 | ---------------------- | ----------------- | --------------------------------------------------------------------------------- |
 | `self.type`            | `DbType`          | DBMS type token (e.g., `dbt_sqlite`). Controls quoting and type-mapping.          |
-| `self.paramstr`        | `str`             | SQL parameter placeholder: `"?"` (most drivers) or `"%s"` (psycopg2, PyMySQL).    |
+| `self.paramstr`        | `str`             | SQL parameter placeholder: `"?"` (most drivers) or `"%s"` (psycopg, PyMySQL).     |
 | `self.encoding`        | `str`             | Database character encoding. Detect from the database on connect if possible.     |
 | `self.encode_commands` | `bool`            | `True` if SQL strings should be encoded before passing to the driver.             |
 | `self.autocommit`      | `bool`            | `True` means the driver commits automatically; `False` requires explicit commits. |

{execsql2-2.19.2 → execsql2-2.21.0}/docs/dev/architecture.md

@@ -118,6 +118,32 @@ Use `--parse-tree` to print the AST without executing.
 
 `RuntimeContext` (in `state.py`) holds the per-run mutable state. `execute()` accepts an explicit `ctx`; the `active_context()` context manager installs one as the active thread-local so metacommand handlers and database adapters resolve against it automatically. Each thread gets its own context via `threading.local()`, enabling concurrent `execsql.run()` calls. The context carries the AST script registry (`ast_scripts`), the include cycle detector (`include_chain`), and the unified execution stack (`ast_exec_stack`) — a list of `ExecFrame` records describing every active scope, IF/LOOP/BATCH block, and INCLUDE'd file. Scope frames (`kind="main"` / `kind="script"`) hold the active `localvars` and `paramvals`; block frames cache a `scope_ref` to the enclosing scope for O(1) variable lookup. `current_script_line()` reads `ctx.last_command`, which the executor updates per statement.
 
+### Dispatch vs. AST executor — the stub seam
+
+A handful of keywords appear in **both** the metacommand dispatch table and the AST grammar. The dispatch entries are intentional stubs that raise `ErrInfo` at runtime if reached, and exist only so the keyword tables and tooling stay complete.
+
+| Keyword                                               | Source                                                       |
+| ----------------------------------------------------- | ------------------------------------------------------------ |
+| `IF` / `ANDIF` / `ORIF` / `ELSEIF` / `ELSE` / `ENDIF` | `metacommands/control.py` raises `_ast_only_stub("IF")` etc. |
+| `LOOP` / `BREAK`                                      | same                                                         |
+| `BEGIN BATCH` / `END BATCH`                           | same                                                         |
+
+What the stubs are for:
+
+- **`--dump-keywords`** walks the dispatch table to emit the canonical keyword list. The VS Code grammar in `extras/vscode-execsql/syntaxes/execsql.tmLanguage.json` is regenerated from `--dump-keywords` output (see `scripts/generate_vscode_grammar.py`). Removing the dispatch entries would silently shrink that grammar and lose highlighting for the affected keywords.
+- **Reachability is impossible at runtime.** The AST parser owns these constructs and they never bottom out in `_exec_metacommand()`. If a stub *does* raise, that means the parser missed a structural case — file a bug rather than implementing the dispatch path.
+
+A new contributor who greps for `ErrInfo: AST-only` lands in `metacommands/control.py:_ast_only_stub`; the same logic applies to any future keyword that the AST parser owns.
+
+### Legacy `commandliststack` residue
+
+`state.py` still exposes `commandliststack` (and `if_stack`, `savedscripts`) as `RuntimeContext` attributes for backwards compatibility with two surfaces:
+
+- **`metacommands/debug.py`** — the `x_debug_commandliststack` REPL helper and a few diagnostic prints read `_state.commandliststack[-1]` to surface the active local-variable frame.
+- **`state.py` proxy** — kept as a slot on `RuntimeContext` so external code that imported `from execsql.state import commandliststack` keeps importing.
+
+These are **read-only diagnostic surfaces.** New control-flow or scope code must go through `ctx.ast_exec_stack` / `ExecFrame`; the legacy stack is no longer the source of truth and is not pushed/popped by the AST executor in the way the old flat-command-list engine did. Treat `commandliststack` as a debug-only window onto `ctx.localvars` / `ctx.paramvals`.
+
 ______________________________________________________________________
 
 ## Plugin System

execsql2-2.21.0/docs/dev/releasing.md

@@ -0,0 +1,124 @@
+# Release Process
+
+This page documents the release workflow for `execsql2`. The release is
+fully automated — the version-bump commit (plus its companion tag) is
+the trigger; `.github/workflows/ci-cd.yml` does the rest.
+
+## Prerequisites
+
+- Working tree clean on `main` (or whatever branch you are releasing
+    from).
+- Local tests green: `just check`.
+- `CHANGELOG.md` `[Unreleased]` section reviewed and tightened to the
+    Keep-a-Changelog voice rule (one idea per bullet, user-facing tone,
+    no internal-only refactor notes). See `CLAUDE.md` for the full rule.
+- `docs/about/divergence.md` updated for any new feature, changed
+    behavior, security fix, or removed functionality that diverges from
+    upstream `execsql` v1.130.1.
+- You have `gh` authenticated against the `geocoug/execsql` repository
+    (`gh auth status` shows you're logged in).
+
+## Choose the bump level
+
+| Recipe                   | Use when                                                                                                                                       |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `just bump-patch`        | Bug fixes, doc fixes, dependency hygiene, anything user-invisible. Most releases.                                                              |
+| `just bump-minor`        | New features, new metacommands / flags / formats, backwards-compatible behavior changes.                                                       |
+| `just bump-major`        | Breaking changes. Public-API signature changes, removed metacommands, dropped Python versions.                                                 |
+| `just bump-pre 2.20.0a1` | Cut an explicit pre-release (alpha / beta / rc). Doesn't fire the publish workflow unless `--allow-dirty` and a tag-style argument trigger it. |
+
+What each one does (per `[tool.bumpversion]` in `pyproject.toml`):
+
+1. Rewrites the version in `pyproject.toml`, `CHANGELOG.md` (turns
+    `[Unreleased]` into the new dated section), `README.md`'s pre-commit
+    `rev:` snippet, and `docs/guides/formatter.md`'s pre-commit `rev:`
+    snippet.
+1. Runs `uv lock` (refreshes the lockfile against the new version) and
+    `git add uv.lock`.
+1. Creates a commit `Bump version: 2.X.Y → 2.X.Y+1`.
+1. Creates an annotated tag `v2.X.Y+1` on that commit.
+
+The working tree is now clean.
+
+## Push and watch CI
+
+```bash
+git push && git push --tags     # commit AND tag, both required
+gh run list --limit 1            # confirm the workflow fired
+gh run watch <RUN_ID> --exit-status   # block until it finishes (red on failure)
+```
+
+`gh run watch --exit-status` returns non-zero if any job in the workflow
+fails. Stay on the command until it exits.
+
+### What runs on a tag push
+
+| Job                    | Gating?                            | Purpose                                                          |
+| ---------------------- | ---------------------------------- | ---------------------------------------------------------------- |
+| `lint`                 | yes                                | ruff check + ruff format check                                   |
+| `tests` (matrix)       | yes                                | py3.10–3.14 × {ubuntu, macos, windows}                           |
+| `integration-tests`    | yes                                | PostgreSQL, MySQL, MSSQL service containers                      |
+| `access-tests-windows` | yes (when Access install succeeds) | Real Access driver on `windows-latest`                           |
+| `build`                | yes                                | `python -m build` produces sdist + wheel                         |
+| `publish`              | yes (tag-gated)                    | OIDC trusted-publisher PyPI upload                               |
+| `generate-release`     | yes (tag-gated)                    | Creates the GitHub release with auto-extracted CHANGELOG section |
+
+Build / publish / generate-release run only on tag refs
+(`if: startsWith(github.ref, 'refs/tags/v')`), so a non-bump push to
+`main` doesn't publish.
+
+## When something goes wrong
+
+### A test failed after the tag push (PyPI not yet published)
+
+The `build` job won't run if any earlier job is red, so `publish` won't
+fire. Fix:
+
+1. Identify the failure: `gh run view <RUN_ID> --log-failed`.
+1. Fix it on `main`.
+1. Re-bump: `just bump-patch` (this creates a *new* tag at the next patch
+    level; do NOT delete the old tag and retag the new commit — once a
+    tag has been visible publicly, treat it as immutable).
+1. Push and re-watch.
+
+### `publish` failed but the tag is live
+
+This is the worst case: PyPI is unaware, GitHub thinks the release
+happened. Fix:
+
+1. `gh run view <RUN_ID> --log-failed` and read the publish job log.
+1. Common cause: OIDC trust-policy drift, transient PyPI 5xx, or a name
+    collision with the pre-release tag.
+1. If transient: `gh run rerun --failed <RUN_ID>` and watch again.
+1. If structural (trust policy changed, package name conflict): delete
+    the GitHub release **but not the tag**, fix the cause, and re-trigger
+    the workflow manually via the Actions UI. The tag is the source of
+    truth for the version; don't reassign it.
+
+### `generate-release` succeeded but the CHANGELOG section is wrong
+
+The release-notes step in the workflow extracts the CHANGELOG section
+matching `## [<version>]`. Edit the GitHub release body directly through
+the UI or `gh release edit v2.X.Y --notes-file <path>`. Then fix the
+voice in `CHANGELOG.md` on `main` so future releases don't repeat the
+mistake.
+
+### `uv lock` produced an unrelated diff
+
+`bump-my-version` runs `uv lock` as a pre-commit hook to refresh the
+lockfile. If unrelated packages also moved (because they updated since
+your last sync), that's expected — `uv` is doing the right thing. If the
+diff is large enough to be worrying, abort the bump (`git restore .`),
+run `uv lock` manually, review, commit the lock update on its own, then
+re-bump.
+
+## Post-release sanity check
+
+After `gh run watch` exits green:
+
+- `pip install execsql2==2.X.Y` in a throwaway venv — confirms the
+    wheel landed on PyPI.
+- Browse the new GitHub release page; check the CHANGELOG section
+    matches what's on `main`.
+- `git pull` locally to retrieve the bump commit (you already had it
+    locally if you bumped yourself, but other contributors will sync).