dbctl 0.7.4__tar.gz → 0.7.8__tar.gz

{dbctl-0.7.4 → dbctl-0.7.8}/CHANGELOG.md

@@ -5,6 +5,86 @@ All notable changes to this project will be documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.7] — 2026-08-10
+
+### Fixed
+
+- **`ruff format` failed in CI** on the v0.7.6 commit — three files
+  (`dbctl/cli.py`, `dbctl/runtime.py`, `tests/test_execute.py`) had
+  manually-typed signatures that fit on one line per `ruff format`'s
+  rules but were wrapped in the source. Reformatted to the canonical
+  layout (`def opened_engine(ctx: click.Context, canonical: str, conn:
+  Connection) -> Iterator[OpenedStub]:` on one line; same for the
+  `execute_cmd` callback signature and the inline-URL error `print`
+  call). Re-running `uv run ruff format --check dbctl tests` is now
+  clean and `make format` is a no-op on top of this commit.
+- **Typo in `docs/execute.md`** — `# dduckdb inline URL` comment →
+  `# duckdb inline URL`.
+- **README project layout** now lists `execute.md` under `docs/` so the
+  new reference page is discoverable from the layout block.
+
+No behaviour change; re-running `dbctl execute --help` produces the
+same output as v0.7.6.
+
+## [0.7.6] — 2026-08-10
+
+### Added
+
+- **`dbctl execute`** — run ad-hoc SQL without declaring an operation in
+  `operations.yaml`. The new top-level verb takes a connection name *or* a
+  full SQLAlchemy URL, the SQL string as a single positional argument, and
+  the short option set the existing operation dispatch uses:
+
+  ```bash
+  dbctl execute -c pg -o json "SELECT * FROM users"
+  dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+  dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+  dbctl execute -c pg -o yaml "SELECT * FROM users LIMIT 10"
+  ```
+
+  Behaviour:
+
+  - **`-c` / `--connection`** accepts a registered connection name /
+    alias (resolved via `connections.yaml`) **or** a full SQLAlchemy URL
+    (detected by the presence of `://`). Inline URLs build a transient
+    `direct` Connection so the SSM/SSH password-source plumbing, native-lib
+    install hints, and `connect_args` (connect-timeout, Windows SSO) all
+    apply uniformly.
+  - **`-o` / `--output`** chooses `table` (default) / `json` / `csv` /
+    `yaml` for SELECT-shaped results, exactly like declared `fetch` ops.
+  - The SQL is auto-classified by its first verb: `SELECT` / `WITH` /
+    `SHOW` / `EXPLAIN` / `DESCRIBE` / `PRAGMA` / `VALUES` / `TABLE` runs
+    as a query (rendered via `--output`); anything else runs as DML
+    (INSERT / UPDATE / DELETE / CREATE / DROP / ALTER / ...) inside
+    `engine.begin()`.
+  - DML respects the connection's `safety.confirm` (dry-run-by-default
+    unless `--apply`), `safety.read_only` (DML blocked with exit 6), and
+    prompts before commit unless `--yes` / `-y` is passed — exactly the
+    same gate as a declared `mode: execute` operation. Inline URLs
+    default to `safety.confirm: true`.
+  - DDL that returns `rowcount = -1` (CREATE TABLE, DROP, ...) is rendered
+    as `OK in <ms>ms` instead of the misleading `OK -1 row(s) affected`.
+    Real INSERT/UPDATE/DELETE row counts are still reported.
+  - Every run is appended to `~/.dbctl/history.jsonl` as
+    `operation="execute"` with the SQL (truncated to 500 chars) in the
+    `params.sql` field, so it shows up under `dbctl history list`. The
+    audit `connection` field is the canonical connection name, or the
+    literal `<inline>` token for inline URL runs.
+  - `--show-sql` prints the resolved SQL before executing; `--` separates
+    options from positional SQL that begins with a dash (Click would
+    otherwise treat the leading dash as an unknown option).
+  - The new verb is registered as a top-level static command alongside
+    `connections` / `operations` / `doctor` / `init` / `history` /
+    `tunnel` / `ui`, so shell completion picks it up.
+
+  This closes the long-standing "no ad-hoc query command" gap without
+  weakening the declarative operation registry: the declared
+  `operations.yaml` model remains the recommended way to make "what can
+  be run against this DB" discoverable from a versioned file, while
+  `execute` covers the exploratory / break-glass path the TUI already
+  serves — both share the same tunnel / safety / audit plumbing so every
+  run is still logged and policy-checked.
+
 ## [0.7.4] — 2026-08-10
 
 ### Added

{dbctl-0.7.4 → dbctl-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: dbctl
-Version: 0.7.4
+Version: 0.7.8
 Summary: Generic CLI to monitor, control, and administer multiple databases via SSM, SSH, or direct connection.
 Author: dbctl contributors
 License: MIT
@@ -122,9 +122,9 @@ the same params.
 
 ## Why "the operations are declarative"
 
-There is **no ad-hoc query command**. To run SQL through `dbctl` you must
-declare an operation in `operations.yaml` first — its name, its parameters
-(with types, descriptions, positional vs keyword), its SQL, and its mode
+The recommended path for permanent, repeatable work is to declare an
+operation in `operations.yaml` first — its name, its parameters (with
+types, descriptions, positional vs keyword), its SQL, and its mode
 (`execute` / `fetch` / `fetch_one` / `script` / `upsert` for single-DB;
 `diff` / `compare` / `copy` / `sync` / `validate` / `replay` for multi-DB).
 The CLI then synthesises a Click subcommand per operation, so:
@@ -135,7 +135,18 @@ The CLI then synthesises a Click subcommand per operation, so:
 - the audit log is queryable by operation name (`dbctl history list`).
 
 This keeps "what can be run against this DB" discoverable from a versioned
-config file, instead of buried in shell history.
+config file, instead of buried in shell history. For exploratory / break-glass
+SQL — the path the TUI serves — `dbctl execute` (added in v0.7.6) runs
+ad-hoc SQL through the same tunnel / safety / audit plumbing without
+requiring a declared operation:
+
+```bash
+dbctl execute -c pg -o json "SELECT * FROM users"
+dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+```
+
+See [`docs/execute.md`](docs/execute.md) for the full reference.
 
 ## Install (uv)
 
@@ -188,6 +199,12 @@ dbctl pg add-user stephen 12 --show-sql        # dry-run (prints SQL)
 dbctl pg add-user stephen 12 --apply --yes     # commit (no prompt)
 dbctl pg increase-credits alice 10 --apply -y    # +10% on alice's credits
 
+# ad-hoc SQL without declaring an operation (since v0.7.6):
+dbctl execute -c pg -o json "SELECT * FROM users"
+dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+dbctl execute -c pg -o yaml -- "SELECT * FROM users WHERE name='-alice'"  # SQL starting with a dash needs `--`
+
 # multi-DB modes (operation-first, preferred since v0.6):
 dbctl user-count pg my                        # multi-DB diff
 dbctl compare-credits pg my Daily
@@ -414,6 +431,7 @@ dbctl/
 ├── docs/
 │   ├── connections.md      # connections.yaml reference
 │   ├── operations.md       # operations.yaml reference
+│   ├── execute.md          # dbctl execute (ad-hoc SQL) reference
 │   ├── tui.md              # dbctl ui reference (keybindings, dialect SQL)
 │   └── DESIGN.md           # architecture and design decisions
 └── dbctl/

{dbctl-0.7.4 → dbctl-0.7.8}/README.md

@@ -86,9 +86,9 @@ the same params.
 
 ## Why "the operations are declarative"
 
-There is **no ad-hoc query command**. To run SQL through `dbctl` you must
-declare an operation in `operations.yaml` first — its name, its parameters
-(with types, descriptions, positional vs keyword), its SQL, and its mode
+The recommended path for permanent, repeatable work is to declare an
+operation in `operations.yaml` first — its name, its parameters (with
+types, descriptions, positional vs keyword), its SQL, and its mode
 (`execute` / `fetch` / `fetch_one` / `script` / `upsert` for single-DB;
 `diff` / `compare` / `copy` / `sync` / `validate` / `replay` for multi-DB).
 The CLI then synthesises a Click subcommand per operation, so:
@@ -99,7 +99,18 @@ The CLI then synthesises a Click subcommand per operation, so:
 - the audit log is queryable by operation name (`dbctl history list`).
 
 This keeps "what can be run against this DB" discoverable from a versioned
-config file, instead of buried in shell history.
+config file, instead of buried in shell history. For exploratory / break-glass
+SQL — the path the TUI serves — `dbctl execute` (added in v0.7.6) runs
+ad-hoc SQL through the same tunnel / safety / audit plumbing without
+requiring a declared operation:
+
+```bash
+dbctl execute -c pg -o json "SELECT * FROM users"
+dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+```
+
+See [`docs/execute.md`](docs/execute.md) for the full reference.
 
 ## Install (uv)
 
@@ -152,6 +163,12 @@ dbctl pg add-user stephen 12 --show-sql        # dry-run (prints SQL)
 dbctl pg add-user stephen 12 --apply --yes     # commit (no prompt)
 dbctl pg increase-credits alice 10 --apply -y    # +10% on alice's credits
 
+# ad-hoc SQL without declaring an operation (since v0.7.6):
+dbctl execute -c pg -o json "SELECT * FROM users"
+dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+dbctl execute -c pg -o yaml -- "SELECT * FROM users WHERE name='-alice'"  # SQL starting with a dash needs `--`
+
 # multi-DB modes (operation-first, preferred since v0.6):
 dbctl user-count pg my                        # multi-DB diff
 dbctl compare-credits pg my Daily
@@ -378,6 +395,7 @@ dbctl/
 ├── docs/
 │   ├── connections.md      # connections.yaml reference
 │   ├── operations.md       # operations.yaml reference
+│   ├── execute.md          # dbctl execute (ad-hoc SQL) reference
 │   ├── tui.md              # dbctl ui reference (keybindings, dialect SQL)
 │   └── DESIGN.md           # architecture and design decisions
 └── dbctl/

{dbctl-0.7.4 → dbctl-0.7.8}/dbctl/cli.py

@@ -20,10 +20,12 @@ from typing import Any
 import click
 import yaml
 from rich.table import Table
+from sqlalchemy import text
+from sqlalchemy.engine import Engine
 from sqlalchemy.exc import SQLAlchemyError
 
 from dbctl import __version__
-from dbctl.config import Operation, OutputFormat, Param, ParamType
+from dbctl.config import Connection, Operation, OutputFormat, Param, ParamType
 from dbctl.operations import by_scope
 from dbctl.operations import resolve as resolve_op
 from dbctl.runtime import (
@@ -1020,7 +1022,17 @@ def _aliases(conns):
 
 def _root_list(ctx: click.Context) -> list[str]:
     conns, ops = registries(ctx)
-    static = ["connections", "operations", "status", "doctor", "init", "history", "tunnel", "ui"]
+    static = [
+        "connections",
+        "operations",
+        "status",
+        "doctor",
+        "init",
+        "history",
+        "tunnel",
+        "ui",
+        "execute",
+    ]
     # multi-op operation-first top-level commands + deprecated verb-first groups
     multi_ops = {n for n, o in ops.items() if o.scope.value == "multi"}
     multi_modes = {o.mode.value for o in ops.values() if o.scope.value == "multi"}
@@ -1040,6 +1052,7 @@ def _root_get(ctx: click.Context, name: str):
         "history": history_cmd,
         "tunnel": tunnel_cmd,
         "ui": ui_cmd,
+        "execute": execute_cmd,
     }
     if name in static:
         return static[name]
@@ -1339,6 +1352,278 @@ def ui_cmd(ctx):
     DbctlApp(profile=ctx.obj.get("profile")).run()
 
 
+# --------------------------------------------------------------------------- #
+# ad-hoc SQL: `dbctl execute`
+# --------------------------------------------------------------------------- #
+# A read-only SQL verb is one whose first word matches this set. "VALUES"
+# / "TABLE" are SQL-standard row-set constructors; "WITH" is a CTE head;
+# the rest are dialect-specific introspection verbs (EXPLAIN / DESCRIBE /
+# SHOW / PRAGMA / DESC) that return a result set the user wants to render
+# like a SELECT.
+_READ_VERBS = {
+    "SELECT",
+    "WITH",
+    "VALUES",
+    "TABLE",
+    "SHOW",
+    "EXPLAIN",
+    "DESC",
+    "DESCRIBE",
+    "PRAGMA",
+}
+
+
+def _sql_is_read(sql: str) -> bool:
+    head = sql.strip().lstrip("(").strip().split(None, 1)
+    return bool(head) and head[0].upper() in _READ_VERBS
+
+
+def _make_inline_connection(url: str) -> Connection:
+    """Build a transient ``Connection`` from a full SQLAlchemy URL.
+
+    Used by ``dbctl execute -c "<sqlalchemy url>"``. The placeholder
+    ``direct`` block is required by the ``Connection`` validator even in
+    URL mode, but it's never *used* — ``build_engine`` honours ``url:``
+    over host/port. Default safety mirrors the bundled dev connections:
+    DML is dry-run-by-default unless ``--apply`` is supplied.
+    """
+    from dbctl.config import Connection
+
+    return Connection.model_validate(
+        {
+            "type": "direct",
+            "direct": {"host": "localhost", "port": 1},
+            "url": url,
+            "healthcheck": {"query": "SELECT 1", "timeout_seconds": 5},
+            "safety": {"confirm": True, "read_only": False},
+        }
+    )
+
+
+def _do_execute_ad_hoc(
+    *,
+    engine: Engine,
+    sql: str,
+    is_select: bool,
+    output_fmt: str,
+    canonical: str,
+    profile: str | None,
+    actor: str | None,
+) -> None:
+    """Run an ad-hoc SQL string against ``engine`` and render the result.
+
+    SELECT-shaped SQL runs in a read-only ``engine.connect()`` and renders
+    via ``render_rows`` (table / json / yaml / csv). DML runs inside
+    ``engine.begin()`` and reports rows-affected with a green OK line. Any
+    SQLAlchemy / runtime error is rendered via ``fmt_db_error`` (one-line
+    friendly message) and exits 1 — matching the declared-op execution
+    path's behaviour. Every run is appended to the audit log as
+    ``operation="execute"`` with the SQL (truncated to 500 chars) in
+    ``params`` so it shows up under ``dbctl history list``.
+    """
+    from dbctl.audit import append
+    from dbctl.reports import render_rows
+
+    started = time.monotonic()
+    mode_label = "fetch" if is_select else "execute"
+    audit_sql = sql[:500]
+    rows_affected: int | None = None
+    try:
+        if is_select:
+            with engine.connect() as c:
+                rows = [dict(r) for r in c.execute(text(sql)).mappings()]
+            render_rows(rows, output_fmt, title=canonical)
+        else:
+            with engine.begin() as c:
+                result = c.execute(text(sql))
+                rows_affected = result.rowcount
+            elapsed = (time.monotonic() - started) * 1000.0
+            # Many drivers report rowcount = -1 (unknown) for DDL and for
+            # statements that don't naturally expose a row count (CREATE
+            # TABLE, DROP TABLE, ALTER, ...). Render a cleaner line instead
+            # of the misleading "OK -1 row(s) affected".
+            if rows_affected is not None and rows_affected >= 0:
+                console.print(f"[green]OK[/green] {rows_affected} row(s) affected in {elapsed:.1f}ms")
+            else:
+                console.print(f"[green]OK[/green] in {elapsed:.1f}ms")
+    except (RuntimeError, SQLAlchemyError) as e:
+        append(
+            profile=profile,
+            connection=canonical,
+            operation="execute",
+            params={"sql": audit_sql},
+            mode=mode_label,
+            status="error",
+            duration_ms=(time.monotonic() - started) * 1000.0,
+            actor=actor,
+        )
+        err_console.print(f"[red]{_fmt_db_error(e)}[/red]")
+        raise SystemExit(1)
+    append(
+        profile=profile,
+        connection=canonical,
+        operation="execute",
+        params={"sql": audit_sql},
+        mode=mode_label,
+        status="ok",
+        rows_affected=rows_affected,
+        duration_ms=(time.monotonic() - started) * 1000.0,
+        actor=actor,
+    )
+
+
+@click.command("execute", context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "-c",
+    "--connection",
+    "connection_str",
+    required=True,
+    metavar="CONN-OR-URL",
+    help=(
+        "Either a connection name / alias from connections.yaml, or a full "
+        "SQLAlchemy URL (e.g. "
+        "'postgresql+psycopg://user:pass@host:5432/db'). "
+        "URLs are detected by the presence of '://'."
+    ),
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_fmt",
+    type=click.Choice([m.value for m in OutputFormat]),
+    default="table",
+    show_default=True,
+    help="Output format for SELECT-shaped results (ignored for DML).",
+)
+@click.option(
+    "--apply",
+    is_flag=True,
+    help="Commit any DML (default is a dry-run preview when confirm is on).",
+)
+@click.option(
+    "-y",
+    "--yes",
+    is_flag=True,
+    help="Skip the confirmation prompt before DML is committed.",
+)
+@click.option(
+    "--show-sql",
+    is_flag=True,
+    help="Print the SQL before executing.",
+)
+@click.argument("sql")
+@click.pass_context
+def execute_cmd(
+    ctx: click.Context, connection_str: str, output_fmt: str, apply: bool, yes: bool, show_sql: bool, sql: str
+) -> None:
+    """Run ad-hoc SQL against a configured connection OR a full SQLAlchemy URL.
+
+    The SQL is auto-classified by its first verb: SELECT / WITH / SHOW /
+    EXPLAIN / DESCRIBE / PRAGMA / VALUES / TABLE runs as a query and is
+    rendered via ``--output`` (table / json / yaml / csv). Anything else
+    (INSERT / UPDATE / DELETE / CREATE / DROP / ALTER / ...) runs as DML
+    with the same dry-run-by-default + ``--apply`` safety semantics as a
+    declared ``mode: execute`` operation: on a connection with
+    ``safety.confirm: true`` (the default config), the SQL is previewed
+    and the audit log records a ``dry-run`` status unless ``--apply`` is
+    passed; ``--yes`` skips the final [y/N] prompt.
+
+    \b
+    Examples:
+      dbctl execute -c pg -o json "SELECT * FROM users"
+      dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+      dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+      dbctl execute -c sqlite -o yaml "SELECT name FROM sqlite_master WHERE type='table'"
+
+    \b
+    If the SQL itself begins with a dash, separate options from the
+    positional with ``--`` (Click would otherwise treat the leading dash
+    as an unknown option):
+      dbctl execute -c pg -- "-- my SQL comment starting with a dash"
+
+    Every run is appended to ~/.dbctl/history.jsonl as
+    ``operation="execute"`` so it shows up under ``dbctl history list``;
+    the SQL (truncated to 500 chars) is recorded in the audit entry's
+    ``params.sql`` field.
+    """
+    from dbctl.connections import resolve as resolve_conn_name
+
+    sql_clean = sql.strip()
+    if not sql_clean:
+        err_console.print("[red]empty SQL statement[/red]")
+        raise SystemExit(2)
+    is_select = _sql_is_read(sql_clean)
+
+    is_url = "://" in connection_str
+    if is_url:
+        canonical = "<inline>"
+        try:
+            conn = _make_inline_connection(connection_str)
+        except Exception as e:  # noqa: BLE001 - validator / make-url errors
+            err_console.print(f"[red]invalid connection URL: {e}[/red]")
+            raise SystemExit(2)
+    else:
+        conns, _ = registries(ctx)
+        try:
+            canonical, conn = resolve_conn_name(connection_str, conns)
+        except KeyError as e:
+            err_console.print(f"[red]{e}[/red]")
+            raise SystemExit(2)
+
+    if show_sql:
+        console.print(f"[cyan]SQL:[/cyan]\n{sql_clean}")
+
+    profile = ctx.obj.get("profile")
+    actor = ctx.obj.get("actor")
+
+    # DML safety gate — mirrors `_execute_single`'s read_only / confirm / dry-run logic.
+    if not is_select:
+        if conn.safety.read_only:
+            err_console.print(f"[red]connection {canonical!r} is read-only; DML is blocked[/red]")
+            raise SystemExit(6)
+        if conn.safety.confirm and not apply:
+            console.print("[yellow]dry-run (use --apply to commit)[/yellow]")
+            from dbctl.audit import append
+
+            append(
+                profile=profile,
+                connection=canonical,
+                operation="execute",
+                params={"sql": sql_clean[:500]},
+                mode="execute",
+                status="dry-run",
+                actor=actor,
+            )
+            raise SystemExit(0)
+        if conn.safety.confirm and not yes:
+            confirm_or_abort(f"Apply SQL to {canonical}?", yes=yes)
+
+    if is_url:
+        from dbctl.runtime import opened_engine
+
+        with opened_engine(ctx, canonical, conn) as stub:
+            _do_execute_ad_hoc(
+                engine=stub.engine,
+                sql=sql_clean,
+                is_select=is_select,
+                output_fmt=output_fmt,
+                canonical=canonical,
+                profile=profile,
+                actor=actor,
+            )
+    else:
+        with opened_conn(ctx, canonical) as (_name, _conn, stub):
+            _do_execute_ad_hoc(
+                engine=stub.engine,
+                sql=sql_clean,
+                is_select=is_select,
+                output_fmt=output_fmt,
+                canonical=canonical,
+                profile=profile,
+                actor=actor,
+            )
+
+
 @main.group("history")
 def history_cmd():
     """Show the audit log."""

{dbctl-0.7.4 → dbctl-0.7.8}/dbctl/multi.py

@@ -20,6 +20,7 @@ Execution paths here:
 
 from __future__ import annotations
 
+import re
 import time
 from collections.abc import Callable, Iterator
 from contextlib import contextmanager
@@ -367,13 +368,34 @@ def _truncate_table(c, table: str, engine) -> None:
             c.execute(text(f"DELETE FROM {table_q}"))
 
 
+def _safe_param_names(columns: list[str]) -> dict[str, str]:
+    """Map each column name to a SQLAlchemy-safe bind-parameter name.
+
+    ``text()`` parses a ``:name`` bind parameter up to the first character
+    outside ``[A-Za-z0-9_]`` — a column containing a space (or any other
+    such character) silently truncates the parameter name at that point
+    (e.g. ``:Last price`` is parsed as parameter ``Last`` followed by the
+    literal SQL text ``price``), which then fails at execute time because
+    the row dict has no ``"Last"`` key. Suffixing with the column's index
+    keeps names unique even if two columns sanitize to the same string.
+    """
+    return {c: f"p{i}_{re.sub(r'[^A-Za-z0-9_]', '_', c)}" for i, c in enumerate(columns)}
+
+
+def _remap_rows(rows: list[dict], columns: list[str], param_names: dict[str, str]) -> list[dict]:
+    """Rekey each row dict from real column names to their safe bind-parameter
+    names (see ``_safe_param_names``) before handing it to ``conn.execute``."""
+    return [{param_names[c]: row[c] for c in columns} for row in rows]
+
+
 def _build_insert_sql(table: str, columns: list[str], spec: CopySpec, engine) -> str:
     """Build the dialect-aware INSERT statement for one batch (excluding the
     MSSQL ``skip`` path, which has no single-statement shape — see
     ``_insert_batch_mssql_skip``)."""
     preparer = engine.dialect.identifier_preparer
+    param_names = _safe_param_names(columns)
     cols = ", ".join(preparer.quote(c) for c in columns)
-    placeholders = ", ".join(f":{c}" for c in columns)
+    placeholders = ", ".join(f":{param_names[c]}" for c in columns)
     dialect = engine.dialect.name
     base_sql = f"INSERT INTO {_quote_ident(table, engine)} ({cols}) VALUES ({placeholders})"
 
@@ -401,7 +423,8 @@ def _execute_insert(conn, table: str, columns: list[str], rows: list[dict], spec
     """Execute the INSERT for one batch on an already-open connection; the
     caller controls commit/rollback. Not used for the MSSQL ``skip`` path."""
     sql = _build_insert_sql(table, columns, spec, engine)
-    r = conn.execute(text(sql), rows)
+    safe_rows = _remap_rows(rows, columns, _safe_param_names(columns))
+    r = conn.execute(text(sql), safe_rows)
     # `rowcount` for `executemany` is the number of rows actually written.
     # For `INSERT IGNORE` / `ON CONFLICT DO NOTHING` it excludes the
     # duplicates the driver skipped; for plain `INSERT` it equals
@@ -503,18 +526,20 @@ def _insert_batch_mssql_skip(
     """MSSQL has no native ON CONFLICT; emulate skip by inserting rows one at a
     time guarded by NOT EXISTS on the columns. Slow but correct."""
     preparer = trg.engine.dialect.identifier_preparer
+    param_names = _safe_param_names(columns)
     cols = ", ".join(preparer.quote(c) for c in columns)
-    vals = ", ".join(f":{c}" for c in columns)
+    vals = ", ".join(f":{param_names[c]}" for c in columns)
     table_q = _quote_ident(table, trg.engine)
-    not_exists_cols = " AND ".join(f"s.{c}=t.{c}" for c in columns)
+    not_exists_cols = " AND ".join(f"t.{preparer.quote(c)} = :{param_names[c]}" for c in columns)
     sql = (
         f"INSERT INTO {table_q} ({cols}) "
         f"SELECT {vals} WHERE NOT EXISTS "
         f"(SELECT 1 FROM {table_q} t WHERE {not_exists_cols})"
     )
     inserted = 0
+    safe_rows = _remap_rows(rows, columns, param_names)
     with trg.engine.begin() as c:
-        for row in rows:
+        for row in safe_rows:
             r = c.execute(text(sql), row)
             inserted += r.rowcount or 0
     return inserted