execsql2 2.23.0__tar.gz → 2.24.0__tar.gz

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

@@ -43,6 +43,47 @@ jobs:
             - run: python -m pip install ".[dev]"
             - run: mypy src/execsql/
 
+    formatter-corpus:
+        name: formatter-corpus
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+            - 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]"
+            # Every formatter bug to date came from real SQL containing a
+            # construct the project's own scripts lack.  This gate runs those
+            # checks under their own name so a corpus failure is legible
+            # without reading a 6,000-test log.
+            - run: pytest tests/test_format.py -k corpus --no-cov -q
+
+    typer-floor:
+        name: typer-floor
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+            - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+              with:
+                  python-version: "3.10"
+                  cache: "pip"
+            - run: python -m pip install --upgrade pip
+            # Help rendering and flag parsing lean on Typer internals that
+            # move between releases, and every other job runs the newest
+            # Typer. Install the declared minimum, read from pyproject.toml so
+            # the two cannot drift, and run the CLI tests against it.
+            - run: |
+                  floor=$(grep -oP '"typer>=\K[0-9.]+' pyproject.toml)
+                  echo "Typer floor: $floor"
+                  python -m pip install ".[dev]" "typer==$floor"
+            - run: pytest tests/cli --no-cov -q
+
     pre-commit:
         name: pre-commit
         runs-on: ubuntu-latest
@@ -213,7 +254,7 @@ jobs:
             - name: Install dependencies
               run: |
                   python -m pip install --upgrade pip
-                  python -m pip install ".[dev,postgres,mysql,mssql]"
+                  python -m pip install ".[dev,postgres,mysql,mssql,upsert]"
             - name: Run subprocess integration tests
               run: |
                   python -m pytest tests/integration/test_postgres.py tests/integration/test_mysql.py -v --override-ini="addopts="
@@ -289,7 +330,7 @@ jobs:
     build:
         name: Build distribution 📦
         runs-on: ubuntu-latest
-        needs: [ lint, typecheck, pre-commit, docs, tests, integration-tests ]
+        needs: [ lint, typecheck, pre-commit, formatter-corpus, typer-floor, docs, tests, integration-tests ]
         # Deliberately NOT gated on tags: packaging breaks must surface on a PR,
         # not at release time. Only publish/generate-release below are tag-gated.
         permissions:
@@ -364,3 +405,67 @@ jobs:
                   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/.pre-commit-hooks.yaml

@@ -0,0 +1,17 @@
+- id: execsql-format
+  name: execsql-format
+  description: Format execsql SQL scripts — normalize metacommand indentation and uppercase keywords.
+  entry: execsql format
+  language: python
+  types: [file]
+  files: \.sql$
+  args: [--in-place]
+  additional_dependencies: ["sqlglot>=25.0,<31"]
+
+- id: execsql-lint
+  name: execsql-lint
+  description: Statically check execsql SQL scripts without a database — unclosed blocks, undefined or unused variables, missing INCLUDE targets, unreachable code.
+  entry: execsql lint
+  language: python
+  types: [file]
+  files: \.sql$

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

@@ -13,6 +13,67 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.24.0] - 2026-10-01
+
+### Added
+
+- **Commands:** `execsql run`, `format`, `lint`, `config`, `list` and `init`. `format` and `lint` take files or directories and need no database, so a whole script library can be linted at once. See [Commands](https://execsql2.readthedocs.io/en/latest/getting-started/syntax/#commands).
+- **`run`:** `--manifest FILE` writes a JSON record of the run (files read and written, connections, statement counts and any error), even when the run fails. `--var NAME=VALUE` sets `!!NAME!!` from the command line.
+- **`lint`:** every issue has a rule code (`V001`, `F002`, …) that `--select` and `--ignore` filter on. `--output-format json|concise|github`, `--statistics`, and `--strict` to fail on warnings. New checks for a `SUB` variable nothing reads, an `IF` whose condition never changes, and statements after `HALT`. See the [lint rules reference](https://execsql2.readthedocs.io/en/latest/reference/lint/).
+- **`execsql-lint` pre-commit hook**, alongside `execsql-format`.
+- **`format`:** `--diff` shows what would change without writing. `--sql` and `--no-leading-comma` override the config for one run.
+- **`format` and `lint`:** read a script from stdin with `-`, and take `-f`/`--script-encoding` and `--config`.
+- **`[format]` and `[lint]` config sections** set project defaults; a command-line flag wins.
+- **`config`:** lists every option with its value, its default and the file that set it, with passwords shown as `***`. `--validate` reports every problem in every config file with its file and line. `--init` prints the config template.
+- **`init`:** creates `execsql.conf`, a starter script and the pre-commit hooks. Existing files are kept unless you pass `--force`.
+- **`list`:** `metacommands`, `encodings`, `plugins` and `keywords`, as text or JSON.
+- **`PG_UPSERT` character-length check:** a staging value longer than its `varchar(n)` or `char(n)` base column fails QA and appears in the `EXPORT_FAILURES` fix sheet.
+
+### Deprecated
+
+- Running a script without a command (`execsql script.sql myserver mydb`) prints a warning and stops working in execsql2 3.0. Put `run` first: `execsql run script.sql myserver mydb`. `-m`, `-y`, `--list-plugins`, `--dump-keywords`, `--init-config` and `--ping` without a command warn the same way and name their replacement; see [Flags that became commands](https://execsql2.readthedocs.io/en/latest/getting-started/syntax/#former_flags). After `run` they still work without a warning, but `execsql run --help` no longer lists them.
+
+### Removed
+
+- `--lint`: use `execsql lint`. `execsql run --lint` now exits with status 2 without running the script, so update CI steps and hooks that call it.
+- The `execsql-format` command: use `execsql format`, which takes the same options. Pre-commit users need no change, because the hook id is still `execsql-format`. Shell scripts, Makefiles and CI steps that call `execsql-format` must be updated.
+- `SqlStmt`, `MetacommandStmt` and `ScriptCmd` from `execsql.script`. Only Python code that imports them is affected; scripts are not.
+
+### Changed
+
+- **`PG_UPSERT` QA follows `METHOD` and `EXCLUDE`:** all three modes check only the staging rows the load would write, so pass `PG_UPSERT QA` the same `METHOD` and `EXCLUDE` as the load that follows it. `CHECK ... METHOD update` treats a missing `NOT NULL` column as a warning. The `upsert` extra now requires pg-upsert 1.25.0 or newer. See [QA follows METHOD and EXCLUDE](https://execsql2.readthedocs.io/en/latest/reference/metacommands/#pg_upsert_qa_method).
+- **`PG_UPSERT` QA can fail where it passed before:** it now catches a unique key that collides with an existing base row, a foreign key parent that is not in `TABLES`, and an excluded `NOT NULL` column on an inserted row, all of which used to fail during the load.
+- A script named exactly like a command (`run`, `format`, `lint`, `config`, `list` or `init`, with no extension) must be run as `execsql run NAME`.
+- `execsql format --encoding` is now `-f`/`--script-encoding`, matching `run`. `--encoding` still works.
+- The debug REPL (`BREAKPOINT`, `--debug`) runs metacommands and blocks as well as SQL, as if they were the next lines of the script where it paused: a `SUB` stays set when the script resumes, and SQL is committed as the script's own SQL would be. See [Debugging](https://execsql2.readthedocs.io/en/latest/guides/debugging/).
+- CLI help is plain text, colored on a terminal (`NO_COLOR` or `EXECSQL_NO_COLOR` turns color off), and uses the terminal's full width. `execsql` with no arguments prints it and exits with status 2.
+- Lint output groups issues under each file in line order, with one summary line. A script that fails to parse is reported on one line with its line number.
+- Error messages name the fix: a missing SQLite or DuckDB file suggests `-n`/`--new-db`, and a config file error names the file and line and suggests `execsql config --validate`.
+- Requires Typer 0.26 or newer (previously 0.12).
+
+### Fixed
+
+- `execsql format` without the `[formatter]` extra says sqlglot is needed and how to install it, instead of an uncaught `ImportError`.
+- `-h` works as a short form of `--help`, as it did in upstream execsql.
+- The debug REPL's `.set VAR VALUE` keeps the value's case instead of lowercasing it, and `.vars all` lists environment variables instead of looking up a variable named `all`.
+
+______________________________________________________________________
+
+## [2.23.1] - 2026-09-29
+
+### Added
+
+- A warning when MySQL, MariaDB or Oracle commits a statement on its own while `AUTOCOMMIT` is `OFF` or a batch is open — `CREATE TABLE`, `DROP`, `TRUNCATE` and other DDL, which the server commits together with everything before it, so none of it can be rolled back.
+- A warning when `AUTOCOMMIT OFF` or `BEGIN BATCH` cannot hold statements at all: an ODBC DSN whose driver has no transactions, or an MS Access `CREATE TEMPORARY QUERY`, which reopens the connection and rolls back what was not yet committed.
+
+### Fixed
+
+- SQLite: `CREATE TABLE`, `DROP` and other DDL run while `AUTOCOMMIT` is `OFF` or inside `BEGIN BATCH` are held until commit. They were committed at once, so `AUTOCOMMIT ON WITH ROLLBACK` and `ROLLBACK BATCH` left them in place.
+- DuckDB: `AUTOCOMMIT OFF` and `BEGIN BATCH` hold statements until commit. Every statement, rows included, was committed as it ran, so nothing could be rolled back. A script's own `BEGIN;` and `COMMIT;` now work too; `COMMIT;` failed with "no transaction is active".
+- DuckDB: `$LAST_ROWCOUNT` holds the number of rows an `INSERT`, `UPDATE` or `DELETE` changed. It was always `-1`.
+
+______________________________________________________________________
+
 ## [2.23.0] - 2026-09-29
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execsql2
-Version: 2.23.0
+Version: 2.24.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
@@ -42,7 +42,7 @@ Requires-Python: >=3.10
 Requires-Dist: python-dateutil>=2.8
 Requires-Dist: rich>=13.0
 Requires-Dist: textual>=1.0
-Requires-Dist: typer>=0.12
+Requires-Dist: typer>=0.26
 Provides-Extra: all
 Requires-Dist: defusedxml>=0.7; extra == 'all'
 Requires-Dist: duckdb>=1.0; extra == 'all'
@@ -52,7 +52,7 @@ 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: pg-upsert>=1.25.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'
@@ -126,7 +126,7 @@ Requires-Dist: oracledb>=3.0; extra == 'oracle'
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'postgres'
 Provides-Extra: upsert
-Requires-Dist: pg-upsert>=1.23.0; extra == 'upsert'
+Requires-Dist: pg-upsert>=1.25.0; extra == 'upsert'
 Description-Content-Type: text/markdown
 
 > [!NOTE]
@@ -154,7 +154,54 @@ Description-Content-Type: text/markdown
 
 ## Overview
 
-*execsql* runs SQL scripts against PostgreSQL, MySQL/MariaDB, SQLite, DuckDB, MS-SQL-Server, MS-Access, Firebird, Oracle, or an ODBC DSN. In addition to standard SQL, it supports a set of metacommands (embedded in SQL comments) for importing and exporting data, copying data between databases, conditional execution, looping, substitution variables, and interactive prompts. Because metacommands live in SQL comments, scripts remain valid SQL and are ignored by other tools such as `psql` or `sqlcmd`.
+*execsql* is a toolchain for SQL scripts: **write** them with editor support, **format** them consistently, **lint** them without a database, and **run** them against nine DBMSs.
+
+Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), which add importing and exporting data, copying between databases, conditional execution, looping, substitution variables, and interactive prompts. Because the metacommands live in comments, the scripts stay valid SQL and other tools (`psql`, `sqlcmd`, your editor) ignore them.
+
+| 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 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                |
+| `execsql init`                             | Set up a project: config file, a script with a header, pre-commit hooks | No                |
+| [VS Code extension](extras/vscode-execsql) | Syntax highlighting for metacommands and variables                      | No                |
+
+`format` and `lint` take files or directories.
+
+> [!WARNING]
+> The original positional form, `execsql script.sql myserver mydb`, still works
+> but is deprecated: it prints a warning and stops working in execsql2 3.0. Use
+> `execsql run script.sql myserver mydb`.
+
+## Quick start: no database required
+
+`format` and `lint` work on a bare `.sql` file, with no server and no config. Try them first:
+
+```bash
+pip 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:
+
+```text
+$ execsql lint load_data.sql
+load_data.sql
+  1  warning  V002  variable !!site_cd!! is never used
+  2  warning  I001  INCLUDE file does not exist: common/setup.sql
+  3  warning  V001  undefined variable !!site_code!!
+
+Found 3 issues in 1 file: 3 warnings (1 file checked)
+```
+
+`V002` and `V001` together point at a typo: `site_cd` is defined and `site_code` is used. Every issue has a rule code for `--select` and `--ignore`; `--output-format concise` prints one `path:line` line per issue and `json` feeds CI tools. The [lint rules](https://execsql2.readthedocs.io/en/latest/reference/lint/) page explains each one.
+
+`execsql format` also runs as a [pre-commit hook](#formatting-scripts), so formatting is enforced without anyone remembering to run it.
 
 ## Example
 
@@ -197,49 +244,54 @@ The `PROMPT` metacommand produces a GUI display of the data:
 ## Installation
 
 ```bash
-pip install execsql2                # core — SQLite works with no extras
+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
 ```
 
-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.
+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
 
 ```text
-execsql [OPTIONS] SQL_SCRIPT [SERVER DATABASE | DATABASE_FILE]
+execsql run    [OPTIONS] SQL_SCRIPT [SERVER DATABASE | DATABASE_FILE]
+execsql format [--check | -i] [--indent N] FILE_OR_DIR...
+execsql lint   [OPTIONS] FILE_OR_DIR...
+execsql config [SQL_SCRIPT] [--init] [--config FILE]
+execsql list   metacommands|encodings|plugins|keywords
+execsql init   [DIR] [--script NAME] [--no-script] [--no-config] [--no-pre-commit]
 ```
 
 Examples:
 
 ```bash
-execsql -tp script.sql myserver mydb        # PostgreSQL
-execsql -tm script.sql myserver mydb        # MySQL / MariaDB
-execsql -ts script.sql myserver mydb        # SQL Server
-execsql -tl script.sql mydb.sqlite          # SQLite
-execsql -tk script.sql mydb.duckdb          # DuckDB
-execsql -to script.sql myserver myservice   # Oracle
-execsql script.sql                          # read connection from config file
+execsql run -tp script.sql myserver mydb        # PostgreSQL
+execsql run -tm script.sql myserver mydb        # MySQL / MariaDB
+execsql run -ts script.sql myserver mydb        # SQL Server
+execsql run -tl script.sql mydb.sqlite          # SQLite
+execsql run -tk script.sql mydb.duckdb          # DuckDB
+execsql run -to script.sql myserver myservice   # Oracle
+execsql run script.sql                          # read connection from config file
 ```
 
 ### Supported Databases
 
-| Flag | Database        | Support                                          |
-| ---- | --------------- | ------------------------------------------------ |
-| `p`  | PostgreSQL      | Supported — verified against a live server in CI |
-| `m`  | MySQL / MariaDB | Supported — verified against a live server in CI |
-| `s`  | MS SQL Server   | Supported — verified against a live server in CI |
-| `l`  | SQLite          | Supported — verified against real files in CI    |
-| `k`  | DuckDB          | Supported — verified against real files in CI    |
-| `a`  | MS Access       | Best effort — not verified in CI                 |
-| `f`  | Firebird        | Best effort — not verified in CI                 |
-| `o`  | Oracle          | Best effort — not verified in CI                 |
-| `d`  | ODBC DSN        | Best effort — not verified in CI                 |
+| Flag | Database        | Support                                         |
+| ---- | --------------- | ----------------------------------------------- |
+| `p`  | PostgreSQL      | Supported: verified against a live server in CI |
+| `m`  | MySQL / MariaDB | Supported: verified against a live server in CI |
+| `s`  | MS SQL Server   | Supported: verified against a live server in CI |
+| `l`  | SQLite          | Supported: verified against real files in CI    |
+| `k`  | DuckDB          | Supported: verified against real files in CI    |
+| `a`  | MS Access       | Best effort: not verified in CI                 |
+| `f`  | Firebird        | Best effort: not verified in CI                 |
+| `o`  | Oracle          | Best effort: not verified in CI                 |
+| `d`  | ODBC DSN        | Best effort: not verified in CI                 |
 
 **Supported** adapters run against a live server or a real database file on
 every CI run; a regression blocks the release and bugs get fixed. **Best
 effort** adapters are carried forward from the upstream monolith and are not
-exercised anywhere in CI — the code is there and may work, but nothing proves
+exercised anywhere in CI. The code is there and may work, but nothing proves
 it still does. Issues and pull requests are welcome for them; no guarantee is
 made. Opening a best-effort connection prints one informational line, which
 `support_tier_notice=No` in the `[interface]` section of `execsql.conf`
@@ -247,24 +299,24 @@ silences.
 
 ### Common options
 
-| Flag                                              | Description                                                     |
-| ------------------------------------------------- | --------------------------------------------------------------- |
-| `-t {p,m,s,l,k,a,f,o,d}`                          | Database type                                                   |
-| `-u USER`                                         | Database username                                               |
-| `-p PORT`                                         | Server port                                                     |
-| `--dsn URL`                                       | Connection string (e.g. `postgresql://user:pass@host/db`)       |
-| `-n`                                              | Create a new SQLite or PostgreSQL database if it does not exist |
-| `-c SCRIPT`                                       | Execute inline SQL or metacommand string                        |
-| `-a VALUE`                                        | Set substitution variable `$ARG_x`                              |
-| `-v {0,1,2,3}`                                    | GUI level (0=none, 1=password, 2=selection, 3=full)             |
-| `--config FILE`                                   | Load an explicit config file                                    |
-| `--dry-run`                                       | Parse the script and report commands without executing          |
-| `--lint`                                          | Static analysis: check structure and warn on issues (no DB)     |
-| `--ping`                                          | Test database connectivity and exit                             |
-| `--debug`                                         | Start in step-through debug mode (REPL pauses before each stmt) |
-| `--no-system-cmd` / `--no-rm-file` / `--no-serve` | Disable the `SYSTEM_CMD` / `RM_FILE` / `SERVE` metacommands     |
-
-See the [full options reference](https://execsql2.readthedocs.io/en/latest/getting-started/syntax/#options) or run `execsql --help` for the complete list, and `execsql -m` for all metacommands.
+| Flag                                              | Description                                                                |
+| ------------------------------------------------- | -------------------------------------------------------------------------- |
+| `-t {p,m,s,l,k,a,f,o,d}`                          | Database type                                                              |
+| `-u USER`                                         | Database username                                                          |
+| `-p PORT`                                         | Server port                                                                |
+| `--dsn URL`                                       | Connection string (e.g. `postgresql://user:pass@host/db`)                  |
+| `-n`                                              | Create a new SQLite or PostgreSQL database if it does not exist            |
+| `-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)                        |
+| `--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 |
+| `--debug`                                         | Start in step-through debug mode (REPL pauses before each stmt)            |
+| `--no-system-cmd` / `--no-rm-file` / `--no-serve` | Disable the `SYSTEM_CMD` / `RM_FILE` / `SERVE` metacommands                |
+
+See the [full options reference](https://execsql2.readthedocs.io/en/latest/getting-started/syntax/#options) or run `execsql run --help` for the complete list, `execsql run --ping` to test a connection, `execsql config` to see which config files set what, and `execsql list metacommands` for all metacommands.
 
 ## Features
 
@@ -279,7 +331,7 @@ See the [full options reference](https://execsql2.readthedocs.io/en/latest/getti
 - Conditionally execute SQL and metacommands using `IF`/`ELSE`/`ENDIF` based on data values, DBMS type, or user input.
 - Loop over blocks of SQL and metacommands using `LOOP`/`ENDLOOP`; include or chain scripts with `INCLUDE` and `SCRIPT`.
 - Use substitution variables (`SUB`, `$ARG_x`, built-in variables like `$date_tag`) to parameterize scripts.
-- Validate data with `ASSERT` — halt the script with a clear error message if a condition is false (ideal for CI pipelines).
+- Validate data with `ASSERT`: halt the script with a clear error message if a condition is false (ideal for CI pipelines).
 
 **Interaction & observability**
 
@@ -334,7 +386,7 @@ if not result.success:
 result.raise_on_error()  # raises ExecSqlError
 ```
 
-Use a pre-existing database connection instead of a DSN — useful for reusing one connection across multiple `run()` calls, or when connection parameters come from your application's configuration rather than a URL:
+Use a pre-existing database connection instead of a DSN. This is useful for reusing one connection across multiple `run()` calls, or when connection parameters come from your application's configuration rather than a URL:
 
 ```python
 from execsql import run
@@ -357,7 +409,7 @@ loaded = run(
     variables={"RUN_DATE": "2026-07-03"},
 )
 
-# run() does NOT close the connection — you manage its lifecycle
+# run() does NOT close the connection; you manage its lifecycle
 conn.close()
 
 # SQLite works the same way
@@ -366,43 +418,44 @@ result = run(sql="SELECT 1;", connection=conn)
 conn.close()
 ```
 
-Factory functions exist for every supported backend (`db_Postgres`, `db_MySQL`, `db_SQLite`, `db_DuckDB`, `db_SqlServer`, `db_Oracle`, `db_Firebird`, `db_Access`, `db_Dsn`) — see [`execsql.db.factory`](https://execsql2.readthedocs.io/en/latest/api/db/).
+Factory functions exist for every supported backend (`db_Postgres`, `db_MySQL`, `db_SQLite`, `db_DuckDB`, `db_SqlServer`, `db_Oracle`, `db_Firebird`, `db_Access`, `db_Dsn`). See [`execsql.db.factory`](https://execsql2.readthedocs.io/en/latest/api/db/).
 
 Each call to `run()` uses an isolated `RuntimeContext`, so multiple calls do not share state.
 
 ## Formatting Scripts
 
-The `execsql-format` command normalizes execsql script files: it uppercases metacommand keywords, corrects block indentation, and optionally reformats SQL via `sqlglot`. The metacommand / indent / keyword reformatting is built into `execsql2`; SQL reformatting requires the `[formatter]` extra (or pass `--no-sql` to skip it):
+The `execsql format` command normalizes execsql script files: it uppercases metacommand keywords, corrects block indentation, and optionally reformats SQL via `sqlglot`. The metacommand / indent / keyword reformatting is built into `execsql2`; SQL reformatting requires the `[formatter]` extra (or pass `--no-sql` to skip it):
 
 ```bash
 # Install with the SQL-reformatting extra
 pip install execsql2[formatter]
 
 # Format files in place
-execsql-format --in-place scripts/
+execsql format --in-place scripts/
 
 # Check formatting without writing (useful in CI)
-execsql-format --check scripts/
+execsql format --check scripts/
 
-# Run the formatter without sqlglot — keyword/indent normalization only
-execsql-format --no-sql --in-place scripts/
+# Run the formatter without sqlglot: keyword/indent normalization only
+execsql format --no-sql --in-place scripts/
 ```
 
-`execsql-format` is also available as a [pre-commit](https://pre-commit.com/) hook:
+`execsql format` and `execsql lint` are also available as [pre-commit](https://pre-commit.com/) hooks. The format hook id is unchanged, so existing configs keep working:
 
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.23.0
+    rev: v2.24.0
     hooks:
       - id: execsql-format
+      - id: execsql-lint
 ```
 
-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.
+The format hook rewrites `*.sql` files in place by default; the lint hook fails the commit when a script has a lint error. See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/guides/formatter/) for `--check`, `--indent`, and other options.
 
 ## VS Code Syntax Highlighting
 
-A VS Code extension for execsql syntax highlighting is included in [`extras/vscode-execsql`](extras/vscode-execsql). It injects a TextMate grammar into `.sql` files, adding highlighting for `-- !x!` metacommand markers, keywords (control flow, block, action, directive), variable substitutions (`!!var!!`, `!{var}!`), built-in functions, export formats, and config options — all layered on top of standard SQL highlighting.
+A VS Code extension for execsql syntax highlighting is included in [`extras/vscode-execsql`](extras/vscode-execsql). It injects a TextMate grammar into `.sql` files, adding highlighting for `-- !x!` metacommand markers, keywords (control flow, block, action, directive), variable substitutions (`!!var!!`, `!{var}!`), built-in functions, export formats, and config options, all layered on top of standard SQL highlighting.
 
 To install, symlink the extension folder into your VS Code extensions directory: