execsql2 2.26.0__tar.gz → 2.28.0__tar.gz

{execsql2-2.26.0 → execsql2-2.28.0}/.github/dependabot.yml

@@ -51,3 +51,12 @@ updates:
           pre-commit-hooks:
               patterns:
                   - "*"
+    # The VS Code extension's language client and its packaging tool.
+    - package-ecosystem: npm
+      directory: /extras/vscode-execsql
+      schedule:
+          interval: weekly
+      groups:
+          vscode-extension:
+              patterns:
+                  - "*"

{execsql2-2.26.0 → execsql2-2.28.0}/.github/workflows/ci-cd.yml

@@ -110,6 +110,37 @@ jobs:
               env:
                   SKIP: mypy
 
+    vscode-extension:
+        name: vscode-extension
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+            - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
+              with:
+                  node-version: "22"
+            # Dependencies come from the committed package-lock.json, and no
+            # install script of any dependency runs.
+            - name: Install dependencies
+              working-directory: extras/vscode-execsql
+              run: npm ci --ignore-scripts --no-audit --no-fund
+            # A release's extension carries the release's version (VS Code
+            # versions are X.Y.Z, so a pre-release suffix is dropped).
+            - name: Set the extension version from the tag
+              if: startsWith(github.ref, 'refs/tags/v')
+              working-directory: extras/vscode-execsql
+              run: |
+                  version="$(echo "${GITHUB_REF_NAME#v}" | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+')"
+                  npm pkg set version="$version"
+            - name: Package the .vsix
+              working-directory: extras/vscode-execsql
+              run: ./node_modules/.bin/vsce package --out "../../execsql-syntax.vsix"
+            - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+              with:
+                  name: vscode-extension
+                  path: execsql-syntax.vsix
+
     docs:
         name: docs
         runs-on: ubuntu-latest
@@ -338,7 +369,7 @@ jobs:
     build:
         name: Build distribution 📦
         runs-on: ubuntu-latest
-        needs: [ lint, typecheck, pre-commit, formatter-corpus, typer-floor, docs, tests, integration-tests ]
+        needs: [ lint, typecheck, pre-commit, formatter-corpus, typer-floor, docs, tests, integration-tests, vscode-extension ]
         # 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:
@@ -403,7 +434,7 @@ jobs:
         name: Generate GitHub Release
         # After the PyPI upload, so a release is never announced for a
         # version that pip cannot install.
-        needs: [ publish ]
+        needs: [ publish, vscode-extension ]
         if: startsWith(github.ref, 'refs/tags/v')
         runs-on: ubuntu-latest
         permissions:
@@ -416,6 +447,11 @@ jobs:
               with:
                   name: ${{ github.event.repository.name }}
                   path: dist/
+            - name: Download the VS Code extension
+              uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+              with:
+                  name: vscode-extension
+                  path: dist/
             - name: Detect pre-release tag
               id: tag
               # PEP 440 pre-release suffix (a1, b2, rc1) on the tag -> mark the

{execsql2-2.26.0 → execsql2-2.28.0}/.gitignore

@@ -56,3 +56,7 @@ PROMPTS.md
 audit/
 AGENTS.md
 .codex/
+
+# VS Code extension dependencies (npm ci in extras/vscode-execsql)
+node_modules/
+*.vsix

{execsql2-2.26.0 → execsql2-2.28.0}/.pre-commit-config.yaml

@@ -13,12 +13,12 @@ repos:
       - id: check-hooks-apply
   # Protect secrets using Gitleaks
   - repo: https://github.com/zricethezav/gitleaks
-    rev: v8.30.0
+    rev: v8.30.1
     hooks:
       - id: gitleaks
   # uv lockfile management
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.11.1
+    rev: 0.12.23
     hooks:
       - id: uv-lock
   # Base hooks
@@ -44,7 +44,7 @@ repos:
       - id: mdformat
         language: python
         additional_dependencies:
-          - mdformat-mkdocs==5.1.1
+          - mdformat-mkdocs==5.3.0
         exclude: |
           (?x)^(
             \.claude/.*|
@@ -56,7 +56,7 @@ repos:
           )$
   # Markdown lint
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.48.0
+    rev: v0.49.1
     hooks:
       - id: markdownlint
         types: [file]
@@ -64,13 +64,13 @@ repos:
         args: [--disable, MD013]
   # Spell check
   - repo: https://github.com/crate-ci/typos
-    rev: v1.44.0
+    rev: v1.51.0
     hooks:
       - id: typos
         args: [--force-exclude]
   # Lint & format with ruff
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.7
+    rev: v0.16.10
     hooks:
       - id: ruff-check
         args: [--config=pyproject.toml, --exit-non-zero-on-fix]

{execsql2-2.26.0 → execsql2-2.28.0}/.readthedocs.yaml

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

{execsql2-2.26.0 → execsql2-2.28.0}/CHANGELOG.md

@@ -13,6 +13,61 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.28.0] - 2026-10-13
+
+### Added
+
+- **`execsql lsp --check`** reports whether the language server can start (exit 0) or what is missing (exit 1).
+
+### Changed
+
+- **Missing-package messages** (database drivers, spreadsheet, YAML and template exports, `PG_UPSERT`, the formatter and the language server) name the execsql2 extra and show how to add it while keeping the extras already installed.
+
+### Fixed
+
+- **`execsql format` keeps optimizer hints and MySQL executable comments:** a statement holding `/*+ ... */` or `/*! ... */` is left as written in both modes. It was rewritten to `/* + ... */` and the hint moved off its keyword, so MySQL skipped the `/*! */` SQL (for example a `WHERE` or `PARTITION BY`) and Oracle/MySQL ignored the hint; re-check files the formatter or its pre-commit hook rewrote.
+- **`execsql format` no longer ends a final statement with a `;` the script did not have:** a script execsql refused for an unfinished last statement became one that ran it.
+- **`execsql format`:** a statement kept as written after another on the same line no longer starts with a space.
+- **`execsql format` without sqlglot** printed its `pip install` hint without the `[formatter]` extra.
+- **`execsql lint` and the language server read a `SUB_INI` file once** however many lines name it; a script naming a large INI file on many lines took minutes to lint and froze the editor. V002 for a variable a `SUB_INI` defines is reported at the `SUB_INI` line, not line 0.
+- **`execsql lsp` with an incompatible pygls** names the installed pygls version instead of saying the `lsp` extra is missing.
+- **`COPY` keeps binary columns** (SQLite/DuckDB BLOB, PostgreSQL `bytea`) byte for byte, and `COPY ... TO NEW` creates them as binary columns. They were copied as escaped text (`\x89PNG...`), and into PostgreSQL as text.
+- **DuckDB `TO NEW`** is no longer refused because a table of the same name exists in an `ATTACH`ed database; only the current database counts.
+
+______________________________________________________________________
+
+## [2.27.0] - 2026-10-12
+
+### Added
+
+- **`execsql lsp`**, a language server for editors. Install the new `lsp` extra (`uv tool install "execsql2[lsp]"`; to add it to an existing install, name the extras you already have, e.g. `"execsql2[postgres,lsp]"`); setup for VS Code, Neovim, Helix and other editors is in the new Editor Support guide. It provides:
+
+    - `execsql lint` findings as you type, using the workspace's `[lint]` settings;
+    - completion of metacommands (as fill-in templates of their documented syntax), conditional tests, variables and export formats;
+    - hover explanations of metacommands, conditional tests and variables;
+    - Go to Definition, Find All References, Rename Symbol (variables), the outline and `INCLUDE` links;
+    - folding of `IF` branches, `LOOP`, `SCRIPT`, `BATCH` and `SQL` blocks, multi-line statements and comments;
+    - quick fixes for misspelled metacommands, conditional tests and variables (P003, P004, V001) and split dollar-quoted bodies (P002);
+    - Format Document, the same as `execsql format` with the workspace's `[format]` settings;
+    - `execsql.conf` read again when it changes, and open scripts linted again when a file they `INCLUDE` changes;
+    - each folder of a multi-root workspace linted and formatted with its own `execsql.conf`.
+
+    The server never runs a script or connects to a database. It reads the open scripts, the files they `INCLUDE` or name in `SUB_INI` (regular files of bounded size), and the configuration files `execsql lint` reads.
+
+- **VS Code extension** starts `execsql lsp` for `.sql` files, with `execsql.server.path` and `execsql.server.enabled` settings and an **execsql: Restart Language Server** command. Each GitHub release attaches it as `execsql-syntax.vsix`; install with `code --install-extension execsql-syntax.vsix`. The server starts only in a trusted folder; highlighting works in any. `execsql.server.path` is a command name looked up in PATH or an absolute path, and the extension never runs an `execsql` found in the open folder.
+
+### Changed
+
+- **`lsp` is a command name:** `execsql lsp` starts the language server. Run a script file named `lsp` (with no extension) as `execsql run lsp`.
+- **`execsql list metacommands`** lists every metacommand (all 95; some were missing) with its category and a one-line summary, and `execsql list metacommands <KEYWORD>` shows that metacommand's syntax, as the reference docs write it, with a link. In `--output-format json`, `syntax` is now the full first syntax line, and each entry adds `forms`, `category`, `summary` and `url`. Read `forms` for every syntax line.
+
+### Fixed
+
+- **DuckDB `TIMESTAMPTZ` values** are read instead of stopping the script: the `duckdb` and `all-db` extras now install `pytz`, which duckdb needs for them.
+- **`CONFIG MAX_INT <n>`** works as documented; it stopped with `Unknown metacommand`, and only the bare `MAX_INT <n>` (still accepted) was recognized.
+
+______________________________________________________________________
+
 ## [2.26.0] - 2026-10-09
 
 ### Added

{execsql2-2.26.0 → execsql2-2.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execsql2
-Version: 2.26.0
+Version: 2.28.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
@@ -49,14 +49,17 @@ 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: lsprotocol>=2025.0.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.25.0; extra == 'all'
 Requires-Dist: polars>=1.0; extra == 'all'
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'all'
+Requires-Dist: pygls<3,>=2.1; extra == 'all'
 Requires-Dist: pymysql>=1.1; extra == 'all'
 Requires-Dist: pyodbc>=5.0; extra == 'all'
+Requires-Dist: pytz; extra == 'all'
 Requires-Dist: pyyaml>=6.0; extra == 'all'
 Requires-Dist: sqlglot<30.22,>=30.21.0; extra == 'all'
 Requires-Dist: tables>=3.10; extra == 'all'
@@ -69,6 +72,7 @@ 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'
+Requires-Dist: pytz; extra == 'all-db'
 Provides-Extra: auth
 Requires-Dist: keyring>=25.0; extra == 'auth'
 Provides-Extra: auth-encrypted
@@ -83,13 +87,18 @@ Requires-Dist: build>=1.2.2.post1; extra == 'dev'
 Requires-Dist: bump-my-version>=1.2.7; extra == 'dev'
 Requires-Dist: defusedxml>=0.7; extra == 'dev'
 Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: lsprotocol>=2025.0.0; extra == 'dev'
 Requires-Dist: mkdocstrings-python>=2.0.3; extra == 'dev'
 Requires-Dist: mypy>=1.10; 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: pygls<3,>=2.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-lsp>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: pyyaml>=6.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: sqlglot<30.22,>=30.21.0; extra == 'dev'
@@ -97,9 +106,10 @@ 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>=2.0; extra == 'dev'
-Requires-Dist: zensical==0.0.28; extra == 'dev'
+Requires-Dist: zensical==0.0.67; extra == 'dev'
 Provides-Extra: duckdb
 Requires-Dist: duckdb>=1.0; extra == 'duckdb'
+Requires-Dist: pytz; extra == 'duckdb'
 Provides-Extra: firebird
 Requires-Dist: firebird-driver>=1.10; extra == 'firebird'
 Provides-Extra: formats
@@ -113,6 +123,10 @@ Requires-Dist: tables>=3.10; extra == 'formats'
 Requires-Dist: xlrd>=2.0; extra == 'formats'
 Provides-Extra: formatter
 Requires-Dist: sqlglot<30.22,>=30.21.0; extra == 'formatter'
+Provides-Extra: lsp
+Requires-Dist: lsprotocol>=2025.0.0; extra == 'lsp'
+Requires-Dist: pygls<3,>=2.1; extra == 'lsp'
+Requires-Dist: sqlglot<30.22,>=30.21.0; extra == 'lsp'
 Provides-Extra: map
 Requires-Dist: tkintermapview>=1.29; extra == 'map'
 Provides-Extra: mssql
@@ -158,15 +172,16 @@ Description-Content-Type: text/markdown
 
 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, 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                |
-| `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                |
+| Command                                    | What it does                                                                                                                                                          | Needs a database? |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `execsql format`                           | Normalize keywords, indentation, and SQL layout                                                                                                                       | 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                |
+| `execsql init`                             | Set up a project: config file, a script with a header, pre-commit hooks                                                                                               | No                |
+| `execsql lsp`                              | [Language server](https://execsql2.readthedocs.io/en/latest/guides/editors/): lint findings, completion, hover, navigation, quick fixes and formatting in your editor | No                |
+| [VS Code extension](extras/vscode-execsql) | Highlighting plus everything `execsql lsp` provides                                                                                                                   | No                |
 
 `format` and `lint` take files or directories.
 
@@ -451,7 +466,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.26.0
+    rev: v2.28.0
     hooks:
       - id: execsql-format
       - id: execsql-lint
@@ -459,17 +474,18 @@ repos:
 
 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
+## VS Code
 
-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:
+The VS Code extension in [`extras/vscode-execsql`](extras/vscode-execsql) highlights execsql syntax in `.sql` files (metacommand markers, keywords, variable substitutions, export formats, config options) on top of standard SQL highlighting, and starts the execsql language server for lint findings as you type and completion. Each GitHub release has the extension attached as `execsql-syntax.vsix`:
 
 ```sh
-ln -s /path/to/execsql/extras/vscode-execsql ~/.vscode/extensions/execsql-syntax
+uv tool install "execsql2[lsp]"                     # the language server
+code --install-extension execsql-syntax.vsix        # the extension, from the release
 ```
 
-See the [extension README](extras/vscode-execsql/README.md) for Windows instructions, color customization, and troubleshooting.
+If execsql is already installed with other extras, name them too, e.g. `uv tool install "execsql2[postgres,lsp]"` or `pipx install --force "execsql2[postgres,lsp]"`: the new list replaces the old one (see [Adding an extra later](https://execsql2.readthedocs.io/en/latest/getting-started/installation/#adding-an-extra-later)).
+
+Other editors use the language server directly: see [Editor Support](https://execsql2.readthedocs.io/en/latest/guides/editors/). The [extension README](extras/vscode-execsql/README.md) covers settings, installing from a clone, color customization, and troubleshooting.
 
 ## Templates
 

{execsql2-2.26.0 → execsql2-2.28.0}/README.md

@@ -27,15 +27,16 @@
 
 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, 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                |
-| `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                |
+| Command                                    | What it does                                                                                                                                                          | Needs a database? |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `execsql format`                           | Normalize keywords, indentation, and SQL layout                                                                                                                       | 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                |
+| `execsql init`                             | Set up a project: config file, a script with a header, pre-commit hooks                                                                                               | No                |
+| `execsql lsp`                              | [Language server](https://execsql2.readthedocs.io/en/latest/guides/editors/): lint findings, completion, hover, navigation, quick fixes and formatting in your editor | No                |
+| [VS Code extension](extras/vscode-execsql) | Highlighting plus everything `execsql lsp` provides                                                                                                                   | No                |
 
 `format` and `lint` take files or directories.
 
@@ -320,7 +321,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.26.0
+    rev: v2.28.0
     hooks:
       - id: execsql-format
       - id: execsql-lint
@@ -328,17 +329,18 @@ repos:
 
 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
+## VS Code
 
-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:
+The VS Code extension in [`extras/vscode-execsql`](extras/vscode-execsql) highlights execsql syntax in `.sql` files (metacommand markers, keywords, variable substitutions, export formats, config options) on top of standard SQL highlighting, and starts the execsql language server for lint findings as you type and completion. Each GitHub release has the extension attached as `execsql-syntax.vsix`:
 
 ```sh
-ln -s /path/to/execsql/extras/vscode-execsql ~/.vscode/extensions/execsql-syntax
+uv tool install "execsql2[lsp]"                     # the language server
+code --install-extension execsql-syntax.vsix        # the extension, from the release
 ```
 
-See the [extension README](extras/vscode-execsql/README.md) for Windows instructions, color customization, and troubleshooting.
+If execsql is already installed with other extras, name them too, e.g. `uv tool install "execsql2[postgres,lsp]"` or `pipx install --force "execsql2[postgres,lsp]"`: the new list replaces the old one (see [Adding an extra later](https://execsql2.readthedocs.io/en/latest/getting-started/installation/#adding-an-extra-later)).
+
+Other editors use the language server directly: see [Editor Support](https://execsql2.readthedocs.io/en/latest/guides/editors/). The [extension README](extras/vscode-execsql/README.md) covers settings, installing from a clone, color customization, and troubleshooting.
 
 ## Templates
 

{execsql2-2.26.0 → execsql2-2.28.0}/docs/about/divergence.md

@@ -71,6 +71,7 @@ ______________________________________________________________________
 | Fix                             | Description                                                                                                                                                                                                                                                                                                              |
 | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Variable EXECUTE SCRIPT targets | `EXECUTE SCRIPT !!#var!!` now works — the parser accepts substitution variable patterns as script identifiers, and the executor resolves them at runtime.                                                                                                                                                                |
+| `CONFIG MAX_INT`                | The documented `CONFIG MAX_INT <n>` form is accepted. Upstream documented it but recognized only the bare `MAX_INT <n>`, which still works.                                                                                                                                                                              |
 | Quoted parameter defaults       | `BEGIN SCRIPT proc(name="value")` previously stored the literal `"value"` (with surrounding quotes), causing substitutions like `WRITE "!!#name!!"` to expand to `WRITE ""value""` and fail. Defaults now strip surrounding quotes at parse time, matching the `wo_quotes` handling already applied to passed arguments. |
 
 ### Conditional Tests
@@ -134,8 +135,9 @@ today — a script named exactly like a command — is recorded under
 | `execsql format` | The formatter, reached through the main command. It replaced the standalone `execsql-format` console script, which was removed. The published pre-commit hook **id** is still `execsql-format`, so downstream `.pre-commit-config.yaml` files need no change — only the hook's internal `entry` moved. Formatter for normalizing metacommand indentation and uppercasing SQL keywords. Supports `--check`, `--in-place`, `--indent N` (controls both metacommand and SQL indentation), `--leading-comma` (commas at start of lines), `--no-sql` (skip SQL reformatting), `--rewrite-sql` (accept sqlglot's rewrites of SQL text; off by default, so only layout changes), `-f`/`--script-encoding` (formerly `--encoding`, still accepted), and `--config`; `-` formats stdin to stdout. 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. |
 | `execsql lint`   | Static checks over files *and directories*, walking directories recursively for `*.sql`; `-` reads stdin. Scripts are read with `-f`/`--script-encoding` or `[encoding] script` from config, like `run`. Every issue carries a [rule code](../reference/lint.md#rules); `--select` / `--ignore` choose rules, `--output-format json` feeds tools, and `--statistics` counts issues per rule. It replaced the `--lint` flag, which checked only the one script it was given.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `execsql config` | List every config option with its current value, default, and the file that set it, resolved as a run would (pass a script to include its directory's `execsql.conf`). Passwords are masked. `--init` prints the template (replaces `--init-config`). `--validate` reports every problem in every config file a run reads, with file and line: invalid values and unparsable files as errors, unknown or misplaced sections and keys as warnings — upstream stopped at the first bad value and ignored unknown names silently.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `execsql list`   | `metacommands`, `encodings`, `plugins` or `keywords`, as text or JSON. Replaces `-m`, `-y`, `--list-plugins` and `--dump-keywords`; `-m` and `-y` are upstream flags and keep working as hidden aliases, deprecated when used without a command.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `execsql list`   | `metacommands`, `encodings`, `plugins` or `keywords`, as text or JSON. Replaces `-m`, `-y`, `--list-plugins` and `--dump-keywords`; `-m` and `-y` are upstream flags and keep working as hidden aliases, deprecated when used without a command. `-m` / `list metacommands` prints each metacommand's category and one-line summary (and its syntax when given a keyword) instead of upstream's listing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `execsql init`   | Set up a project: `execsql.conf` from the template, a script with a header (from the upstream script template), and the `execsql-format` / `execsql-lint` pre-commit hooks. Never overwrites without `--force`, and never rewrites an existing `.pre-commit-config.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `execsql lsp`    | A language server for editors, started over stdio: `execsql lint` findings shown as you type, with the `[lint]` settings of the workspace's config, completion of metacommands (as templates of their documented syntax), conditional tests, variables and export formats, hover explanations, navigation (definition, references, outline, `INCLUDE` links), Rename Symbol for variables, folding, quick fixes for P003, P004, V001 and P002, and Format Document (`execsql format` with the workspace's `[format]` settings). Settings are read per workspace folder and again when `execsql.conf` or an included file changes. The VS Code extension in `extras/vscode-execsql` starts it only in a trusted workspace. Needs the `lsp` extra (pygls). See [Editor Support](../guides/editors.md#editors).                                                                                                                                                                                                                                                                                                 |
 
 Formatter correctness notes added in the 2.19.x line:
 
@@ -284,6 +286,7 @@ The legacy flat command-list engine (`_parse_script_lines` / `runscripts` / `Com
 - **Exception hierarchy** — All custom exceptions inherit from `ExecSqlError`, enabling `except ExecSqlError` to catch any execsql-originated error.
 - **Exception chaining** — All `raise` statements inside `except` blocks preserve the original traceback via `from`.
 - **Database and driver error messages** — End with the error itself (`OperationalError: table t already exists`). Upstream appended "in <file> on line N of execsql", a line of its own source; in the package the file was often a driver's and the line number another file's. Where in execsql the error was raised goes to `execsql.log` as `Raised at: execsql/<module>.py:<line>`.
+- **Missing optional package messages** — Name the execsql2 extra that installs the package and how to add it to a `uv tool` or `pipx` install without dropping the extras already there (`uv tool install "execsql2[...,postgres]"`). Upstream pointed at the package's web page.
 - **Config file errors** — An invalid value in `execsql.conf` stops a run with `Configuration error: <file>: <problem>` (and the line, for an unreadable file) plus a pointer to `execsql config --validate`. Upstream printed `Configuration error on line N of execsql.py`, where N was a line of its own source. A duplicate key, a missing section header or a bare `%` is reported the same way; upstream failed with an uncaught exception. Errors raised by `ConfigData` for a file are `ConfigFileError`, a subclass of `ConfigError`.
 - **ASSERT error type** — `ASSERT` failures now use a dedicated `"assert"` error type that produces `**** Assertion failed.` instead of `**** Error in metacommand.`. This distinguishes intentional script-level checks from actual metacommand errors. Upstream did not have `ASSERT`.
 
@@ -358,10 +361,11 @@ These are behavioral changes driven by security or correctness issues in the ups
 | `DT_Timestamp` claims time-only values                             | `dateutil.parser.parse()` silently fills in today's date for bare time strings like `"13:15:45"`, so `DT_Timestamp` matched before `DT_Time` in the inference order. `parse_datetime()` now rejects time-only strings.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | Partial dates inferred as timestamps                               | `dateutil` fills fields missing from a value with today's date, so `1-2`, `5/6`, `March 5`, `Jan` and `Monday` were inferred as timestamps and, on DuckDB, SQL Server, MySQL, Oracle, Firebird, Access and every ODS/XLSX/JSON/Parquet/Feather import, stored as dates in the current year. Inference now requires a four-digit year (or a month-first `m/d/yy` or `m-d-yy`) and a month and day, which restores upstream's behaviour for these values. `m-d-yy` is accepted in addition to upstream's `m/d/yy`.                                                                                                                                                                                                                                                                                                   |
 | Offset values stored as plain timestamps                           | With `dateutil`, a value with a UTC offset (`2024-01-01 10:00+05:00`) also counted as a plain timestamp, so a column mixing offset and plain values was created as `timestamp` and the driver converted the offset values with the client's time zone: the stored value depended on the machine that ran the import. A value with an offset is again not a plain timestamp, as with upstream's offset-free format list, so a mixed column is text and keeps each value as written. A column where every value has an offset is still `timestamptz`.                                                                                                                                                                                                                                                                |
+| Binary columns in `COPY`                                           | Every value a source cursor returned as bytes was decoded to text (undecodable bytes as `\xNN` escapes) before `COPY` wrote it, and `TO NEW` typed the column as text. Upstream did the same for SQLite BLOBs; with psycopg2 a PostgreSQL `bytea` arrived as a `memoryview` and escaped the decode, so for PostgreSQL this was an execsql2 regression. `COPY` now moves bytes unchanged and creates binary columns. Exports still write the decoded text.                                                                                                                                                                                                                                                                                                                                                          |
 | Short data lines on import                                         | A line with fewer values than the header was padded with NULLs only on PostgreSQL and MySQL. SQLite stopped with "Too few values", DuckDB and the other DBMSs with a driver parameter-count error. With `TO NEW` / `REPLACEMENT`, type inference skipped the missing values, so the column could be created `NOT NULL` and then reject the padded line, on PostgreSQL too. Missing trailing values are now NULL on every DBMS, and inference counts them as NULL.                                                                                                                                                                                                                                                                                                                                                  |
 | `COPY` re-typed text values                                        | Upstream described the destination table by re-reading the source's text values as if they came from a file, so a text column of `1`/`0` became `boolean` and one of dates became `timestamp` with `NEW` / `REPLACEMENT`, and values copied into an existing text column were converted on the way in (`1` stored as `true`). Text from the source database now stays text. Upstream also ran the source query twice, once to describe the table and once to copy it; execsql2 runs it once and holds the rows in a temporary file in between.                                                                                                                                                                                                                                                                     |
 | `REPLACEMENT` of a quoted or schema-qualified table                | The SQLite, SQL Server, Oracle, Firebird and Access adapters quoted the table name a second time before dropping it, so `IMPORT` / `COPY ... TO REPLACEMENT "my tbl"` dropped a table named `"my tbl"` (quotes included) that did not exist and then failed to create the table, and on SQL Server, Oracle and Firebird `REPLACEMENT staging.t` tried to drop one table named `staging.t`. The name is now quoted once.                                                                                                                                                                                                                                                                                                                                                                                            |
-| `TO NEW` onto an existing table                                    | `COPY`'s checks that the source exists and that a `NEW` target does not were dead code: each raised its error inside a `try` that discarded it. `IMPORT ... TO NEW` had no check. Both now stop with `Table <name> already exists` before any DDL (when the database cannot say whether the table exists, the command goes ahead). A name without a schema counts only in the schema the table would be created in (MySQL: the current database). The source check was removed instead of revived: PostgreSQL reads an unquoted `COPY Orders` as `orders`, which the check would have reported missing.                                                                                                                                                                                                            |
+| `TO NEW` onto an existing table                                    | `COPY`'s checks that the source exists and that a `NEW` target does not were dead code: each raised its error inside a `try` that discarded it. `IMPORT ... TO NEW` had no check. Both now stop with `Table <name> already exists` before any DDL (when the database cannot say whether the table exists, the command goes ahead). A name without a schema counts only in the schema the table would be created in (MySQL: the current database), and on DuckDB only in the current database, not an `ATTACH`ed one. The source check was removed instead of revived: PostgreSQL reads an unquoted `COPY Orders` as `orders`, which the check would have reported missing.                                                                                                                                         |
 | No `exit` log record on error or halt                              | The log was closed before the `exit` record was written, so a run that ended with an error, a `HALT` or a cancelled prompt left no `exit` line, and Ctrl-C was recorded as `unknown`. Every run now writes exactly one `exit` record; Ctrl-C is `interrupted`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | SIGTERM lost the run's log                                         | Python's default SIGTERM action ends the process without running exit handlers, so the buffered `execsql.log` (every record of the run) was never written, the transaction was not rolled back explicitly and a running `SYSTEM_CMD` kept going. The `execsql` command now turns SIGTERM into a normal exit with status 143 and an `exit` record of type `terminated`. `execsql.run()` does not install a handler.                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `access_use_numeric` ignored                                       | The config option was read but never applied, so MS-Access tables created by `IMPORT` / `COPY` always got `DOUBLE` for decimal data. With `Yes` they get `NUMERIC(precision,scale)` again, as upstream. The setting is read when each table is created, so it applies per run (upstream changed the shared type map once at startup).                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

{execsql2-2.26.0 → execsql2-2.28.0}/docs/dev/adding_metacommands.md

@@ -223,9 +223,32 @@ ______________________________________________________________________
 - [ ] Handler function added to the appropriate `src/execsql/metacommands/*.py` module
 - [ ] Handler imported in `src/execsql/metacommands/dispatch.py`
 - [ ] `mcl.add(...)` call added in `build_dispatch_table()` with `description=` and `category=`
+- [ ] Entry added to `src/execsql/metacommands/reference.py`: the syntax line(s) as the reference docs write them, a one-line summary and the docs anchor (see below)
+- [ ] A line using it added to `tests/data/lint/every_metacommand.sql`
 - [ ] Run `just install-vscode` to regenerate the VS Code grammar
 - [ ] Integration test added to `tests/test_metacommands.py` (or relevant file)
-- [ ] `pytest` passes locally (including `tests/test_registry.py` keyword consistency checks)
+- [ ] `pytest` passes locally (including `tests/test_registry.py` and `tests/test_reference.py`)
+
+### The readable syntax entry
+
+The dispatch table's regular expressions are not something to show a person.
+`execsql.metacommands.reference` holds what editors (`execsql lsp`) and
+`execsql list metacommands` show instead:
+
+```python
+Metacommand(
+    "MY_COMMAND",                       # the description= keyword
+    "action",                           # the category=
+    ("MY_COMMAND <table> TO <file>",),  # syntax lines, docs notation: <value>, [optional], A|B
+    "Does one thing to a table.",       # one sentence, at most 120 characters
+    "my_command",                       # the heading's anchor in docs/reference/metacommands.md
+),
+```
+
+Editor completion turns each syntax line into a fill-in template (`<value>`
+becomes a tab stop, `A|B` a choice). `tests/test_reference.py` fails until the
+entry exists, its anchor is a real heading, and each syntax line, filled with
+sample values, is accepted by the dispatch table.
 
 ______________________________________________________________________
 
@@ -251,3 +274,5 @@ mcl.add(
 ```
 
 The result is exposed as `CONDITIONAL_TABLE` and consumed at runtime via `_state.conditionallist`.
+
+Add a `Condition(...)` entry to `src/execsql/metacommands/reference.py` as well (name, syntax line such as `MY_TEST(<table>)`, one-line summary, docs anchor) and a use of it to `tests/data/lint/conditions_and_blocks.sql`; `tests/test_reference.py` checks that every conditional test has an entry.

{execsql2-2.26.0 → execsql2-2.28.0}/docs/dev/releasing.md

@@ -53,15 +53,16 @@ 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                                | Checks the tag equals `project.version`; `python -m build` produces sdist + wheel |
-| `publish`              | yes (tag-gated)                    | OIDC trusted-publisher PyPI upload                                                |
-| `generate-release`     | yes (tag-gated, after `publish`)   | Creates the GitHub release with auto-extracted CHANGELOG section                  |
+| 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                                                     | Checks the tag equals `project.version`; `python -m build` produces sdist + wheel                       |
+| `publish`              | yes (tag-gated)                                         | OIDC trusted-publisher PyPI upload                                                                      |
+| `vscode-extension`     | yes                                                     | Packages `extras/vscode-execsql` into `execsql-syntax.vsix` (on a tag, with the tag's X.Y.Z version)    |
+| `generate-release`     | yes (tag-gated, after `publish` and `vscode-extension`) | Creates the GitHub release with auto-extracted CHANGELOG section; attaches the sdist, wheel and `.vsix` |
 
 Publish / generate-release run only on tag refs
 (`if: startsWith(github.ref, 'refs/tags/v')`), so a non-bump push to
@@ -129,6 +130,6 @@ 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`.
+    matches what's on `main` and that `execsql-syntax.vsix` is attached.
 - `git pull` locally to retrieve the bump commit (you already had it
     locally if you bumped yourself, but other contributors will sync).