Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

sql: the row cap bounds the fetch itself, not only the SQL (#497)

Abhishek Jha82562f4fa825
diff --git a/gateway/sql_plane.py b/gateway/sql_plane.py
index b39dccc8..a689167f 100644
--- a/gateway/sql_plane.py
+++ b/gateway/sql_plane.py
@@ -191,7 +191,18 @@ async def _pg_query(dsn: str, sql: str, timeout: float, max_rows: int) -> dict:
# A read-only transaction: the gate above is a parser, this is the database's own opinion.
# Belt and braces, and this one cannot be fooled by clever text.
async with conn.transaction(readonly=True):
- recs = await asyncio.wait_for(conn.fetch(sql), timeout=timeout)
+ # The fetch itself is bounded: the row cap must not depend on the SQL rewrite,
+ # because a statement's own large LIMIT is never rewritten and would otherwise
+ # load every row into memory before slicing. A server-side cursor streams the
+ # first max_rows + 1 rows and the database never materialises the rest.
+ # conn.cursor() returns a CursorFactory, not a Cursor: awaiting it opens the
+ # real server-side cursor. (asyncpg's Cursor exposes fetch/fetchrow/forward
+ # only — there is no Cursor.close() and no async context manager; the portal
+ # is bound to this read-only transaction and is destroyed when the block exits.)
+ async def first_rows():
+ cur = await conn.cursor(sql) # prepares and binds: under the timeout too
+ return await cur.fetch(max_rows + 1)
+ recs = await asyncio.wait_for(first_rows(), timeout=timeout)
cols = list(recs[0].keys()) if recs else []
return _rows_out(cols, [tuple(r.values()) for r in recs], max_rows)
except asyncio.TimeoutError as e:
@@ -215,18 +226,26 @@ async def _mysql_query(dsn: str, sql: str, timeout: float, max_rows: int) -> dic
try:
conn = await asyncio.wait_for(aiomysql.connect(**parsed), timeout=timeout)
await _vet_peer(conn)
- async with conn.cursor() as cur:
- # MySQL has no read-only transaction that survives a plain connection cleanly, so the
- # session is set read-only where the server supports it and the parser carries the
- # rest. Documented, not pretended.
- with_suppress = "SET SESSION TRANSACTION READ ONLY"
- try:
- await cur.execute(with_suppress)
- except Exception:
- pass
- await asyncio.wait_for(cur.execute(sql), timeout=timeout)
- recs = await cur.fetchall()
- cols = [d[0] for d in (cur.description or [])]
+ # Bounded like the Postgres path: the row cap must not depend on the SQL rewrite, because a
+ # statement's own large LIMIT is never rewritten. The cursor is UNBUFFERED: aiomysql's
+ # default one reads the whole result into memory inside execute(), before any fetch could
+ # bound it. And it is never closed: closing an unbuffered cursor reads the rest of the
+ # result off the wire. Closing the connection (below) drops the rest instead.
+ cur = await conn.cursor(aiomysql.SSCursor)
+ # MySQL has no read-only transaction that survives a plain connection cleanly, so the
+ # session is set read-only where the server supports it and the parser carries the
+ # rest. Documented, not pretended.
+ with_suppress = "SET SESSION TRANSACTION READ ONLY"
+ try:
+ await cur.execute(with_suppress)
+ except Exception:
+ pass
+
+ async def first_rows():
+ await cur.execute(sql)
+ return await cur.fetchmany(max_rows + 1) # rows stream now: under the timeout too
+ recs = await asyncio.wait_for(first_rows(), timeout=timeout)
+ cols = [d[0] for d in (cur.description or [])]
return _rows_out(cols, list(recs), max_rows)
except asyncio.TimeoutError as e:
raise SqlError(f"The query did not finish within {int(timeout)}s.") from e
diff --git a/gateway/tests/test_pinned_address.py b/gateway/tests/test_pinned_address.py
index 0644131a..6f628051 100644
--- a/gateway/tests/test_pinned_address.py
+++ b/gateway/tests/test_pinned_address.py
@@ -137,13 +137,17 @@ def _fake_pg(monkeypatch, peer):
def transaction(self, readonly=False):
return _Tx()
- async def fetch(self, sql):
+ async def cursor(self, sql): # asyncpg: an awaited cursor factory opens the cursor
ran.append(sql)
- return []
+ return Cursor()
async def close(self):
pass
+ class Cursor:
+ async def fetch(self, n):
+ return []
+
async def connect(dsn):
return Conn()
monkeypatch.setitem(sys.modules, "asyncpg", types.SimpleNamespace(connect=connect))
diff --git a/gateway/tests/test_sql_plane.py b/gateway/tests/test_sql_plane.py
index 4f6bd241..01625036 100644
--- a/gateway/tests/test_sql_plane.py
+++ b/gateway/tests/test_sql_plane.py
@@ -171,3 +171,178 @@ def test_a_result_within_the_cap_is_not_marked_truncated(monkeypatch):
assert out["row_count"] == 10 and out["truncated"] is False
out = run("SELECT x FROM small", 50)
assert out["row_count"] == 10 and out["truncated"] is False and out["limit_applied"] == 50
+
+
+# ── the fetch itself is bounded, not just the SQL ──────────────────────────────
+# #493: the row cap was enforced by appending LIMIT to the SQL and slicing after
+# fetchall(). A statement carrying its own large LIMIT (or MySQL's all-rows idiom)
+# was never rewritten, so the driver loaded every row into memory first. The fix
+# bounds the fetch at the driver: the plane must return max_rows rows, mark
+# truncated, and never ask the driver for more than max_rows + 1.
+
+class _PgRecord(dict):
+ pass # asyncpg Records answer .keys()/.values()
+
+
+class _PgCursor:
+ # Mirrors asyncpg's real Cursor: fetch/fetchrow/forward only. There is deliberately
+ # NO close() here — asyncpg has none, so production code calling cur.close() would
+ # raise AttributeError and fail the test instead of passing silently.
+ def __init__(self, rows):
+ self._rows = rows
+ self.fetched = None
+
+ async def fetch(self, n):
+ self.fetched = n
+ return self._rows[:n]
+
+
+class _PgConn:
+ def __init__(self, cursor):
+ self._cursor = cursor
+
+ async def cursor(self, sql):
+ # Mirrors asyncpg: Connection.cursor() returns an awaitable CursorFactory,
+ # and awaiting it opens the real server-side cursor.
+ return self._cursor
+
+ def transaction(self, readonly=False):
+ class _Tx:
+ async def __aenter__(self):
+ return None
+
+ async def __aexit__(self, *a):
+ return False
+
+ return _Tx()
+
+ async def close(self):
+ pass
+
+
+def _stub_asyncpg(monkeypatch, conn):
+ import sys
+ import types
+
+ mod = types.ModuleType("asyncpg")
+
+ async def connect(dsn):
+ return conn
+
+ mod.connect = connect
+ monkeypatch.setitem(sys.modules, "asyncpg", mod)
+
+
+class _SSCursor:
+ """Stands for aiomysql.SSCursor, the unbuffered cursor class."""
+
+
+class _MysqlCursor:
+ def __init__(self, rows):
+ self._rows = rows
+ self.fetched = None
+ self.closed = False
+ self.description = [("x",)]
+
+ async def execute(self, sql):
+ pass
+
+ async def fetchmany(self, n):
+ self.fetched = n
+ return self._rows[:n]
+
+ async def close(self):
+ # An unbuffered cursor's close() reads the rest of the result off the wire.
+ self.closed = True
+
+
+class _MysqlConn:
+ def __init__(self, cursor):
+ self._cursor = cursor
+ self.cursor_classes = None
+ self.closed = False
+
+ async def cursor(self, *classes): # aiomysql's cursor() is awaitable
+ self.cursor_classes = classes
+ return self._cursor
+
+ def close(self):
+ self.closed = True
+
+
+def _stub_aiomysql(monkeypatch, conn):
+ import sys
+ import types
+
+ mod = types.ModuleType("aiomysql")
+
+ async def connect(**kw):
+ return conn
+
+ mod.connect = connect
+ mod.SSCursor = _SSCursor
+ monkeypatch.setitem(sys.modules, "aiomysql", mod)
+
+
+def test_the_postgres_fetch_never_asks_for_more_than_the_cap_plus_one(monkeypatch):
+ """The stand-in engine ignores the appended LIMIT and returns the statement's own
+ huge result; the plane still returns max_rows rows, says truncated, and the driver
+ was asked for exactly max_rows + 1."""
+ import asyncio
+ import sql_plane
+
+ rows = [_PgRecord({"x": i}) for i in range(10_000)]
+ cur = _PgCursor(rows)
+ _stub_asyncpg(monkeypatch, _PgConn(cur))
+ out = asyncio.run(sql_plane._pg_query("postgres://u@h/db", "SELECT x FROM t LIMIT 1000000", 5.0, 100))
+ assert out["row_count"] == 100 and out["truncated"] is True
+ assert cur.fetched == 101, f"driver asked for {cur.fetched} rows, not 101"
+ # No close() assertion: asyncpg's Cursor has no close() — the server-side portal
+ # is bound to the read-only transaction and dies when the block exits.
+
+
+def test_the_mysql_fetch_never_asks_for_more_than_the_cap_plus_one(monkeypatch):
+ """MySQL's all-rows idiom `LIMIT 0, 18446744073709551615` is never rewritten; with a
+ bounded fetchmany the driver still hands over at most max_rows + 1 rows."""
+ import asyncio
+ import sql_plane
+
+ rows = [(i,) for i in range(10_000)]
+ cur = _MysqlCursor(rows)
+ conn = _MysqlConn(cur)
+ _stub_aiomysql(monkeypatch, conn)
+ out = asyncio.run(sql_plane._mysql_query(
+ "mysql://u@h/db", "SELECT x FROM t LIMIT 0, 18446744073709551615", 5.0, 100))
+ assert out["row_count"] == 100 and out["truncated"] is True
+ assert cur.fetched == 101, f"driver asked for {cur.fetched} rows, not 101"
+ # The default cursor buffers the whole result inside execute(): only an unbuffered one is bounded.
+ assert conn.cursor_classes == (_SSCursor,)
+ # Closing the unbuffered cursor would read the rest of the result; the connection is closed instead.
+ assert not cur.closed and conn.closed
+
+
+def test_the_postgres_cursor_calls_match_real_asyncpg():
+ """Regression guard for the #497 review thread: asyncpg's Connection.cursor() returns
+ an awaitable CursorFactory (NOT a Cursor), and Cursor exposes fetch/fetchrow/forward
+ only — no close(), no async context manager. The stub above mirrors this; if a future
+ asyncpg changes the interface, this fails loudly instead of shipping a broken call."""
+ import inspect
+
+ asyncpg = pytest.importorskip("asyncpg")
+ from asyncpg.cursor import Cursor, CursorFactory
+
+ assert not inspect.iscoroutinefunction(asyncpg.Connection.cursor)
+ assert hasattr(CursorFactory, "__await__")
+ assert not hasattr(CursorFactory, "fetch")
+ assert hasattr(Cursor, "fetch")
+ assert not hasattr(Cursor, "close")
+ assert not hasattr(Cursor, "__aenter__")
+
+
+def test_the_mysql_cursor_calls_match_real_aiomysql():
+ """Guard for the MySQL stubs above: aiomysql's SSCursor is its unbuffered cursor, and its close()
+ is its own (it reads the rest of the result off the wire), which is why the plane closes the
+ connection instead of the cursor."""
+ aiomysql = pytest.importorskip("aiomysql")
+ assert issubclass(aiomysql.SSCursor, aiomysql.Cursor)
+ assert aiomysql.SSCursor.close is not aiomysql.Cursor.close