execsql2 2.12.1__tar.gz → 2.12.2__tar.gz

execsql2-2.12.2/.claude/agents/liaison.md

@@ -0,0 +1,107 @@
+---
+name: The Liaison
+description: Integration specialist for pg-upsert and execsql2. Tracks the pg-upsert codebase (../pg-upsert), designs the optional dependency integration, and owns the UPSERT metacommand. Reads both codebases — writes only in execsql2.
+model: sonnet
+color: yellow
+---
+
+You are a senior Python engineer who specializes in integrating the **pg-upsert** library with the **execsql2** project. You are the bridge between two codebases maintained by the same author:
+
+- **execsql2** — `/Users/cgrant/GitHub/geocoug/execsql/` (this repo)
+- **pg-upsert** — `/Users/cgrant/GitHub/geocoug/pg-upsert/` (sibling repo)
+
+Your job is to keep the integration plan current, design the `UPSERT` metacommand, and ensure changes in either codebase don't break the integration path.
+
+## Expertise
+
+You have deep, working knowledge of:
+
+**pg-upsert internals:** The `PgUpsert` class (QA checks: null, PK, FK, check constraint validation), `PostgresDB` connection wrapper, the staging-to-base upsert workflow, topological table ordering, the `ups_control` temporary table, and the `psycopg2.sql` parameterized SQL generation patterns.
+
+**execsql2 extension points:** The metacommand dispatch system (`MetaCommandList`, `build_dispatch_table()`, `x_*` handlers), `DatabasePool` connection management, substitution variables (`SubVarSet`), transaction/autocommit model, the `PostgresDatabase` adapter, and the existing upsert SQL templates in `templates/pg_upsert.sql`.
+
+**Integration patterns:** Optional dependency detection (`importlib.util.find_spec`), connection sharing between libraries, adapter patterns for bridging different transaction models, and graceful degradation when an optional package is not installed.
+
+______________________________________________________________________
+
+## First Actions (always, before doing any work)
+
+1. **Read `.claude/project_context.md`** — load the execsql2 module layout and architectural overview.
+2. **Read your briefing** if one exists at `.claude/comms/briefings/liaison-*.md` — follow the DBA's specific instructions.
+3. **Read the integration plan** at `../pg-upsert/.claude/plans/refactor-and-execsql-integration.md` — this is the canonical plan. Understand the current phase and what's been decided.
+4. **Check pg-upsert's current state** — read `../pg-upsert/src/pg_upsert/upsert.py` and `../pg-upsert/src/pg_upsert/postgres.py` to understand the latest API surface. pg-upsert is under active refactoring; the API may have changed since the plan was written.
+5. **Check execsql2's metacommand system** — read `src/execsql/metacommands/dispatch.py` to understand registration patterns.
+
+______________________________________________________________________
+
+## Key Design Decisions (established)
+
+These have been agreed upon. Do not revisit unless the human asks:
+
+1. **pg-upsert is an optional dependency** — execsql2 must work without it installed. The `UPSERT` metacommand raises a clear error if pg-upsert is missing.
+2. **Connection sharing** — the metacommand passes execsql's existing `psycopg2` connection to `PgUpsert(conn=...)`. No second connection.
+3. **Results map to substitution variables** — upsert stats (rows updated, inserted, QA errors) are exposed as `!!$UPSERT_*!!` substitution variables.
+4. **execsql's transaction model governs** — the metacommand respects execsql's `AUTOCOMMIT ON/OFF` state, not pg-upsert's `do_commit` flag.
+5. **No Tkinter dependency** — the interactive GUI is not used when called from execsql. QA results go to execsql's logging/debug REPL instead.
+
+______________________________________________________________________
+
+## pg-upsert API Surface (reference)
+
+The integration depends on these pg-upsert interfaces. If any change, the integration plan must be updated.
+
+```python
+# Core class — this is what the metacommand will call
+PgUpsert(
+    conn=psycopg2_connection,  # Shared from execsql
+    tables=["t1", "t2"],
+    staging_schema="staging",
+    base_schema="public",
+    do_commit=False,           # execsql controls commits
+    interactive=False,         # No GUI from execsql
+    upsert_method="upsert",   # "upsert" | "update" | "insert"
+    exclude_cols=["col1"],
+    exclude_null_check_cols=["col2"],
+)
+
+# Methods the metacommand will call
+.qa_all()       # Run all QA checks, returns self
+.upsert_all()   # Run upsert on all tables, returns self
+.commit()       # Commit/rollback based on do_commit + qa_passed
+.run()          # qa_all() → upsert_all() → commit()
+
+# State the metacommand will read
+.qa_passed      # bool — did all QA checks pass?
+.control_table  # str — name of temp table with per-table results
+```
+
+______________________________________________________________________
+
+## What to Produce
+
+Depending on the task, you may produce:
+
+1. **Integration status reports** — what's changed in pg-upsert, what that means for execsql integration
+2. **Metacommand design** — regex patterns, handler signatures, SQL syntax for `UPSERT` metacommand
+3. **Implementation code** — `src/execsql/metacommands/upsert.py` and dispatch registration
+4. **Compatibility notes** — API changes in pg-upsert that require adaptation
+5. **Test specifications** — what the QA agent should test for the integration
+
+______________________________________________________________________
+
+## Syndicate Protocol
+
+When working as part of the SQL Syndicate:
+
+1. Read your briefing from `.claude/comms/briefings/liaison-*.md`
+2. Do your research across both codebases
+3. Write your report to `.claude/comms/reports/liaison-{YYYY-MM-DD}.md`
+4. Write integration artifacts to `.claude/plans/` (for design) or `.claude/patches/` (for implementation)
+
+## Constraints
+
+- **Writes only in execsql2.** You may read `../pg-upsert/` freely but never modify files there.
+- **pg-upsert is a moving target.** Always re-read the current pg-upsert source before making claims about its API — don't rely on cached knowledge.
+- **Optional means optional.** Never add pg-upsert to execsql2's required dependencies. Use `extras_require` / optional dependency groups.
+- **Preserve existing upsert templates.** The SQL templates in `templates/pg_upsert.sql` must continue to work. The metacommand is an alternative, not a replacement.
+- Follow all execsql2 project constraints from CLAUDE.md (ruff, Python 3.10+, coverage floor, changelog, docs, divergence tracking).

{execsql2-2.12.1 → execsql2-2.12.2}/CHANGELOG.md

@@ -13,6 +13,18 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.12.2] - 2026-04-02
+
+### Added
+
+- Documentation: keyring setup guide for headless Linux servers (encrypted and plaintext file backends) in the Security reference page, with a cross-reference from the Installation page.
+
+### Changed
+
+- `ASSERT` failures now report `**** Assertion failed.` instead of `**** Error in metacommand.` to distinguish intentional script-level checks from actual metacommand errors.
+
+______________________________________________________________________
+
 ## [2.12.1] - 2026-04-02
 
 ### Changed

{execsql2-2.12.1 → execsql2-2.12.2}/CLAUDE.md

@@ -22,6 +22,7 @@ A multi-agent system where specialized agents collaborate to improve, extend, de
 - `.claude/docs-drafts/` — Scribe's documentation drafts
 - `.claude/releases/` — Herald's release notes and changelog entries
 - `.claude/state/` — Shared state (current phase, active task, agent status)
+- `../pg-upsert/.claude/plans/` — pg-upsert integration plan (read by The Liaison)
 
 ## Communication Protocol
 

{execsql2-2.12.1 → execsql2-2.12.2}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.12.1
+Version: 2.12.2
 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
 Project-URL: Issues, https://github.com/geocoug/execsql/issues
 Author-email: Dreas Nielsen <cortice@tutanota.com>

{execsql2-2.12.1 → execsql2-2.12.2}/docs/about/divergence.md

@@ -174,6 +174,7 @@ All 33 mutable runtime globals in `state.py` have been consolidated into a `Runt
 
 - **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`.
+- **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`.
 
 ______________________________________________________________________
 

{execsql2-2.12.1 → execsql2-2.12.2}/docs/getting-started/installation.md

@@ -30,3 +30,7 @@ pip install "execsql2[all]"         # Everything
 ```
 
 In addition to the *execsql* program itself, additional Python libraries may need to be installed to use *execsql* with specific types of DBMSs and spreadsheets. The additional libraries that may be needed are listed in the [Requirements](requirements.md#requirements) section.
+
+!!! tip "Keyring on headless Linux"
+
+    If you install `execsql2[auth]` on a headless Linux server (no desktop environment), the keyring backend needs manual configuration. See [Keyring Platform Setup](../reference/security.md#keyring_setup) for instructions.

{execsql2-2.12.1 → execsql2-2.12.2}/docs/reference/metacommands.md

@@ -56,7 +56,9 @@ ASSERT <condition> "<failure message>"
 ASSERT <condition> '<failure message>'
 ```
 
-Evaluates `<condition>` using the same expression engine as [IF](#if_cmd). If the condition is `True`, execution continues silently (and the result is written to the log). If the condition is `False`, an error is raised with the provided failure message. If no message is supplied, the default message is `Assertion failed: <condition>`.
+Evaluates `<condition>` using the same expression engine as [IF](#if_cmd). If the condition is `True`, execution continues silently (and the result is written to the log). If the condition is `False`, an assertion error is raised with the provided failure message. If no message is supplied, the default message is `Assertion failed: <condition>`.
+
+A failed assertion produces `**** Assertion failed.` (not `**** Error in metacommand.`) to make it clear that the script's own check caught a problem, not that execsql encountered an internal error.
 
 When [HALT_ON_METACOMMAND_ERROR](#config) is `ON` (the default), a failed assertion halts the script. When it is `OFF`, execution continues after the failure is logged.
 

{execsql2-2.12.1 → execsql2-2.12.2}/docs/reference/security.md

@@ -29,7 +29,7 @@ When execsql needs a database password and none is stored or configured, it prom
 
 ### OS credential store (keyring)
 
-When the optional `keyring` package is installed (`pip install execsql2[auth]`), execsql checks the OS credential store before prompting. After a successful interactive prompt, the password is automatically stored for future use. Supported stores are macOS Keychain, Windows Credential Manager, and Linux SecretService. Keyring service names follow the pattern:
+When the optional `keyring` package is installed (`pip install execsql2[auth]`), execsql checks the OS credential store before prompting. After a successful interactive prompt, the password is automatically stored for future use. Keyring service names follow the pattern:
 
 ```text
 execsql/<db_type>/<server>/<database>
@@ -37,6 +37,64 @@ execsql/<db_type>/<server>/<database>
 
 To disable keyring integration, set `use_keyring = No` in the `[connect]` section of `execsql.conf`.
 
+#### Platform setup { #keyring_setup }
+
+**macOS** — Works out of the box. Keyring uses the macOS Keychain automatically.
+
+**Windows** — Works out of the box. Keyring uses the Windows Credential Manager automatically.
+
+**Linux (desktop with GNOME/KDE)** — Works out of the box if a SecretService provider (GNOME Keyring or KWallet) is running.
+
+**Linux (headless / remote / server)** — No secret service is typically available, so keyring silently fails to store passwords. You need to configure a file-based backend. There are two options:
+
+##### Option A: Encrypted file backend (recommended) { #keyring_encrypted }
+
+Passwords are stored encrypted on disk. Requires a master password the first time keyring is used per session.
+
+```bash
+pip install keyrings.alt pycryptodome
+mkdir -p ~/.config/python_keyring
+cat > ~/.config/python_keyring/keyringrc.cfg << 'EOF'
+[backend]
+default-keyring=keyrings.alt.file.EncryptedKeyring
+EOF
+```
+
+The encrypted keyring file is stored at `~/.local/share/python_keyring/crypted_pass.cfg`. You will be prompted for a master password once per session (e.g., when you first run execsql after logging in).
+
+##### Option B: Plaintext file backend (no prompts) { #keyring_plaintext }
+
+Passwords are stored in plain text on disk. No master password is needed — execsql will never prompt for a password after the first successful entry.
+
+```bash
+pip install keyrings.alt
+mkdir -p ~/.config/python_keyring
+cat > ~/.config/python_keyring/keyringrc.cfg << 'EOF'
+[backend]
+default-keyring=keyrings.alt.file.PlaintextKeyring
+EOF
+```
+
+Passwords are stored at `~/.local/share/python_keyring/keyring_pass.cfg`. Restrict access to this file:
+
+```bash
+chmod 600 ~/.local/share/python_keyring/keyring_pass.cfg
+```
+
+!!! warning "Plaintext storage"
+
+    The plaintext backend stores passwords without encryption. Only use this on machines where the filesystem is already secured (encrypted disk, single-user access, restricted permissions). Prefer the encrypted backend when possible.
+
+##### Verifying keyring setup { #keyring_verify }
+
+After configuring a backend, verify it works:
+
+```bash
+python -c "import keyring; keyring.set_password('test', 'user', 'pw'); print(keyring.get_password('test', 'user'))"
+```
+
+This should print `pw` without errors. If it does, the next time execsql prompts for a database password, it will store it and skip the prompt on future runs.
+
 ### `enc_password` in execsql.conf
 
 !!! warning "Obfuscation only — not encryption"

{execsql2-2.12.1 → execsql2-2.12.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.12.1"
+version = "2.12.2"
 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" }
@@ -91,6 +91,7 @@ execsql = "execsql.cli:_legacy_main"
 execsql-format = "execsql.format:main"
 
 [project.urls]
+Homepage = "https://execsql2.readthedocs.io"
 Repository = "https://github.com/geocoug/execsql"
 Issues = "https://github.com/geocoug/execsql/issues"
 
@@ -158,7 +159,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.12.1"
+current_version = "2.12.2"
 commit = true
 commit_args = "--no-verify"
 tag = true

{execsql2-2.12.1 → execsql2-2.12.2}/src/execsql/exceptions.py

@@ -132,6 +132,8 @@ class ErrInfo(ExecSqlError):
 
         if self.type == "db":
             self.error_message = "**** Error in SQL statement."
+        elif self.type == "assert":
+            self.error_message = "**** Assertion failed."
         elif self.type == "cmd":
             self.error_message = "**** Error in metacommand."
         elif self.type == "log":

{execsql2-2.12.1 → execsql2-2.12.2}/src/execsql/metacommands/control.py

@@ -66,7 +66,7 @@ def x_assert(**kwargs: Any) -> None:
         if _state.exec_log is not None:
             _state.exec_log.log_user_msg(f"ASSERT passed: {condition}")
     else:
-        raise ErrInfo(type="cmd", other_msg=message)
+        raise ErrInfo(type="assert", other_msg=message)
 
 
 def x_if(**kwargs: Any) -> None:

{execsql2-2.12.1 → execsql2-2.12.2}/tests/metacommands/test_assert.py

@@ -71,9 +71,22 @@ class TestXAssertRaisesOnFalseCondition:
         with (
             patch.object(_state, "xcmd_test", return_value=False),
             patch.object(_state, "exec_log", mock_log),
-            pytest.raises(ErrInfo),
+            pytest.raises(ErrInfo) as exc_info,
         ):
             x_assert(condtest="ROWCOUNT > 0", message=None, metacommandline="ASSERT ROWCOUNT > 0")
+        assert exc_info.value.type == "assert"
+
+    def test_false_condition_eval_err_says_assertion_failed(self) -> None:
+        mock_log = _make_exec_log()
+        with (
+            patch.object(_state, "xcmd_test", return_value=False),
+            patch.object(_state, "exec_log", mock_log),
+            pytest.raises(ErrInfo) as exc_info,
+        ):
+            x_assert(condtest="ROWCOUNT > 0", message='"expected rows"', metacommandline="ASSERT ROWCOUNT > 0")
+        err_msg = exc_info.value.eval_err()
+        assert err_msg.startswith("**** Assertion failed.")
+        assert "expected rows" in err_msg
 
     def test_false_condition_with_double_quoted_message(self) -> None:
         mock_log = _make_exec_log()

{execsql2-2.12.1 → execsql2-2.12.2}/tests/test_exceptions.py

@@ -83,6 +83,7 @@ class TestErrInfo:
         "err_type,expected_text",
         [
             ("db", "**** Error in SQL statement."),
+            ("assert", "**** Assertion failed."),
             ("cmd", "**** Error in metacommand."),
             ("log", "**** Error in logging."),
             ("error", "**** General error."),

{execsql2-2.12.1 → execsql2-2.12.2}/uv.lock

@@ -657,7 +657,7 @@ wheels = [
 
 [[package]]
 name = "execsql2"
-version = "2.12.1"
+version = "2.12.2"
 source = { editable = "." }
 dependencies = [
     { name = "rich" },