sdmxlib 0.27.2__tar.gz → 0.28.0__tar.gz

{sdmxlib-0.27.2 → sdmxlib-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sdmxlib
-Version: 0.27.2
+Version: 0.28.0
 Summary: SDMX structural metadata library for Python
 Keywords: sdmx,statistics,metadata,datastructure
 Author: gabrielgellner

{sdmxlib-0.27.2 → sdmxlib-0.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.27.2"
+version = "0.28.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{sdmxlib-0.27.2 → sdmxlib-0.28.0}/src/sdmxlib/local/_data_store.py

@@ -267,7 +267,8 @@ class DuckDBDataStore:
             order_by=order_by,
             limit=limit,
         )
-        cur = conn.execute(sql, sql_params)
+        # Per-call cursor for issue #75 (concurrent reads).
+        cur = conn.cursor().execute(sql, sql_params)
         col_names = [d[0] for d in cur.description] if cur.description else []
         rows = cur.fetchall()
         if not rows:
@@ -365,7 +366,12 @@ class DuckDBDataStore:
             order_by=order_by,
             limit=None,
         )
-        reader = conn.execute(sql, sql_params).to_arrow_reader(chunk_rows)
+        # Per-call cursor for issue #75 — concurrent ``query_stream``
+        # callers must not share the connection's default-cursor row
+        # buffer. The Arrow reader streams from this cursor and holds
+        # the reference until the generator is exhausted (or GC'd).
+        cur = conn.cursor()
+        reader = cur.execute(sql, sql_params).to_arrow_reader(chunk_rows)
         yield from reader
 
 

{sdmxlib-0.27.2 → sdmxlib-0.28.0}/src/sdmxlib/local/_registry.py

@@ -30,8 +30,9 @@ stashes the URI; the DuckDB connection is opened by ``open()`` /
         local.add(...)
 """
 
-from collections import OrderedDict
-from collections.abc import Iterable
+import threading
+from collections.abc import Iterable, Iterator
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Self
 
@@ -61,18 +62,30 @@ _ITEM_TO_SCHEME: dict[str, tuple[str, str]] = {
 DEFAULT_RESOLVE_CACHE_SIZE = 256
 
 
-class _LRUDict(OrderedDict[str, Any]):
-    """Bounded LRU mapping used as the registry-level resolver cache.
+class _FIFOCache(dict[str, Any]):
+    """Bounded resolver cache. FIFO eviction, lock-free reads.
 
-    Subclasses :class:`OrderedDict` so it can be passed wherever the
-    resolver expects ``dict[str, Any]``. Inserts evict least-recently-used
-    entries past ``maxsize``; reads via :meth:`get` move keys to the end.
-    ``maxsize == 0`` disables caching — inserts are silently dropped, so
-    the structure stays empty.
+    Subclasses :class:`dict` (not ``OrderedDict``) so that ``get`` /
+    ``__contains__`` / ``__getitem__`` are plain dict ops — GIL-atomic
+    in CPython and safe for multiple concurrent reader threads with no
+    locking. Mutations (insert, evict, clear) hold a per-instance
+    :class:`threading.Lock`.
 
-    Tracks ``hits`` / ``misses`` for :meth:`Registry.resolve_cache_info`;
-    ``__contains__`` is treated as internal control flow (the resolver
-    uses it for dedup) and is not counted.
+    Eviction is FIFO (insertion order) rather than LRU. FIFO is a
+    deliberate choice over LRU here: tracking recency would require
+    mutating the cache on every hit, which would force every cache hit
+    onto the lock and serialise reader threads. At realistic working-set
+    sizes for SDMX parent-scheme reuse, the hit-rate difference between
+    FIFO and LRU is small; the lock-free read path is more valuable.
+    Documented as a known trade-off in ``docs/concurrency.md`` — revisit
+    if ``resolve_cache_info()`` ever shows poor hit rates against a
+    working set that should otherwise fit.
+
+    ``maxsize == 0`` disables caching — inserts are silently dropped.
+
+    Hit/miss counters are best-effort under concurrency: lockless ``+=``
+    on the counter ints races, so under contention the reported numbers
+    may slightly under-count. They remain useful as a diagnostic.
     """
 
     def __init__(self, maxsize: int) -> None:
@@ -83,63 +96,72 @@ class _LRUDict(OrderedDict[str, Any]):
         self.maxsize = maxsize
         self.hits = 0
         self.misses = 0
+        self._lock = threading.Lock()
 
     def __setitem__(self, key: str, value: Any) -> None:
         if self.maxsize == 0:
             return
-        if key in self:
-            self.move_to_end(key)
-        super().__setitem__(key, value)
-        while len(self) > self.maxsize:
-            self.popitem(last=False)
+        with self._lock:
+            super().__setitem__(key, value)
+            # Evict insertion-oldest entries past the cap. ``next(iter(self))``
+            # is the first-inserted key for plain dicts in Python 3.7+.
+            while len(self) > self.maxsize:
+                oldest = next(iter(self))
+                super().__delitem__(oldest)
 
     def get(self, key: str, default: Any = None) -> Any:  # type: ignore[override]
+        # Lock-free read: plain dict ``__contains__`` / ``__getitem__``
+        # are GIL-atomic in CPython. The counter increments race under
+        # concurrency — accepted (see class docstring).
         if super().__contains__(key):
             self.hits += 1
-            self.move_to_end(key)
             return super().__getitem__(key)
         self.misses += 1
         return default
 
+    def clear(self) -> None:
+        with self._lock:
+            super().clear()
+
     def reset_stats(self) -> None:
         self.hits = 0
         self.misses = 0
 
 
 class _CallScopedMemo(dict[str, Any]):
-    """Per-call resolver memo layered over a persistent LRU cache.
+    """Per-call resolver memo layered over the persistent FIFO cache.
 
-    Two reasons for the overlay rather than passing the LRU directly:
+    Two reasons for the overlay rather than passing the cache directly:
 
     1. **Correctness under tight cache sizes (incl. ``maxsize=0``).** The
        resolver writes URN→target during one phase and reads them back in
        a later phase of the same call. If those writes went straight to
-       the LRU, an entry could be evicted before the read — leaving Refs
+       the cache, an entry could be evicted before the read — leaving Refs
        unresolved for callers using a small (or disabled) cache. The
        overlay holds in-flight entries in an unbounded per-call dict so
        single-call resolution is independent of cache size.
     2. **Promote-on-success.** Entries written during the call enter the
-       LRU only at the end of the call, via :meth:`promote`. That keeps
-       partial-failure semantics clean: if a call raises midway, the LRU
-       is unchanged.
+       persistent cache only at the end of the call, via :meth:`promote`.
+       That keeps partial-failure semantics clean: if a call raises
+       midway, the persistent cache is unchanged.
     """
 
-    def __init__(self, lru: _LRUDict) -> None:
+    def __init__(self, cache: _FIFOCache) -> None:
         super().__init__()
-        self._lru = lru
+        self._cache = cache
 
     def __contains__(self, key: object) -> bool:
-        return super().__contains__(key) or self._lru.__contains__(key)
+        return super().__contains__(key) or self._cache.__contains__(key)
 
     def get(self, key: str, default: Any = None) -> Any:  # type: ignore[override]
         if super().__contains__(key):
             return super().__getitem__(key)
-        return self._lru.get(key, default)
+        return self._cache.get(key, default)
 
     def promote(self) -> None:
-        """Copy this call's resolved entries into the persistent LRU."""
+        """Copy this call's resolved entries into the persistent cache."""
         for k, v in self.items():
-            self._lru[k] = v
+            self._cache[k] = v
 
 
 class Registry:
@@ -164,6 +186,15 @@ class Registry:
     DuckLake catalog the caller already opened) is done via
     :meth:`from_connection`, which doesn't take ownership of the
     connection's lifecycle.
+
+    **Concurrency.** Reads (``get`` / ``get_all`` / ``codelist`` /
+    ``code_map`` / ``dsd_code_map`` / ``to_registry`` / ``__contains__``
+    / ``__len__``) are safe to call from multiple threads against the
+    same ``Registry``. Writes (``add`` / ``drop`` / ``replace`` /
+    ``add_all`` / ``ingest``) are single-threaded — serialise externally
+    if you need to mutate from multiple threads. See
+    ``docs/design/concurrency.md`` for the model and deployment
+    recipes.
     """
 
     def __init__(
@@ -175,18 +206,20 @@ class Registry:
     ) -> None:
         """Open or wrap a DuckDB-backed registry.
 
-        ``resolve_cache_size`` bounds the LRU of resolved Ref targets that
-        :meth:`get` / :meth:`get_all` / :meth:`to_registry` share across
-        calls. Pass ``0`` to disable caching (matches pre-v0.27.2 behaviour
-        — one full read per Ref). The cache is cleared on every mutation
-        (``add`` / ``drop`` / ``replace``) for invalidation correctness.
+        ``resolve_cache_size`` bounds the FIFO cache of resolved Ref
+        targets that :meth:`get` / :meth:`get_all` / :meth:`to_registry`
+        share across calls. Pass ``0`` to disable caching (matches
+        pre-v0.27.2 behaviour — one full read per Ref). The cache is
+        cleared on every mutation (``add`` / ``drop`` / ``replace``) for
+        invalidation correctness. FIFO eviction (not LRU) keeps cache
+        reads lock-free; see ``docs/concurrency.md``.
         """
         self._uri = Path(uri) if isinstance(uri, str) else uri
         self._source_registry = source_registry
         self._conn: duckdb.DuckDBPyConnection | None = None
         self._cursor: duckdb.DuckDBPyConnection | None = None
         self._owns_connection = True
-        self._resolve_cache: _LRUDict = _LRUDict(resolve_cache_size)
+        self._resolve_cache: _FIFOCache = _FIFOCache(resolve_cache_size)
 
     @property
     def uri(self) -> Path:
@@ -250,7 +283,7 @@ class Registry:
         instance._conn = conn  # noqa: SLF001
         instance._cursor = None  # noqa: SLF001
         instance._owns_connection = False  # noqa: SLF001
-        instance._resolve_cache = _LRUDict(resolve_cache_size)  # noqa: SLF001
+        instance._resolve_cache = _FIFOCache(resolve_cache_size)  # noqa: SLF001
         instance._initialise_schema()  # noqa: SLF001
         return instance
 
@@ -266,6 +299,11 @@ class Registry:
         else:
             self._cursor = self._conn.cursor()
             self._cursor.execute("SET search_path = 'sdmx'")
+        # Also set search_path on the connection's default cursor — used
+        # by code paths that call ``conn.execute()`` directly without
+        # going through ``_read_cursor`` (lazy facades' ``code_map``
+        # forwarder, etc.). Cheap one-shot.
+        self._conn.execute("SET search_path = 'sdmx'")
 
     def __enter__(self) -> Self:
         if self._conn is None:
@@ -289,10 +327,10 @@ class Registry:
     def _c(self) -> duckdb.DuckDBPyConnection:
         """Internal accessor — returns the live cursor or raises a clear error.
 
-        Replaces direct ``self._cursor`` use after the Path-style refactor;
-        every method that touches the database routes through this so the
-        error message points at the lifecycle problem instead of the
-        downstream ``AttributeError`` you'd see with a bare ``None``.
+        Used by write paths (``add`` / ``drop`` / ``replace``) which are
+        documented as single-threaded. Read paths must go through
+        :meth:`_read_cursor` instead so concurrent reads each get an
+        isolated cursor — see ``docs/concurrency.md`` and issue #75.
         """
         if self._cursor is None:
             msg = (
@@ -302,6 +340,49 @@ class Registry:
             raise RuntimeError(msg)
         return self._cursor
 
+    def _require_open(self) -> duckdb.DuckDBPyConnection:
+        """Return the live connection or raise a clear lifecycle error.
+
+        Use when a caller needs the long-lived connection itself (e.g. to
+        hand to a lazy facade) rather than a short-lived cursor.
+        """
+        if self._conn is None:
+            msg = (
+                f"Registry({self._uri!r}) is not open. Use it as a context manager "
+                "(``with Registry(uri) as reg: ...``) or call ``.open()`` first."
+            )
+            raise RuntimeError(msg)
+        return self._conn
+
+    @contextmanager
+    def _read_cursor(self) -> Iterator[duckdb.DuckDBPyConnection]:
+        """Open a fresh DuckDB cursor for the duration of one read call.
+
+        DuckDB serialises ``execute()`` calls on a single connection but
+        each connection has *one* default cursor whose row buffer is
+        overwritten by every ``execute()``. Reads that fan out across
+        threads must therefore each hold their own cursor — otherwise
+        thread A's ``fetchone()`` can race thread B's ``execute()`` and
+        return rows belonging to B's query. Fixed in #75/#78.
+
+        Cursors on a read-only DuckDB connection are cheap (no
+        transaction state); per-call create/close has negligible
+        overhead at typical request rates. Sharing the connection — not
+        the cursor — keeps DuckLake / cataloglib federation working.
+        """
+        if self._conn is None:
+            msg = (
+                f"Registry({self._uri!r}) is not open. Use it as a context manager "
+                "(``with Registry(uri) as reg: ...``) or call ``.open()`` first."
+            )
+            raise RuntimeError(msg)
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SET search_path = 'sdmx'")
+            yield cur
+        finally:
+            cur.close()
+
     # ── Add ───────────────────────────────────────────────────────────────
 
     def add(self, artefact: Any, *, source_registry: str | None = None) -> None:
@@ -313,6 +394,12 @@ class Registry:
         Clears the resolver cache: any cached resolved target may now be
         stale (e.g. a freshly-added Codelist replaces the one a previous
         ``get`` had cached).
+
+        **Single-threaded.** Mutations are not safe under concurrent
+        callers — do not invoke ``add`` / ``drop`` / ``replace`` from
+        multiple threads against the same ``Registry``. Concurrent reads
+        through ``get`` / ``get_all`` / ``code_map`` etc. are safe. See
+        ``docs/concurrency.md``.
         """
         tag = source_registry if source_registry is not None else self._source_registry
         writers.put_artefact(self._c, artefact, source_registry=tag)
@@ -342,7 +429,12 @@ class Registry:
         """
         from sdmxlib.storage.readers import make_lazy_codelist  # noqa: PLC0415
 
-        return make_lazy_codelist(self._c, str(urn))
+        # make_lazy_codelist opens its own internal cursor for spine
+        # reads; the returned LazyCodelist holds the long-lived
+        # connection for later method calls. ``_require_open`` enforces
+        # the lifecycle precondition without creating a cursor we don't
+        # need.
+        return make_lazy_codelist(self._require_open(), str(urn))
 
     def get[T](self, urn: "SdmxUrn[T]", *, eager: bool = False) -> "T | None":
         """Look up an artefact by URN.
@@ -357,14 +449,15 @@ class Registry:
             dsd.dimensions["FREQ"].codelist()  # -> LazyCodelist
             dsd.code_map(lang="en")  # works
         """
-        result = readers.get_artefact(self._c, str(urn), eager=eager)
-        if result is None:
-            return None
-        if not isinstance(result, (LazyCodelist, LazyHierarchy)):
-            memo = _CallScopedMemo(self._resolve_cache)
-            self._resolve_refs(result, memo=memo)
-            memo.promote()
-        return result  # type: ignore[return-value]
+        with self._read_cursor() as cur:
+            result = readers.get_artefact(cur, str(urn), eager=eager, lazy_conn=self._conn)
+            if result is None:
+                return None
+            if not isinstance(result, (LazyCodelist, LazyHierarchy)):
+                memo = _CallScopedMemo(self._resolve_cache)
+                self._resolve_refs(cur, result, memo=memo)
+                memo.promote()
+            return result  # type: ignore[return-value]
 
     def get_all[T](self, artefact_type: "type[T]") -> "list[T]":
         """All artefacts of the given Python type.
@@ -374,18 +467,20 @@ class Registry:
         parent scheme referenced by multiple artefacts is loaded once,
         not once per artefact.
         """
-        results = readers.get_all(self._c, artefact_type)
-        memo = _CallScopedMemo(self._resolve_cache)
-        for r in results:
-            if not isinstance(r, (LazyCodelist, LazyHierarchy)):
-                self._resolve_refs(r, memo=memo)
-        memo.promote()
-        return results  # type: ignore[return-value]
+        with self._read_cursor() as cur:
+            results = readers.get_all(cur, artefact_type, lazy_conn=self._conn)
+            memo = _CallScopedMemo(self._resolve_cache)
+            for r in results:
+                if not isinstance(r, (LazyCodelist, LazyHierarchy)):
+                    self._resolve_refs(cur, r, memo=memo)
+            memo.promote()
+            return results  # type: ignore[return-value]
 
     # ── Ref resolution ─────────────────────────────────────────────────
 
     def _resolve_refs(  # noqa: C901
         self,
+        cur: duckdb.DuckDBPyConnection,
         obj: Any,
         *,
         memo: "dict[str, Any] | None" = None,
@@ -438,7 +533,7 @@ class Registry:
                 needed.append(ref.urn)
 
             if needed:
-                self._resolve_urns(needed, memo)
+                self._resolve_urns(cur, needed, memo)
 
             for owner, name, ref in pending:
                 if ref._resolved is not None:  # noqa: SLF001
@@ -479,6 +574,7 @@ class Registry:
 
     def _resolve_urns(  # noqa: C901
         self,
+        cur: duckdb.DuckDBPyConnection,
         urns: "list[SdmxUrn[Any]]",
         memo: "dict[str, Any]",
     ) -> None:
@@ -507,7 +603,7 @@ class Registry:
             if scheme_info is None:
                 continue
             _scheme_class_name, items_attr = scheme_info
-            parent = self._load_parent_scheme(parent_urn_str, sample, memo)
+            parent = self._load_parent_scheme(cur, parent_urn_str, sample, memo)
             if parent is None:
                 continue
             items = getattr(parent, items_attr, None)
@@ -522,7 +618,7 @@ class Registry:
             urn_str = str(parsed)
             if urn_str in memo:
                 continue
-            target = readers.get_artefact(self._c, urn_str)
+            target = readers.get_artefact(cur, urn_str, lazy_conn=self._conn)
             if target is not None:
                 memo[urn_str] = target
 
@@ -547,6 +643,7 @@ class Registry:
 
     def _load_parent_scheme(
         self,
+        cur: duckdb.DuckDBPyConnection,
         parent_urn_str: str,
         sample: "SdmxUrn[Any]",
         memo: "dict[str, Any]",
@@ -559,12 +656,12 @@ class Registry:
         cached = memo.get(parent_urn_str)
         if cached is not None:
             return cached
-        parent = readers.get_artefact(self._c, parent_urn_str, eager=True)
+        parent = readers.get_artefact(cur, parent_urn_str, eager=True)
         if parent is None and sample.version == "latest":
             scheme_info = _ITEM_TO_SCHEME.get(sample.artefact_class)
             if scheme_info is not None:
                 scheme_class_name, _ = scheme_info
-                row = self._c.execute(
+                row = cur.execute(
                     """
                     SELECT urn FROM artefact
                     WHERE artefact_type = ? AND agency_id = ? AND resource_id = ?
@@ -572,7 +669,7 @@ class Registry:
                     [scheme_class_name, sample.agency, sample.id],
                 ).fetchone()
                 if row:
-                    parent = readers.get_artefact(self._c, row[0], eager=True)
+                    parent = readers.get_artefact(cur, row[0], eager=True)
         if parent is not None:
             memo[parent_urn_str] = parent
         return parent
@@ -587,19 +684,22 @@ class Registry:
 
     def __contains__(self, urn: object) -> bool:
         if isinstance(urn, SdmxUrn):
-            row = self._c.execute(
-                "SELECT 1 FROM artefact WHERE urn = ?",
-                [str(urn)],
-            ).fetchone()
-            return row is not None
+            with self._read_cursor() as cur:
+                row = cur.execute(
+                    "SELECT 1 FROM artefact WHERE urn = ?",
+                    [str(urn)],
+                ).fetchone()
+                return row is not None
         return False
 
     def __len__(self) -> int:
-        row = self._c.execute("SELECT COUNT(*) FROM artefact").fetchone()
-        return row[0]  # type: ignore[index]
+        with self._read_cursor() as cur:
+            row = cur.execute("SELECT COUNT(*) FROM artefact").fetchone()
+            return row[0]  # type: ignore[index]
 
     def __repr__(self) -> str:
-        rows = self._c.execute("SELECT artefact_type, COUNT(*) FROM artefact GROUP BY artefact_type").fetchall()
+        with self._read_cursor() as cur:
+            rows = cur.execute("SELECT artefact_type, COUNT(*) FROM artefact GROUP BY artefact_type").fetchall()
         counts = ", ".join(f"{name}={cnt}" for name, cnt in rows)
         return f"Registry({counts or 'empty'})"
 
@@ -610,6 +710,8 @@ class Registry:
 
         Clears the resolver cache (cached resolved targets may reference
         the dropped artefact).
+
+        **Single-threaded** — see :meth:`add`.
         """
         result = writers.drop_artefact(self._c, str(urn))
         self._resolve_cache.clear()
@@ -620,6 +722,8 @@ class Registry:
 
         Each leg clears the resolver cache via :meth:`add` / :meth:`drop`;
         the net effect is a single fully-cleared cache at the end.
+
+        **Single-threaded** — see :meth:`add`.
         """
         writers.drop_artefact(self._c, str(old_urn))
         self.add(new)
@@ -655,11 +759,13 @@ class Registry:
 
     def code_map(self, codelist_urn: "str | SdmxUrn[Any]", *, lang: str) -> dict[str, str]:
         """Return {code_id: label} for a codelist without creating Code objects."""
-        return readers.code_map(self._c, str(codelist_urn), lang=lang)
+        with self._read_cursor() as cur:
+            return readers.code_map(cur, str(codelist_urn), lang=lang)
 
     def dsd_code_map(self, dsd_urn: "str | SdmxUrn[Any]", *, lang: str) -> dict[str, dict[str, str]]:
         """Return {component_id: {code_id: label}} for all enumerated dimensions."""
-        return readers.code_map_for_dsd(self._c, str(dsd_urn), lang=lang)
+        with self._read_cursor() as cur:
+            return readers.code_map_for_dsd(cur, str(dsd_urn), lang=lang)
 
     # ── Bulk ──────────────────────────────────────────────────────────────
 
@@ -687,12 +793,13 @@ class Registry:
         """
         reg = InMemoryRegistry()
         memo = _CallScopedMemo(self._resolve_cache)
-        rows = self._c.execute("SELECT urn, artefact_type FROM artefact").fetchall()
-        for urn_str, _artefact_type in rows:
-            obj = readers.get_artefact(self._c, urn_str, eager=True)
-            if obj is None:
-                continue
-            self._resolve_refs(obj, memo=memo)
-            reg.add(obj)
+        with self._read_cursor() as cur:
+            rows = cur.execute("SELECT urn, artefact_type FROM artefact").fetchall()
+            for urn_str, _artefact_type in rows:
+                obj = readers.get_artefact(cur, urn_str, eager=True)
+                if obj is None:
+                    continue
+                self._resolve_refs(cur, obj, memo=memo)
+                reg.add(obj)
         memo.promote()
         return reg

{sdmxlib-0.27.2 → sdmxlib-0.28.0}/src/sdmxlib/model/code_query.py

@@ -35,6 +35,11 @@ if TYPE_CHECKING:
     import duckdb
 
 
+def _cur(conn: duckdb.DuckDBPyConnection) -> duckdb.DuckDBPyConnection:
+    """Open a fresh per-call cursor (issue #75). SQL here is sdmx.-qualified."""
+    return conn.cursor()
+
+
 # ── Field expressions (AST nodes) ───────────────────────────────────────
 
 
@@ -445,7 +450,7 @@ class CodeQuery:
         dominates on large codelists.
         """
         sql, params = _compile(self)
-        rows = self._conn.execute(sql, params).fetchall()
+        rows = _cur(self._conn).execute(sql, params).fetchall()
         if not rows:
             return []
         if self.annotation_types:
@@ -458,7 +463,7 @@ class CodeQuery:
     def ids(self) -> list[str]:
         """Compile to SQL, execute, and return just the code ids."""
         sql, params = _compile(self, select_clause="c.code_id")
-        rows = self._conn.execute(sql, params).fetchall()
+        rows = _cur(self._conn).execute(sql, params).fetchall()
         return [r[0] for r in rows]
 
     def to_sql(self) -> tuple[str, list[object]]:
@@ -481,7 +486,7 @@ class CodeQuery:
 
     def __len__(self) -> int:
         sql, params = _compile(self, select_clause="COUNT(*)", omit_order=True)
-        row = self._conn.execute(sql, params).fetchone()
+        row = _cur(self._conn).execute(sql, params).fetchone()
         return row[0] if row else 0  # type: ignore[index]
 
     @overload
@@ -492,29 +497,37 @@ class CodeQuery:
 
     def __getitem__(self, key: int | str) -> Code:
         if isinstance(key, str):
-            row = self._conn.execute(
-                """
+            row = (
+                _cur(self._conn)
+                .execute(
+                    """
                 SELECT c.code_id, c.parent_id, c.depth, c.name, c.code_urn, c.description
                 FROM sdmx.code c
                 WHERE c.codelist_urn = ? AND c.code_id = ?
                 """,
-                [self.codelist_urn, key],
-            ).fetchone()
+                    [self.codelist_urn, key],
+                )
+                .fetchone()
+            )
             if row is None:
                 raise KeyError(key)
             return _row_to_code(row, self._anns_for_one(row[4]))
 
         offset = key if key >= 0 else len(self) + key
-        row = self._conn.execute(
-            """
+        row = (
+            _cur(self._conn)
+            .execute(
+                """
             SELECT c.code_id, c.parent_id, c.depth, c.name, c.code_urn, c.description
             FROM sdmx.code c
             WHERE c.codelist_urn = ?
             ORDER BY c.position NULLS LAST, c.code_id
             LIMIT 1 OFFSET ?
             """,
-            [self.codelist_urn, offset],
-        ).fetchone()
+                [self.codelist_urn, offset],
+            )
+            .fetchone()
+        )
         if row is None:
             raise IndexError(key)
         return _row_to_code(row, self._anns_for_one(row[4]))
@@ -535,10 +548,14 @@ class CodeQuery:
 
     def __contains__(self, key: object) -> bool:
         if isinstance(key, str):
-            row = self._conn.execute(
-                "SELECT 1 FROM sdmx.code WHERE codelist_urn = ? AND code_id = ?",
-                [self.codelist_urn, key],
-            ).fetchone()
+            row = (
+                _cur(self._conn)
+                .execute(
+                    "SELECT 1 FROM sdmx.code WHERE codelist_urn = ? AND code_id = ?",
+                    [self.codelist_urn, key],
+                )
+                .fetchone()
+            )
             return row is not None
         if isinstance(key, Code):
             return key.id in self
@@ -947,13 +964,16 @@ def _fetch_annotations_for(
         sql_parts.append(f"AND annotation_type IN ({type_placeholders})")
         sql_params.extend(types)
     sql_parts.append("ORDER BY owner_urn, ordinal")
-    ann_rows = conn.execute(" ".join(sql_parts), sql_params).fetchall()
+    # Use a single per-call cursor across both queries to keep concurrent
+    # callers isolated from each other's row buffers (issue #75).
+    cur = _cur(conn)
+    ann_rows = cur.execute(" ".join(sql_parts), sql_params).fetchall()
     if not ann_rows:
         return {}
 
     ann_ids = [r[0] for r in ann_rows]
     text_placeholders = ", ".join("?" for _ in ann_ids)
-    text_rows = conn.execute(
+    text_rows = cur.execute(
         f"""
         SELECT annotation_id, lang, text
         FROM sdmx.annotation_text