execsql2 2.16.14__tar.gz → 2.16.16__tar.gz

{execsql2-2.16.14 → execsql2-2.16.16}/.github/workflows/ci-cd.yml

@@ -14,6 +14,20 @@ concurrency:
     cancel-in-progress: true
 
 jobs:
+    lint:
+        name: lint
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@v6
+            - uses: actions/setup-python@v6
+              with:
+                  python-version: "3.13"
+            - run: python -m pip install ruff
+            - run: ruff check src/ tests/
+            - run: ruff format --check src/ tests/
+
     tests:
         strategy:
             fail-fast: false
@@ -43,7 +57,8 @@ jobs:
               uses: actions/cache@v5
               with:
                   path: ~/.cache/pip
-                  key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('**/pyproject.toml') }}
+                  key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{
+                      hashFiles('**/pyproject.toml') }}
                   restore-keys: |
                       ${{ runner.os }}-pip-${{ matrix.python-version }}-
             - name: Install dependencies
@@ -86,10 +101,8 @@ jobs:
                 ports:
                     - 5432:5432
                 options: >-
-                    --health-cmd pg_isready
-                    --health-interval 10s
-                    --health-timeout 5s
-                    --health-retries 5
+                    --health-cmd pg_isready --health-interval 10s
+                    --health-timeout 5s --health-retries 5
             mysql:
                 image: mysql:8
                 env:
@@ -100,10 +113,8 @@ jobs:
                 ports:
                     - 3306:3306
                 options: >-
-                    --health-cmd "mysqladmin ping"
-                    --health-interval 10s
-                    --health-timeout 5s
-                    --health-retries 5
+                    --health-cmd "mysqladmin ping" --health-interval 10s
+                    --health-timeout 5s --health-retries 5
         steps:
             - name: Check out repository code
               uses: actions/checkout@v6
@@ -122,7 +133,7 @@ jobs:
     build:
         name: Build distribution 📦
         runs-on: ubuntu-latest
-        needs: [tests, integration-tests]
+        needs: [ lint, tests, integration-tests ]
         if: startsWith(github.ref, 'refs/tags/v')
         permissions:
             contents: read
@@ -147,7 +158,7 @@ jobs:
 
     publish:
         name: PyPI Publish 🚀
-        needs: [build]
+        needs: [ build ]
         if: startsWith(github.ref, 'refs/tags/v')
         runs-on: ubuntu-latest
         environment:
@@ -170,7 +181,7 @@ jobs:
 
     generate-release:
         name: Generate GitHub Release
-        needs: [build]
+        needs: [ build ]
         if: startsWith(github.ref, 'refs/tags/v')
         runs-on: ubuntu-latest
         permissions:

{execsql2-2.16.14 → execsql2-2.16.16}/.pre-commit-config.yaml

@@ -48,6 +48,7 @@ repos:
         exclude: |
           (?x)^(
             \.claude/.*|
+            AUDIT\.md|
             docs/api/.*|
             docs/reference/metacommands\.md|
             docs/guides/documentation\.md|

{execsql2-2.16.14 → execsql2-2.16.16}/CHANGELOG.md

@@ -13,6 +13,33 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.16.16] - 2026-05-02
+
+### Added
+
+- `--init-config` CLI flag to print a default `execsql.conf` template (with all options commented out and documented) to stdout. Use `execsql --init-config > execsql.conf` to bootstrap a configuration file.
+- `--no-system-cmd` CLI flag to disable SYSTEM_CMD/SHELL metacommand execution. Scripts that use SHELL will fail with a clear error when this flag is active. Also configurable via `allow_system_cmd = No` in `execsql.conf` `[config]` section. The library API exposes the same control via `allow_system_cmd=False`.
+
+### Changed
+
+- CLI `--help` output now logically groups related options: connection, encoding, import/export, execution, GUI, configuration, and information.
+- SYSTEM_CMD now uses `subprocess.run()` instead of the deprecated `subprocess.call()`.
+- `execsql.conf` template updated: added missing options (`use_keyring`, `gui_framework`, `allow_system_cmd`, `log_sql`, `max_log_size_mb`, `show_progress`, `import_progress_interval`, `macos_config_file`), fixed incorrect defaults (`password_prompt`, `new_db`, `scan_lines`), added DuckDB (`k`) to database types, modernized all comments.
+
+### Fixed
+
+- SYSTEM_CMD no longer wraps arguments containing `&` in spurious double quotes. The previous behavior (a Windows `cmd.exe` workaround inherited from the upstream monolith) injected literal `"` characters into subprocess arguments, which could cause commands to fail or behave unexpectedly on non-`cmd.exe` targets.
+
+______________________________________________________________________
+
+## [2.16.15] - 2026-05-02
+
+### Changed
+
+- Merged `SHOW SCRIPTS` and `SHOW SCRIPT <name>` into a single `SHOW SCRIPTS [<name>]` metacommand. Without a name, lists all registered scripts; with a name, shows detail for that script.
+
+______________________________________________________________________
+
 ## [2.16.14] - 2026-05-01
 
 ### Fixed

{execsql2-2.16.14 → execsql2-2.16.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.16.14
+Version: 2.16.16
 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

{execsql2-2.16.14 → execsql2-2.16.16}/docs/about/divergence.md

@@ -31,6 +31,8 @@ ______________________________________________________________________
 | `--lint`                        | Parse the script and perform static analysis without connecting to a database. Reports unmatched IF/ENDIF, LOOP/END LOOP, and BEGIN BATCH/END BATCH blocks (errors); potentially undefined `!!$VAR!!` references (warnings); missing INCLUDE file targets (warnings); and unknown `EXECUTE SCRIPT` targets (warnings). Variable analysis uses two passes so definition order does not matter. The linter descends into named script blocks reached via `EXECUTE SCRIPT` / `EXEC SCRIPT` / `RUN SCRIPT`, reads `SUB_INI` INI files at lint time, recognizes `SUB_EMPTY` / `SUB_ADD` / `SUB_APPEND` / `SUBDATA` as definitions, suppresses false warnings for `$COUNTER_N`, and auto-discovers built-in system variables from the installed source. Exits 0 if no errors, 1 if errors found. |
 | `--parse-tree`                  | Parse the script into an Abstract Syntax Tree and print a visual tree showing block nesting (IF/LOOP/BATCH/SCRIPT), source line ranges, compound conditions (ANDIF/ORIF), and all metacommands. Does not connect to a database or execute anything. Useful for understanding script structure and verifying the parser handles a script correctly.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `--list-plugins`                | List all discovered plugins (metacommands, exporters, importers) from Python entry points and exit. Plugins extend execsql via `execsql.metacommands`, `execsql.exporters`, and `execsql.importers` entry point groups.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--no-system-cmd`               | Disable the `SYSTEM_CMD` (SHELL) metacommand. Scripts that use SHELL will fail with a clear error. Also configurable via `allow_system_cmd = No` in `execsql.conf` `[config]` section, or `allow_system_cmd=False` in the library API.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--init-config`                 | Print a default `execsql.conf` template to stdout with all options commented out and documented. Redirect to a file to bootstrap a configuration: `execsql --init-config > execsql.conf`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 ### Export Formats
 
@@ -44,23 +46,22 @@ ______________________________________________________________________
 
 ### Metacommands
 
-| Metacommand            | Description                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `ASSERT`               | Evaluate a condition and raise an error (halting the script) if it is false. Supports all IF conditions. Optional quoted failure message. Skipped in false IF blocks.                                                                                                                                                                                                                                                    |
-| `BREAKPOINT`           | Pause script execution and drop into an interactive debug REPL. See [Debugging](#debugging) below for full details.                                                                                                                                                                                                                                                                                                      |
-| `CONFIG SHOW_PROGRESS` | Enable the Rich progress bar for IMPORT operations at runtime.                                                                                                                                                                                                                                                                                                                                                           |
-| `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                                                                                                                                                                                                                                                                    |
-| `PG_UPSERT`            | QA-checked, FK-dependency-ordered upserts from staging to base schema on PostgreSQL. Integrates [pg-upsert](https://pg-upsert.readthedocs.io/) as an optional dependency. Three modes: full pipeline, QA-only, and schema check. Supports `EXPORT_FAILURES`, `EXPORT_FORMAT`, `EXPORT_MAX_ROWS`, and `STRICT_COLUMNS` keywords. `STRICT_COLUMNS` forces all missing columns to be errors (requires `pg-upsert>=1.22.0`). |
-| `IMPORT … FROM JSON`   | Import a JSON file (array of objects or NDJSON) into a database table. Nested objects are flattened with dot-separated column names; arrays are stored as JSON strings.                                                                                                                                                                                                                                                  |
-| `SHOW SCRIPTS`         | List all registered SCRIPT definitions with parameter signatures and source locations. Includes scripts from INCLUDEEd files.                                                                                                                                                                                                                                                                                            |
-| `SHOW SCRIPT <name>`   | Show detail for a single registered SCRIPT: name, parameters (with defaults), source file/line range, and docstring.                                                                                                                                                                                                                                                                                                     |
+| Metacommand             | Description                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ASSERT`                | Evaluate a condition and raise an error (halting the script) if it is false. Supports all IF conditions. Optional quoted failure message. Skipped in false IF blocks.                                                                                                                                                                                                                                                    |
+| `BREAKPOINT`            | Pause script execution and drop into an interactive debug REPL. See [Debugging](#debugging) below for full details.                                                                                                                                                                                                                                                                                                      |
+| `CONFIG SHOW_PROGRESS`  | Enable the Rich progress bar for IMPORT operations at runtime.                                                                                                                                                                                                                                                                                                                                                           |
+| `CONFIG LOG_SQL`        | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                                                                                                                                                                                                                                                                    |
+| `PG_UPSERT`             | QA-checked, FK-dependency-ordered upserts from staging to base schema on PostgreSQL. Integrates [pg-upsert](https://pg-upsert.readthedocs.io/) as an optional dependency. Three modes: full pipeline, QA-only, and schema check. Supports `EXPORT_FAILURES`, `EXPORT_FORMAT`, `EXPORT_MAX_ROWS`, and `STRICT_COLUMNS` keywords. `STRICT_COLUMNS` forces all missing columns to be errors (requires `pg-upsert>=1.22.0`). |
+| `IMPORT … FROM JSON`    | Import a JSON file (array of objects or NDJSON) into a database table. Nested objects are flattened with dot-separated column names; arrays are stored as JSON strings.                                                                                                                                                                                                                                                  |
+| `SHOW SCRIPTS [<name>]` | Without a name, lists all registered SCRIPT definitions with parameter signatures and source locations. With a name, shows detail including parameters (with defaults), source file/line range, and docstring.                                                                                                                                                                                                           |
 
 ### SCRIPT Enhancements
 
-| Feature            | Description                                                                                                                                                                                                    |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Default parameters | `BEGIN SCRIPT load(schema, table, batch=1000)` — parameters with defaults can be omitted at call site. Required parameters must precede optional parameters.                                                   |
-| Docstrings         | Comments (`--` or `/* */`) immediately following `BEGIN SCRIPT` are captured as documentation. A blank line terminates the docstring. Displayed by `SHOW SCRIPT`, `SHOW SCRIPTS`, and `.scripts` REPL command. |
+| Feature            | Description                                                                                                                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Default parameters | `BEGIN SCRIPT load(schema, table, batch=1000)` — parameters with defaults can be omitted at call site. Required parameters must precede optional parameters.                                                 |
+| Docstrings         | Comments (`--` or `/* */`) immediately following `BEGIN SCRIPT` are captured as documentation. A blank line terminates the docstring. Displayed by `SHOW SCRIPTS <name>` and `.scripts <name>` REPL command. |
 
 ### Bug Fixes
 

{execsql2-2.16.14 → execsql2-2.16.16}/docs/reference/configuration.md

@@ -15,6 +15,12 @@ Configuration data is read from these files in the order listed above. Informati
 
 An explicit configuration file can also be specified with the `--config FILE` command-line option. This file is loaded **after** all four implicit search paths, so its values take precedence over system, user, script-directory, and working-directory config files. CLI arguments still override everything. The `--config` file may chain additional configs via its `[config]` section, just like any other config file.
 
+To generate a starter configuration file with all options commented out and documented, use:
+
+```bash
+execsql --init-config > execsql.conf
+```
+
 In addition, *execsql* will read additional configuration files if they are specified in any of the standard configuration files ([see below](#config_config)).
 
 Configuration files use the [INI](https://en.wikipedia.org/wiki/INI_file) file format. Section names are case sensitive and must be all in lowercase. Property names are not case sensitive. Property values are read as-is and may or may not be case sensitive, depending on their use. Comments can be included in configuration files; each comment line must start with the "#" character.
@@ -329,6 +335,9 @@ The section and property names that may be used in a configuration file are list
 `max_log_size_mb` { #max_log_size_mb }
 :   Maximum size of the log file in megabytes before it is rotated. When set to a positive integer, the log file is rotated to `.1` before a new run appends to it if the file size exceeds the configured threshold. The default is `0` (disabled — no rotation).
 
+`allow_system_cmd` { #allow_system_cmd }
+:   When set to "No", the `SYSTEM_CMD` (SHELL) metacommand is disabled. Any script that attempts to execute an OS command will fail with an error. The default is "Yes". This can also be set via the `--no-system-cmd` CLI flag or `allow_system_cmd=False` in the library API. See [Security — Disabling SYSTEM_CMD](security.md#disable_system_cmd) for details.
+
 `log_datavars` { #conf_log_datavars }
 :   A value of 'Yes' or 'No' to control whether data variables that are created by the [SELECT_SUB](metacommands.md#select_sub), [PROMPT SELECT_SUB](metacommands.md#prompt_selsub) and [PROMPT ACTION](metacommands.md#prompt_action) metacommands are written to *execsql*'s [log file](../guides/logging.md#logging). By default, this is set to 'Yes', so that all data variable assignments are logged. The performance of scripts that make extensive use of these metacommands (e.g., [Example 27](../guides/examples.md#example27)) can be improved by setting this to 'No'.
 

{execsql2-2.16.14 → execsql2-2.16.16}/docs/reference/metacommands.md

@@ -2767,12 +2767,18 @@ The numeric expression may consist of the simple algebraic operations of additio
 ## SHOW SCRIPTS { #show_scripts }
 
 ```
-SHOW SCRIPTS
+SHOW SCRIPTS [<name>]
 ```
 
-Lists all registered SCRIPT definitions with their parameter signatures and source locations. This is useful for discovering what scripts are available at runtime, especially when scripts are loaded from INCLUDEEd files whose paths are determined dynamically.
+Without a name, lists all registered SCRIPT definitions with their parameter signatures and source locations. With a name, shows detail for that script including parameters, source file/line range, and docstring.
 
-**Example output:**
+This is useful for discovering what scripts are available at runtime, especially when scripts are loaded from INCLUDEEd files whose paths are determined dynamically.
+
+**List all scripts:**
+
+```sql
+-- !x! SHOW SCRIPTS
+```
 
 ```
 Registered scripts (3):
@@ -2782,26 +2788,12 @@ Registered scripts (3):
   validate(schema, table)                      pipeline.sql:62-80
 ```
 
-Default parameter values are shown in the signature. Use `SHOW SCRIPT <name>` for full detail including docstrings.
-
-If no scripts are registered, prints `No scripts registered.`
-
-## SHOW SCRIPT { #show_script }
-
-```
-SHOW SCRIPT <name>
-```
-
-Shows detail for a single registered SCRIPT definition, including its parameter list (with required/optional status and defaults), source file/line range, and docstring.
-
-**Example:**
+**Show detail for one script:**
 
 ```sql
--- !x! SHOW SCRIPT load_data
+-- !x! SHOW SCRIPTS load_data
 ```
 
-**Example output:**
-
 ```
 Script: load_data(schema, table, batch_size=1000)
 Source: pipeline.sql:15-42
@@ -2813,7 +2805,7 @@ Parameters:
 Load data from staging into the target table.
 ```
 
-If the script is not found, prints `No script named '<name>' is registered.`
+If no scripts are registered, prints `No scripts registered.` If the named script is not found, prints `No script named '<name>' is registered.`
 
 !!! tip
     In the debug REPL, use `.scripts` to list all scripts or `.scripts <name>` to show detail for one script.

{execsql2-2.16.14 → execsql2-2.16.16}/docs/reference/security.md

@@ -21,6 +21,36 @@ Variable substitution is applied to the command string before execution, so any
 
 If `outdir` is derived from user input, validate or sanitize it before use in a `SYSTEM_CMD` command.
 
+!!! note "Windows `.bat`/`.cmd` files"
+
+    On Windows, when the target of a `SYSTEM_CMD` is a `.bat` or `.cmd` file, Windows may invoke `cmd.exe` to interpret it. In this case, the `&` character in arguments can be interpreted as a command separator by `cmd.exe`, even though the subprocess is not launched with `shell=True`. Avoid passing untrusted data containing `&` to batch files on Windows.
+
+### Disabling SYSTEM_CMD { #disable_system_cmd }
+
+To prevent scripts from executing OS commands entirely, use the `--no-system-cmd` CLI flag:
+
+```bash
+execsql --no-system-cmd script.sql mydb
+```
+
+Any script that uses `SYSTEM_CMD` or `SHELL` will fail with an error. This is useful for CI pipelines, shared execution environments, or running semi-trusted scripts where shell access is not appropriate.
+
+The same restriction can be set permanently in `execsql.conf`:
+
+```ini
+[config]
+allow_system_cmd = No
+```
+
+The library API provides the same control:
+
+```python
+import execsql
+result = execsql.run("script.sql", dsn="sqlite:///my.db", allow_system_cmd=False)
+```
+
+The `--no-system-cmd` CLI flag always takes precedence — if the flag is passed, `SYSTEM_CMD` is disabled regardless of the config file setting.
+
 ## Credential Handling { #credentials }
 
 ### Interactive password prompts

{execsql2-2.16.14 → execsql2-2.16.16}/extras/vscode-execsql/syntaxes/execsql.tmLanguage.json

@@ -93,7 +93,7 @@
     },
     "action-keywords": {
       "comment": "sub, write, execute script, export, etc.",
-      "match": "(?i)\\b(reset\\s+dialog_canceled|write\\s+create_table|export_metadata|pg_upsert\\s+check|sub_querystring|execute\\s+script|append\\s+script|extend\\s+script|reset\\s+counter|export\\s+query|pg_upsert\\s+qa|show\\s+scripts|sub_tempfile|write\\s+script|import_file|set\\s+counter|show\\s+script|sub_decrypt|sub_encrypt|autocommit|breakpoint|copy\\s+query|disconnect|select_sub|sub_append|system_cmd|pg_upsert|pg_vacuum|sub_empty|sub_local|connect|include|max_int|rm_file|subdata|sub_add|sub_ini|assert|export|import|rm_sub|debug|email|serve|write|copy|log|run|sub|use|zip|cd)\\b",
+      "match": "(?i)\\b(reset\\s+dialog_canceled|write\\s+create_table|export_metadata|pg_upsert\\s+check|sub_querystring|execute\\s+script|append\\s+script|extend\\s+script|reset\\s+counter|export\\s+query|pg_upsert\\s+qa|show\\s+scripts|sub_tempfile|write\\s+script|import_file|set\\s+counter|sub_decrypt|sub_encrypt|autocommit|breakpoint|copy\\s+query|disconnect|select_sub|sub_append|system_cmd|pg_upsert|pg_vacuum|sub_empty|sub_local|connect|include|max_int|rm_file|subdata|sub_add|sub_ini|assert|export|import|rm_sub|debug|email|serve|write|copy|log|run|sub|use|zip|cd)\\b",
       "name": "keyword.other.execsql"
     },
     "config-event-keywords": {

{execsql2-2.16.14 → execsql2-2.16.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.16.14"
+version = "2.16.16"
 description = "Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE.txt" }
@@ -165,7 +165,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.16.14"
+current_version = "2.16.16"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{execsql2-2.16.14 → execsql2-2.16.16}/src/execsql/api.py

@@ -316,6 +316,7 @@ def run(
     encoding: str = "utf-8",
     halt_on_error: bool = True,
     new_db: bool = False,
+    allow_system_cmd: bool = True,
 ) -> ScriptResult:
     """Execute a SQL script and return the result.
 
@@ -337,6 +338,8 @@ def run(
             error.  If ``False``, capture errors and continue.
         new_db: If ``True``, create the database if it does not exist
             (SQLite, PostgreSQL, DuckDB).
+        allow_system_cmd: If ``False``, the SYSTEM_CMD (SHELL) metacommand
+            is disabled and will raise an error if encountered.
 
     Returns:
         A :class:`ScriptResult` with execution outcome, timing, errors,
@@ -434,6 +437,7 @@ def run(
     ctx.subvars = subvars
     ctx.status = StatObj()
     ctx.status.halt_on_err = halt_on_error
+    conf.allow_system_cmd = allow_system_cmd
     ctx.conf = conf
 
     # Capture output to a buffer (suppress stdout/stderr)