execsql2 2.17.3__py3-none-any.whl → 2.18.0__py3-none-any.whl

execsql/importers/json.py

@@ -4,10 +4,11 @@ from __future__ import annotations
 JSON import for execsql.
 
 Provides :func:`import_json`, used by ``IMPORT … FORMAT json``.
-Supports JSON arrays of objects (``[{…}, …]``) and newline-delimited
-JSON (NDJSON, one object per line).  Nested objects are flattened with
-dot-separated keys; nested arrays and non-object values are serialized
-as JSON strings so every column maps to a scalar database value.
+Supports JSON arrays of objects (``[{…}, …]``) and `JSON Lines
+<https://jsonlines.org/>`_ (JSONL, one object per line).  Nested
+objects are flattened with dot-separated keys; nested arrays and
+non-object values are serialized as JSON strings so every column
+maps to a scalar database value.
 """
 
 import json
@@ -45,42 +46,58 @@ def _flatten(obj: Any, prefix: str = "", sep: str = ".") -> dict[str, Any]:
 def _parse_json_file(filename: str, encoding: str) -> list[dict[str, Any]]:
     """Read a JSON file and return a list of flat dicts.
 
-    Accepts either a JSON array of objects or newline-delimited JSON
-    (NDJSON).
+    Accepts either a JSON array of objects or `JSON Lines
+    <https://jsonlines.org/>`_ (JSONL). The JSONL path streams the
+    file line-by-line so the raw text isn't buffered alongside the
+    parsed records (B19/F043). The array path still buffers the
+    whole file — switching to a streaming parser would require
+    ``ijson`` as a dependency.
     """
-    text = Path(filename).read_text(encoding=encoding)
-    stripped = text.strip()
-
-    if stripped.startswith("["):
-        # Standard JSON array.
-        raw = json.loads(stripped)
+    # Peek at the first non-whitespace character to decide which
+    # parsing strategy to use, without slurping the entire file.
+    with open(filename, encoding=encoding) as fh:
+        first_char: str | None = None
+        while True:
+            ch = fh.read(1)
+            if not ch:
+                break
+            if not ch.isspace():
+                first_char = ch
+                break
+
+    if first_char == "[":
+        # Standard JSON array — must buffer the whole file (json.loads
+        # has no streaming mode; ijson would be needed for that).
+        text = Path(filename).read_text(encoding=encoding)
+        raw = json.loads(text)
         if not isinstance(raw, list):
             raise ErrInfo(type="error", other_msg="JSON file root is not an array of objects.")
         records = raw
-    elif stripped.startswith("{"):
-        # Try NDJSON (one object per line) or a single object.
+    elif first_char == "{":
+        # JSONL (JSON Lines) — stream the file line-by-line.
         records = []
-        for lineno, line in enumerate(stripped.splitlines(), 1):
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                obj = json.loads(line)
-            except json.JSONDecodeError as exc:
-                raise ErrInfo(
-                    type="error",
-                    other_msg=f"Invalid JSON on line {lineno}: {exc}",
-                ) from exc
-            if not isinstance(obj, dict):
-                raise ErrInfo(
-                    type="error",
-                    other_msg=f"Line {lineno} is not a JSON object.",
-                )
-            records.append(obj)
+        with open(filename, encoding=encoding) as fh:
+            for lineno, line in enumerate(fh, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError as exc:
+                    raise ErrInfo(
+                        type="error",
+                        other_msg=f"Invalid JSON on line {lineno}: {exc}",
+                    ) from exc
+                if not isinstance(obj, dict):
+                    raise ErrInfo(
+                        type="error",
+                        other_msg=f"Line {lineno} is not a JSON object.",
+                    )
+                records.append(obj)
     else:
         raise ErrInfo(
             type="error",
-            other_msg="JSON import expects a file starting with '[' (array) or '{' (object/NDJSON).",
+            other_msg="JSON import expects a file starting with '[' (array) or '{' (object/JSONL).",
         )
 
     if not records:

execsql/metacommands/conditions.py

@@ -75,7 +75,7 @@ def xf_startswith(**kwargs: Any) -> bool:
     if kwargs["ignorecase"] and kwargs["ignorecase"].lower() == "i":
         s1 = s1.lower()
         s2 = s2.lower()
-    return s1[: len(s2)] == s2
+    return s1.startswith(s2)
 
 
 def xf_endswith(**kwargs: Any) -> bool:
@@ -84,7 +84,7 @@ def xf_endswith(**kwargs: Any) -> bool:
     if kwargs["ignorecase"] and kwargs["ignorecase"].lower() == "i":
         s1 = s1.lower()
         s2 = s2.lower()
-    return s1[-len(s2) :] == s2
+    return s1.endswith(s2)
 
 
 def xf_hasrows(**kwargs: Any) -> bool:
@@ -374,6 +374,10 @@ def xf_istrue(**kwargs: Any) -> bool:
     return unquoted(kwargs["value"].strip()).lower() in ("yes", "y", "true", "t", "1")
 
 
+def xf_isfalse(**kwargs: Any) -> bool:
+    return unquoted(kwargs["value"].strip()).lower() in ("no", "n", "false", "f", "0")
+
+
 def xf_dbms(**kwargs: Any) -> bool:
     dbms = kwargs["dbms"]
     return _state.dbs.current().type.dbms_id.lower() == dbms.strip().lower()
@@ -797,6 +801,7 @@ def build_conditional_table() -> Any:
         category="condition",
     )
     mcl.add(r"^\s*IS_TRUE\(\s*(?P<value>[^)]*)\s*\)", xf_istrue, description="IS_TRUE", category="condition")
+    mcl.add(r"^\s*IS_FALSE\(\s*(?P<value>[^)]*)\s*\)", xf_isfalse, description="IS_FALSE", category="condition")
 
     # Boolean literals
     mcl.add(

execsql/metacommands/io_export.py

@@ -18,7 +18,6 @@ appropriate writer in :mod:`execsql.exporters`.
 
 from __future__ import annotations
 
-from pathlib import Path
 from typing import Any
 
 import execsql.state as _state
@@ -44,28 +43,24 @@ from execsql.exporters.yaml import write_query_to_yaml
 from execsql.importers.base import import_data_table
 from execsql.script import current_script_line
 from execsql.utils.errors import exception_desc
-from execsql.utils.fileio import check_dir
+from execsql.utils.fileio import check_dir, safe_output_path
 
 
 def _apply_output_dir(path: str) -> str:
-    """Prepend the configured --output-dir to *path* if it is a relative path.
+    """Resolve *path* against the configured ``--output-dir`` root.
 
-    If ``conf.export_output_dir`` is set and *path* is not absolute (and not
-    ``stdout``), the base directory is joined to *path* so that all EXPORT
-    output lands in the same directory without requiring scripts to hard-code
-    absolute paths.
+    When ``conf.export_output_dir`` is set, ``--output-dir`` is treated as a
+    containment boundary: relative paths are joined to it, absolute paths
+    must already fall inside it, and ``..`` segments that escape the root
+    are rejected. ``stdout`` is passed through untouched.
+
+    When ``conf.export_output_dir`` is unset, *path* is returned unchanged
+    (no behavior change for users not opting in to ``--output-dir``).
     """
     output_dir = getattr(_state.conf, "export_output_dir", None)
-    if not output_dir:
-        return path
-    if path.lower() == "stdout":
-        return path
-    if Path(path).is_absolute():
-        return path
-    # Windows drive-letter paths are also absolute
-    if len(path) > 1 and path[1] == ":":
+    if not output_dir or path.lower() == "stdout":
         return path
-    return str(Path(output_dir) / path)
+    return safe_output_path(path, output_dir)
 
 
 # ---------------------------------------------------------------------------
@@ -212,12 +207,12 @@ def x_export(**kwargs: Any) -> None:
 
 def x_export_query(**kwargs: Any) -> None:
     select_stmt = kwargs["query"]
-    outfile = kwargs["filename"]
+    outfile = _apply_output_dir(kwargs["filename"])
     description = kwargs["description"]
     tee = bool(kwargs["tee"])
     append = bool(kwargs["append"])
     filefmt = kwargs["format"].lower()
-    zipfilename = kwargs["zipfilename"]
+    zipfilename = _apply_output_dir(kwargs["zipfilename"]) if kwargs["zipfilename"] else None
     notype = bool(kwargs.get("notype"))
     _check_zip_compat(outfile, filefmt, zipfilename)
     check_dir(outfile)
@@ -242,13 +237,13 @@ def x_export_query(**kwargs: Any) -> None:
 
 def x_export_query_with_template(**kwargs: Any) -> None:
     select_stmt = kwargs["query"]
-    outfile = kwargs["filename"]
+    outfile = _apply_output_dir(kwargs["filename"])
     template_file = kwargs["template"]
     tee = kwargs["tee"]
     tee = bool(tee)
     append = kwargs["append"]
     append = bool(append)
-    zipfilename = kwargs["zipfilename"]
+    zipfilename = _apply_output_dir(kwargs["zipfilename"]) if kwargs["zipfilename"] else None
     check_dir(outfile)
     if tee and outfile.lower() != "stdout":
         prettyprint_query(select_stmt, _state.dbs.current(), "stdout", False)
@@ -262,13 +257,13 @@ def x_export_with_template(**kwargs: Any) -> None:
     table = kwargs["table"]
     queryname = _state.dbs.current().schema_qualified_table_name(schema, table)
     select_stmt = f"select * from {queryname};"
-    outfile = kwargs["filename"]
+    outfile = _apply_output_dir(kwargs["filename"])
     template_file = kwargs["template"]
     tee = kwargs["tee"]
     tee = bool(tee)
     append = kwargs["append"]
     append = bool(append)
-    zipfilename = kwargs["zipfilename"]
+    zipfilename = _apply_output_dir(kwargs["zipfilename"]) if kwargs["zipfilename"] else None
     check_dir(outfile)
     if tee and outfile.lower() != "stdout":
         prettyprint_query(select_stmt, _state.dbs.current(), "stdout", False)
@@ -279,7 +274,7 @@ def x_export_with_template(**kwargs: Any) -> None:
 
 def x_export_ods_multiple(**kwargs: Any) -> None:
     table_list = kwargs["tables"]
-    outfile = kwargs["filename"]
+    outfile = _apply_output_dir(kwargs["filename"])
     description = kwargs["description"]
     tee = kwargs["tee"]
     tee = bool(tee)
@@ -292,7 +287,7 @@ def x_export_ods_multiple(**kwargs: Any) -> None:
 def x_export_xlsx_multiple(**kwargs: Any) -> None:
     """Export multiple tables to separate worksheets in a single XLSX workbook."""
     table_list = kwargs["tables"]
-    outfile = kwargs["filename"]
+    outfile = _apply_output_dir(kwargs["filename"])
     description = kwargs["description"]
     tee = kwargs["tee"]
     tee = bool(tee)
@@ -303,10 +298,10 @@ def x_export_xlsx_multiple(**kwargs: Any) -> None:
 
 
 def x_export_metadata(**kwargs: Any) -> None:
-    outfile = kwargs["filename"]
+    outfile = _apply_output_dir(kwargs["filename"])
     append = kwargs["append"] is not None
     xall = kwargs["all"] is not None
-    zipfilename = kwargs["zipfilename"]
+    zipfilename = _apply_output_dir(kwargs["zipfilename"]) if kwargs["zipfilename"] else None
     filefmt = kwargs["format"].lower()
     if xall:
         hdrs, rows = _state.export_metadata.get_all()

execsql/metacommands/io_fileops.py

@@ -17,7 +17,6 @@ import execsql.state as _state
 from execsql.exceptions import ErrInfo
 from execsql.models import DataTable
 from execsql.script import current_script_line
-from execsql.types import dbt_firebird
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 from execsql.utils.strings import unquoted
@@ -95,7 +94,7 @@ def x_copy(**kwargs: Any) -> None:
             except Exception:
                 _state.exec_log.log_status_info(f"Could not drop existing table ({tbl2}) for COPY metacommand")
         db2.execute(create_tbl)
-        if db2.type == dbt_firebird:
+        if db2.needs_explicit_commit_after_ddl():
             db2.execute("COMMIT;")
     try:
         hdrs, rows = db1.select_rowsource(select_stmt)
@@ -169,7 +168,7 @@ def x_copy_query(**kwargs: Any) -> None:
             except Exception:
                 _state.exec_log.log_status_info(f"Could not drop existing table ({tbl2}) for COPY metacommand")
         db2.execute(create_tbl)
-        if db2.type == dbt_firebird:
+        if db2.needs_explicit_commit_after_ddl():
             db2.execute("COMMIT;")
     try:
         hdrs, rows = db1.select_rowsource(select_stmt)
@@ -209,6 +208,13 @@ def x_zip_buffer_mb(**kwargs: Any) -> None:
 def x_rm_file(**kwargs: Any) -> None:
     import glob as _glob
 
+    if not getattr(_state.conf, "allow_rm_file", True):
+        raise ErrInfo(
+            type="cmd",
+            command_text=kwargs.get("metacommandline", "RM_FILE"),
+            other_msg="The RM_FILE metacommand is disabled (--no-rm-file).",
+        )
+
     fn = kwargs["filename"].strip(' "')
     fnlist = _glob.glob(fn)
     for f in fnlist:
@@ -249,7 +255,19 @@ def x_hdf5_text_len(**kwargs: Any) -> None:
 
 
 def x_serve(**kwargs: Any) -> None:
+    from execsql.utils.fileio import safe_output_path
+
+    if not getattr(_state.conf, "allow_serve", True):
+        raise ErrInfo(
+            type="cmd",
+            command_text=kwargs.get("metacommandline", "SERVE"),
+            other_msg="The SERVE metacommand is disabled (--no-serve).",
+        )
+
     infname = kwargs["filename"]
+    serve_root = getattr(_state.conf, "serve_root", None)
+    if serve_root:
+        infname = safe_output_path(infname, serve_root)
     fmt = kwargs["format"].lower()
     if not Path(infname).is_file():
         raise ErrInfo(

execsql/metacommands/io_import.py

@@ -8,7 +8,7 @@
 - ``x_import_xls`` / ``x_import_xls_pattern`` — same for XLS/XLSX.
 - ``x_import_parquet`` — IMPORT … FROM PARQUET (via polars).
 - ``x_import_feather`` — IMPORT … FROM FEATHER (via polars).
-- ``x_import_json`` — IMPORT … FROM JSON (array of objects or NDJSON).
+- ``x_import_json`` — IMPORT … FROM JSON (array of objects or JSON Lines).
 - ``x_import_row_buffer`` — CONFIG IMPORT_ROW_BUFFER.
 - ``x_show_progress`` — CONFIG SHOW_PROGRESS (toggle the import progress bar).
 """
@@ -163,7 +163,18 @@ def x_import_ods_pattern(**kwargs: Any) -> None:
         is_new = 0
     schemaname = kwargs["schema"]
     filename = kwargs["filename"]
-    rx = re.compile(kwargs["patn"], re.I)
+    # B18/F012: surface a friendly error for malformed regex patterns
+    # rather than letting an uncaught re.error bubble up. (ReDoS via
+    # catastrophic backtracking remains a documented risk — re2 is
+    # not in stdlib so we can't enforce a complexity cap here.)
+    try:
+        rx = re.compile(kwargs["patn"], re.I)
+    except re.error as exc:
+        raise ErrInfo(
+            type="cmd",
+            command_text=kwargs.get("metacommandline", "IMPORT ODS PATTERN"),
+            other_msg=f"Invalid regular expression {kwargs['patn']!r}: {exc}",
+        ) from exc
     hdr_rows = kwargs["skip"]
     if not hdr_rows:
         hdr_rows = 0
@@ -260,7 +271,16 @@ def x_import_xls_pattern(**kwargs: Any) -> None:
         is_new = 0
     schemaname = kwargs["schema"]
     filename = kwargs["filename"]
-    rx = re.compile(kwargs["patn"], re.I)
+    # B18/F012: surface a friendly error for malformed regex patterns
+    # (see x_import_ods_pattern for the full rationale).
+    try:
+        rx = re.compile(kwargs["patn"], re.I)
+    except re.error as exc:
+        raise ErrInfo(
+            type="cmd",
+            command_text=kwargs.get("metacommandline", "IMPORT XLS PATTERN"),
+            other_msg=f"Invalid regular expression {kwargs['patn']!r}: {exc}",
+        ) from exc
     hdr_rows = kwargs["skip"]
     encoding = kwargs["encoding"]
     if not hdr_rows:

execsql/script/ast.py

@@ -483,6 +483,14 @@ def _format_nodes(nodes: list[Node], lines: list[str], prefix: str) -> None:
             _format_if_block(node, lines, child_prefix)
         elif isinstance(node, (LoopBlock, BatchBlock, ScriptBlock, SqlBlock)):
             _format_nodes(node.body, lines, child_prefix)
+        elif isinstance(node, (SqlStatement, MetaCommandStatement, Comment, IncludeDirective)):
+            # Leaf nodes — no children to render.
+            pass
+        else:
+            # Guard against silently skipping bodies of future block-type nodes.
+            raise NotImplementedError(
+                f"_format_nodes does not handle {type(node).__name__}",
+            )
 
 
 def _format_if_block(node: IfBlock, lines: list[str], prefix: str) -> None:

execsql/script/engine.py

@@ -442,6 +442,14 @@ def set_system_vars(ctx: Any = None) -> None:
 
 
 _MAX_SUBSTITUTION_DEPTH = 100
+# B17/F013: output-byte ceiling for substitute_vars. The depth cap
+# above stops cyclic references (a → !!b!!, b → !!a!!) but does not
+# stop exponential expansion: a single variable referencing the same
+# other variable N times grows ``2^N`` per iteration without ever
+# looping. Track the rendered length and abort when it crosses
+# _MAX_SUBSTITUTION_BYTES (default 10 MB — well above any legitimate
+# SQL statement, comfortably below a memory-pressure failure mode).
+_MAX_SUBSTITUTION_BYTES = 10 * 1024 * 1024
 
 
 def substitute_vars(command_str: str, localvars: SubVarSet | None = None, ctx: Any = None) -> str:
@@ -452,12 +460,23 @@ def substitute_vars(command_str: str, localvars: SubVarSet | None = None, ctx: A
         localvars: Optional local variable overlay to merge with globals.
         ctx: Optional :class:`RuntimeContext`.  When ``None``, falls through
             to the global ``_state`` module (legacy behavior).
+
+    Raises:
+        ErrInfo: when the iteration count exceeds
+            :data:`_MAX_SUBSTITUTION_DEPTH` (cyclic reference) OR the
+            expanded output exceeds :data:`_MAX_SUBSTITUTION_BYTES`
+            (exponential expansion bomb).
     """
     _s = ctx if ctx is not None else _state
     if localvars is not None:
         subs = _s.subvars.merge(localvars)
     else:
         subs = _s.subvars
+    # Allow runtime override of the byte cap via conf. None / missing
+    # → use the engine default (back-compat with users who legitimately
+    # render multi-MB SQL through substitution).
+    conf_max = getattr(_s.conf, "max_substitution_bytes", None)
+    max_bytes = conf_max if conf_max is not None else _MAX_SUBSTITUTION_BYTES
     cmdstr = command_str
     subs_made = True
     iterations = 0
@@ -467,6 +486,19 @@ def substitute_vars(command_str: str, localvars: SubVarSet | None = None, ctx: A
         cmdstr, any_subbed = _s.counters.substitute_all(cmdstr)
         subs_made = subs_made or any_subbed
         iterations += 1
+        # Only enforce the byte cap when expansion ACTUALLY happened
+        # this iteration. A user passing a large pre-existing literal
+        # with no !!var!! tokens shouldn't be rejected — the cap
+        # targets expansion-bomb growth, not literal input size.
+        if subs_made and len(cmdstr) > max_bytes:
+            raise ErrInfo(
+                type="error",
+                other_msg=(
+                    f"Substitution variable expansion exceeded {max_bytes} bytes "
+                    f"(possible exponential expansion bomb) while expanding: "
+                    f"{command_str[:200]}"
+                ),
+            )
         if iterations >= _MAX_SUBSTITUTION_DEPTH:
             raise ErrInfo(
                 type="error",

execsql/script/executor.py

@@ -783,6 +783,18 @@ def _execute_include_native(
     if len(target) > 1 and target[0] == "~" and target[1] == os.sep:
         target = str(Path.home() / target[2:])
 
+    # Optional containment: when conf.include_root is set, the resolved
+    # INCLUDE / EXECUTE SCRIPT target must live under that root.
+    include_root = getattr(ctx.conf, "include_root", None) if hasattr(ctx, "conf") else None
+    if include_root is None:
+        import execsql.state as _state
+
+        include_root = getattr(_state.conf, "include_root", None)
+    if include_root:
+        from execsql.utils.fileio import safe_output_path
+
+        target = safe_output_path(target, include_root)
+
     target_path = Path(target)
 
     # IF EXISTS handling

execsql/script/variables.py

@@ -9,7 +9,6 @@ Classes:
 - :class:`ScriptArgSubVarSet` — per-script ``#``-prefixed argument overlay.
 """
 
-import os
 import re
 from typing import Any
 
@@ -244,17 +243,31 @@ class SubVarSet:
                 if sub is None:
                     sub = ""
                 sub = str(sub)
-                if os.name != "posix":
-                    sub = sub.replace("\\", "\\\\")
+                # B07a/F002: reject embedded NUL bytes regardless of quoter;
+                # most DBMS protocols truncate at NUL and PostgreSQL rejects.
+                if "\x00" in sub:
+                    raise ValueError(
+                        f"Substitution variable {varname!r} contains a NUL byte; refusing to interpolate.",
+                    )
                 quote = m.group("q")
                 if quote == "'":
-                    # Wrap value in single quotes, doubling any embedded
-                    # apostrophe — produces a SQL string literal.
-                    sub = "'" + sub.replace("'", "''") + "'"
+                    # B07a/F002: wrap in single quotes, doubling embedded
+                    # apostrophes AND escaping backslashes so MySQL default
+                    # mode and PostgreSQL E-string literals can't end the
+                    # quoted region via ``\'``. The previous Windows-only
+                    # branch (``os.name != 'posix'``) applied the escape on
+                    # the wrong axis — host OS vs target DBMS.
+                    sub = "'" + sub.replace("\\", "\\\\").replace("'", "''") + "'"
                 elif quote == '"':
-                    # Wrap value in double quotes — produces a SQL quoted
-                    # identifier or quoted metacommand argument.
-                    sub = '"' + sub + '"'
+                    # B07a/F001: wrap in double quotes, doubling embedded
+                    # ``"`` so a value containing ``"; DROP TABLE x; --``
+                    # produces a valid quoted identifier rather than a
+                    # closing quote followed by a second statement.
+                    sub = '"' + sub.replace('"', '""') + '"'
+                else:
+                    # Bare !!var!! token — preserve the raw value verbatim
+                    # but still defend against NUL bytes (handled above).
+                    pass
                 return command_str[: m.start()] + sub + command_str[m.end() :], True
             # Token found but variable not defined — skip it and keep searching.
             m = self._TOKEN_RX.search(command_str, m.end())
@@ -270,32 +283,45 @@ class SubVarSet:
         compilation to avoid O(N) ``re.compile`` calls on every invocation.
         """
         cmd_lower = command_str.lower()
+
+        def _check_nul(name: str, value: str) -> None:
+            """B07a/F002: raise when *value* (about to be interpolated)
+            contains a NUL byte. Called only after a token match so an
+            unrelated variable's NUL value never blocks substitution of
+            a different variable."""
+            if "\x00" in value:
+                raise ValueError(
+                    f"Substitution variable {name!r} contains a NUL byte; refusing to interpolate.",
+                )
+
         for varname, sub in self._subs_dict.items():
             if sub is None:
                 sub = ""
             sub = str(sub)
-            if os.name != "posix":
-                sub = sub.replace("\\", "\\\\")
             # Standard token: !!varname!!
             token = f"!!{varname}!!"
             idx = cmd_lower.find(token)
             if idx != -1:
+                _check_nul(varname, sub)
                 return command_str[:idx] + sub + command_str[idx + len(token) :], True
-            # Single-quote-wrapped token: !'!varname!'!
+            # Single-quote-wrapped token: !'!varname!'! — escape ``\`` and
+            # double embedded ``'`` (see substitute_one for rationale).
             tokenq = f"!'!{varname}!'!"
             idxq = cmd_lower.find(tokenq)
             if idxq != -1:
-                wrapped = "'" + sub.replace("'", "''") + "'"
+                _check_nul(varname, sub)
+                wrapped = "'" + sub.replace("\\", "\\\\").replace("'", "''") + "'"
                 return (
                     command_str[:idxq] + wrapped + command_str[idxq + len(tokenq) :],
                     True,
                 )
-            # Double-quote-wrapped token: !"!varname!"!
+            # Double-quote-wrapped token: !"!varname!"! — double embedded ``"``.
             tokendq = f'!"!{varname}!"!'
             idxdq = cmd_lower.find(tokendq)
             if idxdq != -1:
+                _check_nul(varname, sub)
                 return (
-                    command_str[:idxdq] + '"' + sub + '"' + command_str[idxdq + len(tokendq) :],
+                    command_str[:idxdq] + '"' + sub.replace('"', '""') + '"' + command_str[idxdq + len(tokendq) :],
                     True,
                 )
         return command_str, False

execsql/utils/auth.py

@@ -29,11 +29,56 @@ import getpass
 
 import execsql.state as _state
 
-__all__ = ["get_password", "clear_stored_password", "password_from_keyring"]
+__all__ = ["clear_stored_password", "get_password", "is_plaintext_keyring", "password_from_keyring"]
 
 # Tracks whether the most recent get_password() call returned a keyring-stored value.
 _last_from_keyring: bool = False
 
+# Tracks whether we've already warned about a plaintext keyring backend
+# this process — keyring is a one-shot warning, not a per-call nag.
+_plaintext_warned: bool = False
+
+
+def is_plaintext_keyring() -> bool:
+    """Return True if the active keyring backend stores secrets in cleartext.
+
+    B20/F040: on headless Linux without a real Secret Service, the
+    ``keyrings.alt.file.PlaintextKeyring`` (or
+    ``EncryptedKeyring`` with a hard-coded passphrase) backend is
+    used silently. Detect by inspecting the active backend's module
+    path so callers can warn the user instead of pretending secrets
+    are encrypted.
+    """
+    try:
+        import keyring
+
+        backend = keyring.get_keyring()
+        module = type(backend).__module__
+        return "keyrings.alt" in module or "fail" in module.lower()
+    except Exception:
+        return False
+
+
+def _warn_if_plaintext_keyring() -> None:
+    """Print a one-time warning if the active keyring backend is plaintext."""
+    global _plaintext_warned
+    if _plaintext_warned or not is_plaintext_keyring():
+        return
+    _plaintext_warned = True
+    try:
+        import keyring
+        import sys
+
+        backend_name = type(keyring.get_keyring()).__name__
+        print(
+            f"WARNING: active keyring backend ({backend_name}) stores secrets in "
+            f"cleartext or with a hard-coded key. Stored passwords are not "
+            f"meaningfully protected.",
+            file=sys.stderr,
+        )
+    except Exception:
+        pass
+
 
 def _keyring_service(dbms_name: str, database_name: str, server_name: str | None) -> str:
     """Build a keyring service name from connection parameters."""
@@ -53,6 +98,9 @@ def _keyring_get(service: str, username: str) -> str | None:
 
 def _keyring_set(service: str, username: str, password: str) -> bool:
     """Try to store a password in the OS keyring.  Returns True on success."""
+    # B20/F040: warn before storing into a plaintext backend so the user
+    # knows their secret is not meaningfully protected at rest.
+    _warn_if_plaintext_keyring()
     try:
         import keyring