execsql2 2.28.0__py3-none-any.whl → 2.30.0__py3-none-any.whl

execsql/__main__.py

@@ -1,11 +1,10 @@
-from __future__ import annotations
+"""Entry point for ``python -m execsql``.
 
+Calls :func:`execsql.cli._legacy_main`, so the package runs without the
+installed ``execsql`` script.
 """
-Entry point for ``python -m execsql``.
 
-Delegates immediately to :func:`execsql.cli.main` so the package can be
-invoked directly without going through the installed ``execsql2`` script.
-"""
+from __future__ import annotations
 
 from execsql.cli import _legacy_main
 

execsql/api.py

@@ -594,6 +594,11 @@ def run(
                     pass
             if ctx.tempfiles is not None:
                 ctx.tempfiles.remove_all()
+            if ctx.cd_from is not None:  # the script ran CD: the caller's directory is theirs
+                try:
+                    os.chdir(ctx.cd_from)
+                except OSError:
+                    pass  # it no longer exists
 
     return ScriptResult(
         success=len(errors) == 0,

execsql/cli/__init__.py

@@ -22,31 +22,20 @@ from pathlib import Path
 
 from execsql.cli import commands  # noqa: F401 — registers every command on app
 from execsql.cli.application import app
-from execsql.cli.commands.run import main
-from execsql.cli.dsn import _parse_connection_string, _SCHEME_TO_DBTYPE  # noqa: F401 — re-export
-from execsql.cli.help import _console, _err_console, _init_config, _print_encodings, _print_metacommands  # noqa: F401 — re-export
-from execsql.cli.run import _connect_initial_db, _run  # noqa: F401 — re-export
-from execsql.cli.run import _end_run_on_sigterm
+from execsql.cli.dsn import _parse_connection_string  # noqa: F401 — re-export
+from execsql.cli.run import _end_run_on_sigterm, _run  # noqa: F401 — re-export
 from execsql.exceptions import ConfigError, ConfigFileError, ErrInfo
 
 __all__ = [
-    "_SCHEME_TO_DBTYPE",
-    "_connect_initial_db",
-    "_console",
-    "_err_console",
-    "_init_config",
     "_legacy_main",
     "_parse_connection_string",
-    "_print_encodings",
-    "_print_metacommands",
     "_run",
     "app",
-    "main",
 ]
 
 
 # ---------------------------------------------------------------------------
-# Legacy entry point (kept for backwards compat with pyproject.toml script)
+# Entry point for ``python -m execsql`` (the ``execsql`` script is cli.dispatch:dispatch)
 # ---------------------------------------------------------------------------
 
 

execsql/cli/application.py

@@ -6,6 +6,7 @@ Every command registers itself on :data:`app` from a module in
 
 from __future__ import annotations
 
+import sys
 from collections.abc import Iterator
 from contextlib import contextmanager
 from typing import Any
@@ -225,7 +226,9 @@ class ExecsqlGroup(TyperGroup):
         self.format_commands(ctx, formatter)
 
     def format_commands(self, ctx: Any, formatter: Any) -> None:
-        # Click's own version, with the command names colored.
+        # Click's own version, with the command names colored and each
+        # summary (the first sentence of its help) whole: Click would cut it
+        # to fit the terminal with "...", write_dl wraps it instead.
         commands = [
             (name, cmd)
             for name in self.list_commands(ctx)
@@ -233,10 +236,9 @@ class ExecsqlGroup(TyperGroup):
         ]
         if not commands:
             return
-        limit = formatter.width - 6 - max(len(name) for name, _ in commands)
         with _section(formatter, "Commands"):
             formatter.write_dl(
-                [(_style(name, fg="cyan", bold=True), cmd.get_short_help_str(limit)) for name, cmd in commands],
+                [(_style(name, fg="cyan", bold=True), cmd.get_short_help_str(sys.maxsize)) for name, cmd in commands],
             )
 
 

execsql/cli/commands/lint.py

@@ -93,7 +93,10 @@ def lint_paths(
         except OSError as exc:
             found = [_issue("P001", label, 0, f"cannot read: {exc.strerror or exc}")]
         else:
-            found = lint_source(source, label, script_path=None if stdin else label)
+            try:
+                found = lint_source(source, label, script_path=None if stdin else label)
+            except Exception as exc:  # one script lint cannot check must not hide the others' findings
+                found = [_issue("P001", label, 0, f"execsql could not check this script ({type(exc).__name__}: {exc})")]
         per_file.append((label, sorted(filter_issues(found, select, ignore), key=lambda i: (i.line, i.code))))
 
     reported = [issue for _, issues in per_file for issue in issues]

execsql/cli/commands/lsp.py

@@ -2,6 +2,10 @@
 
 from __future__ import annotations
 
+import logging
+from enum import Enum
+from pathlib import Path
+
 import typer
 from rich.markup import escape
 
@@ -28,6 +32,29 @@ def _pygls_version() -> str:
         return "unknown"
 
 
+class LogLevel(str, Enum):
+    error = "error"
+    warning = "warning"
+    info = "info"
+    debug = "debug"
+
+
+def _configure_logging(level: LogLevel, log_file: Path | None) -> None:
+    """Send the server's log (execsql's and pygls's) to stderr, which editors show, or to *log_file*.
+
+    stdout carries the protocol, so nothing may be logged there.
+    """
+    handler: logging.Handler = (
+        logging.FileHandler(log_file, encoding="utf-8") if log_file is not None else logging.StreamHandler()
+    )
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+    root = logging.getLogger()
+    root.addHandler(handler)
+    root.setLevel(level.value.upper())
+    # pygls logs every message it sends at info, script text included: only debug shows them.
+    logging.getLogger("pygls").setLevel(logging.DEBUG if level is LogLevel.debug else logging.WARNING)
+
+
 @app.command(
     cls=ExecsqlCommand,
     name="lsp",
@@ -43,6 +70,20 @@ def lsp_cmd(
     # Editors' language clients pass --stdio (VS Code always does); stdio is the only transport.
     stdio: bool = typer.Option(False, "--stdio", hidden=True),
     check: bool = typer.Option(False, "--check", help="Report whether the language server can start, and exit."),
+    log_level: LogLevel = typer.Option(
+        LogLevel.warning,
+        "--log-level",
+        envvar="EXECSQL_LSP_LOG_LEVEL",
+        case_sensitive=False,
+        help="How much the server logs: error, warning, info (adds a startup record and each folder's config files) "
+        "or debug (adds every protocol message).",
+    ),
+    log_file: Path | None = typer.Option(
+        None,
+        "--log-file",
+        dir_okay=False,
+        help="Append the log to this file instead of stderr, for an editor that does not show the server's stderr.",
+    ),
 ) -> None:
     """The ``lsp`` command; its user-facing help is the decorator's ``help``."""
     try:
@@ -61,4 +102,5 @@ def lsp_cmd(
     if check:
         typer.echo(f"execsql lsp is ready (pygls {_pygls_version()}).")
         return
+    _configure_logging(log_level, log_file)
     create_server().start_io()

execsql/cli/dsn.py

@@ -50,7 +50,9 @@ def _parse_connection_string(dsn: str) -> dict:
     parsed = urlparse(dsn)
     scheme = parsed.scheme.lower()
     if not scheme:
-        raise ConfigError(f"Cannot parse connection string (no scheme): {dsn!r}")
+        # Echoed so the user sees what went wrong, but never with its password.
+        shown = dsn.replace(f":{parsed.password}@", ":***@") if parsed.password else dsn
+        raise ConfigError(f"Cannot parse connection string (no scheme): {shown!r}")
     if scheme not in _SCHEME_TO_DBTYPE:
         raise ConfigError(
             f"Unrecognised connection-string scheme {scheme!r}. "

execsql/cli/lint.py

@@ -471,7 +471,7 @@ def _read_ini_vars(
         if stat.st_size > _MAX_INI_BYTES:
             return
         resolved = str(p.resolve())
-    except OSError:
+    except (OSError, ValueError):  # unreadable, or a name the OS rejects
         return
     defined_vars.update(_ini_section_keys(resolved, stat.st_size, stat.st_mtime_ns, section))
 
@@ -587,7 +587,12 @@ def _check_include_path(
     if not p.is_absolute() and script_dir is not None:
         p = script_dir / p
 
-    if not p.exists():
+    try:
+        exists = p.exists()
+    except OSError as exc:  # a name the file system rejects outright (too long, ...)
+        issues.append(_issue("I001", source, line_no, f"INCLUDE path cannot be checked: {exc.strerror or exc}"))
+        return
+    if not exists:
         issues.append(
             _issue("I001", source, line_no, f"INCLUDE file does not exist: {raw_path}"),
         )
@@ -701,7 +706,7 @@ _RX_ANY_VAR = re.compile(r"!(['\"]?)![$&@~#+]?\w+!\1!|!\{[$&@~#+]?\w+\}!")
 _PLACEHOLDERS = ("TRUE", "1", "x")
 
 
-def _with_placeholders(text: str, value: str = "TRUE") -> str:
+def _with_placeholders(text: str, value: str) -> str:
     """Replace each substitution variable with the literal *value*."""
     return _RX_ANY_VAR.sub(value, text)
 
@@ -997,6 +1002,7 @@ def _lint_nodes(
 def lint(
     script: Script,
     script_path: str | None = None,
+    base_dir: str | None = None,
 ) -> list[_Issue]:
     """Perform static analysis on an AST-parsed script.
 
@@ -1004,6 +1010,8 @@ def lint(
         script: The parsed :class:`Script` tree.
         script_path: Path to the source file (for resolving relative
             INCLUDE paths).  ``None`` for inline scripts.
+        base_dir: Where an inline script's relative paths resolve, in place
+            of the working directory.
 
     Returns:
         Every :class:`Issue` found, unfiltered.
@@ -1014,7 +1022,7 @@ def lint(
         issues.append(_issue("S001", script_path or script.source, 0, "script is empty"))
         return issues
 
-    script_dir = Path(script_path).resolve().parent if script_path else None
+    script_dir = Path(script_path).resolve().parent if script_path else (Path(base_dir) if base_dir else None)
     script_blocks = _collect_script_blocks(script)
 
     # Pass 1: collect all variable definitions
@@ -1036,7 +1044,7 @@ def lint(
     return issues
 
 
-def lint_source(source: str, label: str, script_path: str | None = None) -> list[_Issue]:
+def lint_source(source: str, label: str, script_path: str | None = None, base_dir: str | None = None) -> list[_Issue]:
     """Parse *source* and lint it, unfiltered.
 
     Each block-structure error (an IF without ENDIF, a stray END LOOP, ...)
@@ -1047,7 +1055,7 @@ def lint_source(source: str, label: str, script_path: str | None = None) -> list
 
     errors: list[ErrInfo] = []
     tree = parse_string(source, label, errors=errors)
-    return [parse_error(label, exc) for exc in errors] + lint(tree, script_path=script_path)
+    return [parse_error(label, exc) for exc in errors] + lint(tree, script_path=script_path, base_dir=base_dir)
 
 
 # ---------------------------------------------------------------------------

execsql/cli/run.py

@@ -233,11 +233,12 @@ _SENSITIVE_SUBSTRINGS = (
 )
 
 
-def _seed_early_subvars() -> SubVarSet:
+def _seed_early_subvars(start_dir: str | None = None) -> SubVarSet:
     """Create and populate the initial substitution variable pool.
 
     Seeds environment variables (filtering secrets), timestamps, system info,
     and placeholder variables.  Called once at the start of :func:`_run`.
+    ``$STARTING_PATH`` is *start_dir*, or the working directory.
     """
     subvars = SubVarSet()
 
@@ -262,7 +263,7 @@ def _seed_early_subvars() -> SubVarSet:
     subvars.add_substitution("$LAST_ERROR", "")
     subvars.add_substitution("$ERROR_MESSAGE", "")
     subvars.add_substitution("$USER", getpass.getuser())
-    subvars.add_substitution("$STARTING_PATH", os.getcwd() + os.sep)
+    subvars.add_substitution("$STARTING_PATH", (start_dir or os.getcwd()) + os.sep)
     subvars.add_substitution("$PATHSEP", os.sep)
     osys = sys.platform
     if osys.startswith("linux"):
@@ -279,23 +280,30 @@ def _load_config(
     script_name: str | None,
     subvars: SubVarSet,
     config_file: str | None,
+    start_dir: str | None = None,
 ) -> ConfigData:
     """Load and merge configuration files for the given script.
 
+    *start_dir* stands in for the working directory (see :class:`ConfigData`).
     Returns a fully populated :class:`ConfigData` instance.
     """
-    script_path = str(Path(script_name).resolve().parent) if script_name else os.getcwd()
-    return ConfigData(script_path, subvars, config_file=config_file)
+    if script_name:
+        script_path = str(Path(script_name).resolve().parent)
+    else:  # resolved, as os.getcwd() is, so the start directory's execsql.conf is not read twice
+        script_path = str(Path(start_dir).resolve()) if start_dir else os.getcwd()
+    return ConfigData(script_path, subvars, config_file=config_file, start_dir=start_dir)
 
 
-def _tool_config(config_file: str | None) -> ConfigData:
+def _tool_config(config_file: str | None, start_dir: str | None = None) -> ConfigData:
     """The config ``execsql format`` and ``execsql lint`` read.
 
     Read once per invocation, from the system, user and working-directory
     locations plus *config_file* — not per script, so a script directory's
-    own ``execsql.conf`` applies only when passed with ``--config``.
+    own ``execsql.conf`` applies only when passed with ``--config``.  The
+    language server passes a workspace folder as *start_dir*: the settings
+    those commands would read when run from it.
     """
-    return _load_config(None, _seed_early_subvars(), config_file)
+    return _load_config(None, _seed_early_subvars(start_dir), config_file, start_dir)
 
 
 def _configured_script_encoding(conf: ConfigData) -> str | None:
@@ -561,7 +569,7 @@ def _setup_logging(
         for n, repl in enumerate(sub_vars):
             var = f"$ARG_{n + 1}"
             subvars.add_substitution(var, repl)
-            logger.add_redaction_value(repl)
+            logger.add_redaction_value(repl, argument=True)
             # `-a` values are positional and opaque (no name to denylist
             # against). High-entropy secrets (sk-live-*, AKIA*, ghp_*,
             # JWTs) pass any substring/value heuristic, so log the
@@ -574,7 +582,7 @@ def _setup_logging(
     # redacted for the same reason as -a's.
     for name, value in named_vars or ():
         subvars.add_substitution(name, value)
-        logger.add_redaction_value(value)
+        logger.add_redaction_value(value, argument=True)
         logger.log_status_info(f"Command-line substitution variable assignment: {name} set to {{***}}")
 
     return logger

execsql/config.py

@@ -401,6 +401,7 @@ class ConfigData:
         variable_pool: _VariablePool,
         *,
         config_file: str | None = None,
+        start_dir: str | None = None,
     ) -> None:
         """Load and merge all discoverable execsql.conf files for the given script path.
 
@@ -414,12 +415,18 @@ class ConfigData:
                 Loaded after the implicit search paths so its values take
                 precedence over system, user, script, and working-directory
                 config files.
+            start_dir: The directory a run starts in: its ``execsql.conf`` is
+                read, and relative ``config_file`` paths (``--config`` and
+                ``[config]`` chains) resolve against it.  Defaults to the
+                working directory.  The language server passes each
+                workspace folder, so it never changes the process's directory.
         """
+        self._start_dir = start_dir
         self._set_defaults()
         current_script = str(Path(sys.argv[0]).resolve())
         from collections import deque
 
-        config_queue: deque[str] = deque(self._search_paths(script_path, config_file))
+        config_queue: deque[str] = deque(self._search_paths(script_path, config_file, start_dir))
         self.files_read: list = []
         # Warm the schema registry by running the option reader against an
         # empty ConfigParser. cp.has_option() is False for everything so no
@@ -455,6 +462,9 @@ class ConfigData:
                     if cp.has_option(section, key):
                         self.sources[attr] = configfile
 
+    #: Where relative paths resolve; ``None`` is the working directory.
+    _start_dir: str | None = None
+
     #: Guard against circular config_file references.
     _MAX_CONFIG_CHAIN = 20
 
@@ -562,7 +572,7 @@ class ConfigData:
         self.lint_strict = False
 
     @classmethod
-    def _search_paths(cls, script_path: str, config_file: str | None) -> list[str]:
+    def _search_paths(cls, script_path: str, config_file: str | None, start_dir: str | None = None) -> list[str]:
         """The files a run reads, lowest precedence first: system, user, script dir, working dir, ``--config``.
 
         Files that ``[config] config_file`` and its OS-specific variants chain
@@ -574,17 +584,25 @@ class ConfigData:
             sys_config_file = str(Path(os.path.expandvars(r"%APPDATA%")) / cls.config_file_name)
         user_config_file = str(Path("~/.config").expanduser() / cls.config_file_name)
         script_config_file = str(Path(script_path) / cls.config_file_name)
-        startdir_config_file = str(Path(".").resolve() / cls.config_file_name)
+        start = Path(start_dir or ".")
+        startdir_config_file = str(start.resolve() / cls.config_file_name)
         if startdir_config_file != script_config_file:
             config_files = [sys_config_file, user_config_file, script_config_file, startdir_config_file]
         else:
             config_files = [sys_config_file, user_config_file, startdir_config_file]
         if config_file:
-            config_files.append(str(Path(config_file).resolve()))
+            config_files.append(str((start / config_file).resolve()))
         return config_files
 
     @classmethod
-    def _chain_target(cls, value: str, variable_pool: _VariablePool, *, expand_home: bool) -> str:
+    def _chain_target(
+        cls,
+        value: str,
+        variable_pool: _VariablePool,
+        *,
+        expand_home: bool,
+        start_dir: str | None = None,
+    ) -> str:
         """Resolve a ``config_file``-style value to the file it names.
 
         A leading ``~`` is expanded when *expand_home* is true, substitution
@@ -598,6 +616,8 @@ class ConfigData:
             elif len(conffile) > 1 and conffile[1] == os.sep:
                 conffile = str(Path("~").expanduser() / conffile[2:])
         conffile = variable_pool.substitute(conffile)[0]
+        if start_dir and not Path(conffile).is_absolute():
+            conffile = str(Path(start_dir) / conffile)
         if not Path(conffile).is_file():
             conffile = str(Path(conffile) / cls.config_file_name)
         return conffile
@@ -651,6 +671,7 @@ class ConfigData:
                 cp.get(self._CONFIG_SECTION, "config_file"),
                 variable_pool,
                 expand_home=os.name == "posix",
+                start_dir=self._start_dir,
             )
             if Path(conffile).is_file():
                 # Silently ignore a non-existent file, for cross-OS compatibility.
@@ -664,7 +685,12 @@ class ConfigData:
         elif os.name == "nt" and cp.has_option(self._CONFIG_SECTION, "win_config_file"):
             _os_config_key = "win_config_file"
         if _os_config_key:
-            conffile = self._chain_target(cp.get(self._CONFIG_SECTION, _os_config_key), variable_pool, expand_home=True)
+            conffile = self._chain_target(
+                cp.get(self._CONFIG_SECTION, _os_config_key),
+                variable_pool,
+                expand_home=True,
+                start_dir=self._start_dir,
+            )
             if Path(conffile).is_file():
                 chained.append(conffile)
         # dao_flush_delay_secs has a specific error message — keep inline

execsql/db/base.py

@@ -215,21 +215,18 @@ class Database(ABC):
     def quote_literal(self, value: Any) -> str:
         """Return *value* as a SQL string literal, safely escaped.
 
-        Default ANSI/Postgres behaviour: wrap in single quotes, double
-        embedded apostrophes, escape backslashes (so a value containing
-        ``\\'`` cannot terminate the literal on MySQL default mode or
-        PostgreSQL E-strings), and reject embedded NUL bytes (most
-        wire protocols truncate or reject them).
-
-        Override per-DBMS only when the wire protocol requires a different
-        literal form.
+        Standard SQL: wrap in single quotes and double embedded apostrophes;
+        a backslash is an ordinary character.  Embedded NUL bytes are
+        rejected (most wire protocols truncate or reject them).  A DBMS
+        that reads a backslash in a literal as an escape (MySQL) overrides
+        this.
         """
         if value is None:
             return "NULL"
         s = str(value)
         if "\x00" in s:
             raise ValueError("SQL literal contains a NUL byte; refusing to quote.")
-        return "'" + s.replace("\\", "\\\\").replace("'", "''") + "'"
+        return "'" + s.replace("'", "''") + "'"
 
     def paramsubs(self, paramcount: int) -> str:
         """Return a comma-separated string of *paramcount* parameter placeholders."""

execsql/db/duckdb.py

@@ -9,6 +9,7 @@ on the CLI.
 """
 
 import re
+from collections import deque
 from pathlib import Path
 from typing import Any
 
@@ -28,21 +29,83 @@ _TRANSACTION_RX = re.compile(r"(?P<begin>BEGIN|START\s+TRANSACTION)\b|(?P<end>CO
 
 
 class _SharedCursor:
-    """The connection, used as a cursor so a statement joins its open transaction.
-
-    A DuckDB cursor is a separate connection with a transaction of its own,
-    and closing it rolls that transaction back.  ``close()`` therefore leaves
-    the connection open.
+    """A cursor that runs on the database's one connection.
+
+    A DuckDB cursor is a separate connection: a temporary table created on
+    one is invisible to the next, and a cursor's transaction is its own.  So
+    every statement runs on the connection itself.  A connection holds one
+    pending result, though, and the next statement discards it; COPY reads
+    its source twice at once (the rows, and a scan for their types).  So
+    before another statement runs, the result this cursor still has to
+    deliver is read into memory (:meth:`DuckDBDatabase._take_connection`).
+    An EXPORT, which runs nothing else while it reads, still streams.
     """
 
-    def __init__(self, conn: Any) -> None:
-        self._conn = conn
+    def __init__(self, db: DuckDBDatabase) -> None:
+        self._db = db
+        self._conn = db.conn
+        self._buffer: deque[Any] | None = None  # the rest of the result, once read ahead
+        self._pending = False  # a result the connection still holds for this cursor
+        self.description: Any = None
+        self.arraysize = 1000
 
     def __getattr__(self, name: str) -> Any:
         return getattr(self._conn, name)
 
+    def execute(self, sql: Any, params: Any = None) -> _SharedCursor:
+        self._db._take_connection(self)
+        if params is None:
+            self._conn.execute(sql)
+        else:
+            self._conn.execute(sql, params)
+        self.description = self._conn.description
+        self._buffer = None
+        self._pending = self.description is not None
+        return self
+
+    def executemany(self, sql: Any, params: Any) -> _SharedCursor:
+        self._db._take_connection(self)
+        self._conn.executemany(sql, params)
+        self.description = self._conn.description
+        self._buffer = None
+        self._pending = False
+        return self
+
+    def read_ahead(self) -> None:
+        """Move the rest of the pending result into memory, freeing the connection."""
+        if self._pending:
+            self._buffer = deque(self._conn.fetchall())
+            self._pending = False
+
+    def fetchmany(self, size: int | None = None) -> list[Any]:
+        size = size or self.arraysize
+        if self._buffer is not None:
+            return [self._buffer.popleft() for _ in range(min(size, len(self._buffer)))]
+        if not self._pending:
+            return []
+        rows: list[Any] = self._conn.fetchmany(size)
+        if not rows:
+            self._pending = False
+        return rows
+
+    def fetchone(self) -> Any:
+        rows = self.fetchmany(1)
+        return rows[0] if rows else None
+
+    def fetchall(self) -> list[Any]:
+        if self._buffer is not None:
+            rows, self._buffer = list(self._buffer), deque()
+            return rows
+        if not self._pending:
+            return []
+        self._pending = False
+        return list(self._conn.fetchall())
+
     def close(self) -> None:
-        pass
+        """Leave the connection, and any transaction on it, open."""
+        self._buffer = None
+        self._pending = False
+        self._db._release_connection(self)
 
 
 class DuckDBDatabase(Database):
@@ -51,12 +114,15 @@ class DuckDBDatabase(Database):
     The duckdb driver commits each statement unless a transaction was begun,
     and has no way to ask whether one is open, so this adapter begins one
     itself while statements are held (AUTOCOMMIT OFF, BEGIN BATCH) and keeps
-    track of it.  While it is open, every statement runs on the connection
-    itself rather than on a cursor (see :class:`_SharedCursor`).
+    track of it.  Every statement runs on the connection itself rather than
+    on a cursor (see :class:`_SharedCursor`), so it joins that transaction
+    and sees the run's temporary tables.
     """
 
     #: A transaction this adapter or a script's own BEGIN opened, not yet ended.
     in_transaction: bool = False
+    #: The cursor whose result the connection holds, if any.
+    _holder: _SharedCursor | None = None
 
     def __init__(self, DuckDB_fn: str) -> None:
         try:
@@ -83,12 +149,21 @@ class DuckDBDatabase(Database):
         return f"DuckDBDatabase({self.db_name!r})"
 
     def cursor(self) -> Any:
-        """A cursor, or while a transaction is open, the connection itself."""
+        """A cursor on the database's one connection (see :class:`_SharedCursor`)."""
         if self.conn is None:
             self.open_db()
-        if self.in_transaction:
-            return _SharedCursor(self.conn)
-        return self.conn.cursor()
+        return _SharedCursor(self)
+
+    def _take_connection(self, cursor: _SharedCursor | None = None) -> None:
+        """Before a statement runs, read ahead the result another cursor has not finished with."""
+        holder = self._holder
+        if holder is not None and holder is not cursor:
+            holder.read_ahead()
+        self._holder = cursor
+
+    def _release_connection(self, cursor: _SharedCursor) -> None:
+        if self._holder is cursor:
+            self._holder = None
 
     def begin_transaction(self) -> None:
         """Open a transaction if none is open."""
@@ -96,6 +171,7 @@ class DuckDBDatabase(Database):
             self.open_db()
         if not self.in_transaction:
             # A second BEGIN would abort the open transaction, hence the tracking.
+            self._take_connection()
             self.conn.execute("BEGIN TRANSACTION")
             self.in_transaction = True
 
@@ -124,17 +200,23 @@ class DuckDBDatabase(Database):
 
     def commit(self) -> None:
         """Commit the open transaction if autocommit is enabled."""
+        self._take_connection()
         super().commit()
         if self.autocommit:
             self.in_transaction = False
 
     def rollback(self) -> None:
         """Roll back the open transaction."""
+        try:
+            self._take_connection()
+        except Exception:  # best effort, as the rollback is: a failed transaction may not give up its rows
+            self._holder = None
         super().rollback()
         self.in_transaction = False
 
     def close(self) -> None:
         """Close the connection; an open transaction is rolled back."""
+        self._holder = None
         super().close()
         self.in_transaction = False