Guard TEXT binds with embedded NULs at the dbapi layer

dqlite's wire encodes TEXT as NUL-terminated UTF-8, so a Python str
with embedded "\x00" cannot round-trip. The wire encoder already
rejects with EncodeError (which cursor._call_client wraps as
DataError), so the failure was already in the dbapi.Error hierarchy
— but the wire-internal diagnostic talked about "null-terminated
encoding would lose data", not the actionable workaround.

Stdlib sqlite3 accepts the same bind faithfully (sqlite3_bind_text
stores the bytes as-is; only sqlite3_column_text truncates at the
first NUL on read-back, while sqlite3_column_blob round-trips). So
cross-driver code that stores NUL-containing payloads in TEXT works
silently on stdlib and raises on dqlite — and the operator reading
the wire-internal diagnostic had no breadcrumb pointing at the BLOB
column / bytes-bind workaround.

Add a pre-encode guard at _convert_bind_param that raises DataError
with a diagnostic naming the offset of the offending NUL and the
canonical BLOB workaround. Runs after the adapter / __conform__
chain so an adapter that produces a NUL-bearing str is also caught
at the adapter site rather than escaping into the wire encoder.
Defence-in-depth: the wire-layer rejection stays in place.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/dqlitedbapi/types.py

@@ -1029,6 +1029,19 @@ def _convert_bind_param(value: Any) -> Any:
     the isinstance built-in arm fires when no exact-type adapter
     matches, then chains the result (the adapter-output chain above)
     if the produced value is itself a datetime/date/time.
+
+    **TEXT binds with embedded NUL bytes are rejected.** dqlite's
+    wire protocol encodes TEXT as NUL-terminated UTF-8, so an
+    embedded ``"\\x00"`` cannot round-trip. The dbapi layer raises
+    :class:`~dqlitedbapi.exceptions.DataError` (in the ``dbapi.Error``
+    hierarchy) BEFORE handing the value to the wire encoder, with a
+    diagnostic naming the BLOB workaround. Diverges from stdlib
+    ``sqlite3``, whose ``sqlite3_bind_text`` accepts embedded NULs
+    (TEXT readback via ``sqlite3_column_text`` truncates at the
+    first NUL, but the value round-trips faithfully via
+    ``sqlite3_column_blob``). Cross-driver code targeting both
+    stdlib and dqlite must bind NUL-containing payloads as
+    ``bytes`` / ``memoryview`` on a BLOB column.
     """
     # User-registered adapter takes precedence. ``type(value)`` not
     # isinstance: stdlib's contract is exact-class match (subclasses
@@ -1118,4 +1131,27 @@ def _convert_bind_param(value: Any) -> Any:
             f"only int / float / str / bytes / bytearray / memoryview / "
             f"bool / None. Register an adapter that returns one of those."
         )
+    # Pre-wire NUL guard: dqlite's wire TEXT is NUL-terminated UTF-8
+    # (see ``dqlitewire.encode_text``), so embedded NULs cannot
+    # round-trip. The wire encoder already rejects with
+    # ``EncodeError``, which ``cursor._call_client`` wraps as
+    # ``DataError`` — but the wire-layer diagnostic mentions the
+    # null-terminated-encoding internal mechanic, not the canonical
+    # workaround. Reject at the dbapi layer with a message naming
+    # the BLOB workaround so cross-driver operators porting from
+    # stdlib ``sqlite3`` (which stores embedded NULs in TEXT
+    # faithfully via ``sqlite3_bind_text``) see the actionable hint
+    # rather than the wire-internal message. Defence-in-depth: the
+    # wire-layer rejection stays in place. Runs AFTER the adapter /
+    # ``__conform__`` chain so an adapter that produces a NUL-bearing
+    # ``str`` is also caught.
+    if isinstance(value, str) and "\x00" in value:
+        raise DataError(
+            f"TEXT bind with embedded NUL at offset "
+            f"{value.index(chr(0))} rejected by dqlite wire "
+            f"(NUL-terminated UTF-8). Cross-driver divergence from "
+            f"stdlib sqlite3 which preserves NULs in TEXT. Use a "
+            f"BLOB column (bind bytes/memoryview) to round-trip "
+            f"NUL-containing data."
+        )
     return value

tests/test_text_bind_nul_byte_rejected_with_blob_hint.py

@@ -0,0 +1,92 @@
+"""Pin: ``_convert_bind_param`` rejects ``str`` bind values containing
+embedded NUL bytes with a ``DataError`` naming the BLOB workaround,
+BEFORE the wire encoder runs.
+
+dqlite's wire protocol encodes TEXT as NUL-terminated UTF-8, so an
+embedded ``"\\x00"`` cannot round-trip. The wire encoder
+(``dqlitewire.encode_text``) already rejects with ``EncodeError``,
+which the cursor's ``_call_client`` wraps as ``DataError`` — but the
+wire-internal diagnostic doesn't point at the actionable workaround
+(use a BLOB column / bind ``bytes``).
+
+Stdlib ``sqlite3.sqlite3_bind_text`` accepts embedded NULs faithfully
+(``sqlite3_column_text`` truncates at the first NUL on read-back, but
+``sqlite3_column_blob`` round-trips), so cross-driver code that stores
+NUL-containing TEXT silently works against stdlib but raises against
+dqlite. Surface a discoverable dbapi-layer diagnostic so operators
+porting from stdlib see the BLOB hint immediately.
+
+The bytes path is unaffected — bind ``bytes`` / ``memoryview`` against
+a BLOB column to round-trip NUL-containing data.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+import dqlitedbapi
+from dqlitedbapi.exceptions import DataError
+from dqlitedbapi.types import _convert_bind_param
+
+
+def test_text_with_embedded_nul_rejected_with_blob_hint() -> None:
+    """The dbapi-layer pre-encode guard fires and names the BLOB
+    workaround. Catches both the canonical 'embedded NUL' phrasing
+    and the actionable 'BLOB' workaround hint so operators porting
+    from stdlib see the path forward without walking ``__cause__``.
+    """
+    with pytest.raises(DataError) as excinfo:
+        _convert_bind_param("hello\x00world")
+    message = str(excinfo.value)
+    assert "embedded NUL" in message
+    assert "BLOB" in message
+    # The offset is named so operators can identify the byte in a
+    # mixed-binary payload.
+    assert "offset 5" in message
+
+
+def test_text_nul_rejection_is_in_dbapi_error_hierarchy() -> None:
+    """The rejection inherits from ``dbapi.Error`` so cross-driver
+    code's ``except dbapi.Error:`` arm catches uniformly."""
+    with pytest.raises(dqlitedbapi.Error):
+        _convert_bind_param("\x00")
+
+
+def test_bytes_with_embedded_nul_unaffected() -> None:
+    """The BLOB / bytes path round-trips NUL-containing data — this
+    is the canonical workaround the diagnostic points at. Pin the
+    bytes pass-through so the guard cannot regress to a blanket
+    reject.
+    """
+    payload = b"hello\x00world"
+    assert _convert_bind_param(payload) is payload
+    payload_ba = bytearray(b"hello\x00world")
+    assert _convert_bind_param(payload_ba) is payload_ba
+    payload_mv = memoryview(b"hello\x00world")
+    assert _convert_bind_param(payload_mv) is payload_mv
+
+
+def test_text_without_nul_unaffected() -> None:
+    """Plain TEXT binds (no embedded NUL) pass through unchanged."""
+    assert _convert_bind_param("hello world") == "hello world"
+    assert _convert_bind_param("") == ""
+    assert _convert_bind_param("unicode: 日本語") == "unicode: 日本語"
+
+
+def test_adapter_producing_str_with_nul_also_rejected() -> None:
+    """The guard runs AFTER the adapter / ``__conform__`` chain so an
+    adapter that legitimately produces a NUL-bearing ``str`` (e.g. a
+    caller's misregistered serialiser) is also caught with the same
+    actionable diagnostic, rather than escaping past the adapter site
+    into the wire encoder.
+    """
+
+    class _NeedsAdapter:
+        pass
+
+    dqlitedbapi.register_adapter(_NeedsAdapter, lambda _v: "leading\x00trailing")
+    try:
+        with pytest.raises(DataError, match="embedded NUL"):
+            _convert_bind_param(_NeedsAdapter())
+    finally:
+        dqlitedbapi.unregister_adapter(_NeedsAdapter)