fix: reject bare str/bytes as params with clear TypeError

params was typed as Sequence[Any], which includes str/bytes; calling
execute("SELECT ?", "alice") type-checked, iterated "alice" character
by character, and sent 5 parameters to the server. The user saw a
confusing "wrong parameter count" server error instead of a clean
client-side type mismatch.

Add a _validate_params guard at every client entry point (execute,
query_raw, fetch, fetchall, fetchval) that raises TypeError with a
helpful hint when params is str or bytes.

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

Author: antoineleclair

src/dqliteclient/connection.py

@@ -238,6 +238,16 @@ def _invalidate(self, cause: BaseException | None = None) -> None:
         if cause is not None:
             self._invalidation_cause = cause
 
+    @staticmethod
+    def _validate_params(params: Sequence[Any] | None) -> None:
+        """Reject bare str/bytes params to catch the ``execute("?", "x")`` footgun.
+
+        ``str`` and ``bytes`` are both ``Sequence[Any]``, so they type-check
+        but would silently split into N single-character parameters.
+        """
+        if isinstance(params, str | bytes):
+            raise TypeError("params must be a list or tuple, not str/bytes; did you mean [value]?")
+
     async def _run_protocol[T](self, fn: Callable[[DqliteProtocol, int], Awaitable[T]]) -> T:
         """Run a protocol operation with standard error handling.
 
@@ -270,6 +280,7 @@ async def execute(self, sql: str, params: Sequence[Any] | None = None) -> tuple[
 
         Returns (last_insert_id, rows_affected).
         """
+        self._validate_params(params)
         return await self._run_protocol(lambda p, db: p.exec_sql(db, sql, params))
 
     async def query_raw(
@@ -281,6 +292,7 @@ async def query_raw(
         of (column_names, rows) from the wire protocol. Intended for
         DBAPI cursor implementations that need column names separately.
         """
+        self._validate_params(params)
         return await self._run_protocol(lambda p, db: p.query_sql(db, sql, params))
 
     async def query_raw_typed(
@@ -296,11 +308,13 @@ async def query_raw_typed(
 
     async def fetch(self, sql: str, params: Sequence[Any] | None = None) -> list[dict[str, Any]]:
         """Execute a query and return results as list of dicts."""
+        self._validate_params(params)
         columns, rows = await self._run_protocol(lambda p, db: p.query_sql(db, sql, params))
         return [dict(zip(columns, row, strict=True)) for row in rows]
 
     async def fetchall(self, sql: str, params: Sequence[Any] | None = None) -> list[list[Any]]:
         """Execute a query and return results as list of lists."""
+        self._validate_params(params)
         _, rows = await self._run_protocol(lambda p, db: p.query_sql(db, sql, params))
         return rows
 
@@ -318,6 +332,7 @@ async def fetchone(
 
     async def fetchval(self, sql: str, params: Sequence[Any] | None = None) -> Any:
         """Execute a query and return the first column of the first row."""
+        self._validate_params(params)
         _, rows = await self._run_protocol(lambda p, db: p.query_sql(db, sql, params))
         if rows and rows[0]:
             return rows[0][0]

tests/test_connection.py

@@ -841,6 +841,15 @@ async def test_commit_failure_invalidates_connection(self, connected_connection)
                 pass
         assert not conn.is_connected, "failed COMMIT must invalidate the connection"
 
+    async def test_string_params_rejected_with_clear_error(self, connected_connection) -> None:
+        """Passing a bare string as params silently splits it into N character
+        parameters. Guard at the client boundary so the user gets a clear
+        TypeError instead of a confusing server-side "wrong parameter count".
+        """
+        conn, _, _ = connected_connection
+        with pytest.raises(TypeError, match="list or tuple"):
+            await conn.execute("SELECT ?", "alice")  # type: ignore[arg-type]
+
     async def test_cross_event_loop_raises_interface_error(self) -> None:
         """Using a connection from a different event loop must raise InterfaceError."""
         import asyncio