sciduckdb 0.1.0__tar.gz → 0.1.9.dev0__tar.gz

{sciduckdb-0.1.0 → sciduckdb-0.1.9.dev0}/.gitignore

@@ -13,3 +13,4 @@ __pycache__/
 *.duckdb
 *.duckdb.wal
 *.wal
+scistack-gui/frontend/node_modules/

{sciduckdb-0.1.0 → sciduckdb-0.1.9.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sciduckdb
-Version: 0.1.0
+Version: 0.1.9.dev0
 Summary: A thin DuckDB layer for managing versioned scientific data
 Author: SciStack Contributors
 License-Expression: MIT

{sciduckdb-0.1.0 → sciduckdb-0.1.9.dev0}/pyproject.toml

@@ -1,10 +1,14 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+source = "vcs"
+raw-options = { search_parent_directories = true, local_scheme = "no-local-version" }
+
 [project]
 name = "sciduckdb"
-version = "0.1.0"
+dynamic = ["version"]
 description = "A thin DuckDB layer for managing versioned scientific data"
 readme = "README.md"
 license = "MIT"

{sciduckdb-0.1.0 → sciduckdb-0.1.9.dev0}/src/sciduckdb/__init__.py

@@ -2,27 +2,33 @@
 
 from .sciduckdb import (
     SciDuck,
+    _bulk_df_to_storage_rows,
+    _dataframe_to_storage_rows,
+    _flatten_dict,
+    _infer_data_columns,
     _infer_duckdb_type,
     _numpy_dtype_to_duckdb,
     _python_to_storage,
+    _record_schema_mismatch,
+    _storage_signature,
     _storage_to_python,
     _storage_to_python_column,
-    _infer_data_columns,
-    _value_to_storage_row,
-    _dataframe_to_storage_rows,
-    _bulk_df_to_storage_rows,
-    _flatten_dict,
     _unflatten_dict,
+    _value_to_storage_row,
+    schema_keys_from_db,
 )
 
 __all__ = [
     "SciDuck",
+    "schema_keys_from_db",
     "_infer_duckdb_type",
     "_numpy_dtype_to_duckdb",
     "_python_to_storage",
     "_storage_to_python",
     "_storage_to_python_column",
     "_infer_data_columns",
+    "_record_schema_mismatch",
+    "_storage_signature",
     "_value_to_storage_row",
     "_dataframe_to_storage_rows",
     "_bulk_df_to_storage_rows",

{sciduckdb-0.1.0 → sciduckdb-0.1.9.dev0}/src/sciduckdb/sciduckdb.py

@@ -11,15 +11,16 @@ nested LIST, JSON) so the database can be inspected with DBeaver or any
 DuckDB-compatible viewer.
 """
 
-import duckdb
-import logging
-import pandas as pd
-import numpy as np
-import json
 import datetime
+import json
+import logging
 import threading
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any
+
+import duckdb
+import numpy as np
+import pandas as pd
 
 logger = logging.getLogger("sciduck")
 
@@ -40,6 +41,7 @@ def _schema_str(value):
 # Type mapping helpers
 # ---------------------------------------------------------------------------
 
+
 def _numpy_dtype_to_duckdb(dtype: np.dtype) -> str:
     """Map a numpy scalar dtype to a DuckDB type string."""
     kind = dtype.kind
@@ -63,7 +65,7 @@ def _numpy_dtype_to_duckdb(dtype: np.dtype) -> str:
     return "VARCHAR"
 
 
-def _infer_duckdb_type(value: Any) -> Tuple[str, dict]:
+def _infer_duckdb_type(value: Any) -> tuple[str, dict]:
     """
     Infer the DuckDB column type and a metadata dict for round-trip
     restoration from a single Python/numpy value.
@@ -197,6 +199,17 @@ def _python_to_storage(value: Any, meta: dict) -> Any:
     """Convert a Python value to its DuckDB-storable form."""
     ptype = meta.get("python_type", "")
 
+    # _infer_data_columns unwraps length-1 arrays to scalars when it picks the
+    # column type, e.g. {"x": np.array([1.0])} -> DOUBLE column with
+    # python_type="float". Mirror that unwrap here so the stored value is a
+    # scalar matching the column; otherwise the row carries a DOUBLE[] into a
+    # DOUBLE column and DuckDB rejects the cast (DOUBLE[] -> DOUBLE).
+    if ptype in ("float", "int", "bool", "str"):
+        if isinstance(value, np.ndarray) and value.size == 1:
+            value = value.item()
+        elif isinstance(value, np.generic):
+            value = value.item()
+
     if ptype == "ndarray":
         arr = value
         # Scalar in a column typed as ndarray (e.g. ragged vectors): wrap as 1-element list
@@ -345,9 +358,10 @@ def _unflatten_dict(flat, path_map):
 # DatabaseManager)
 # ---------------------------------------------------------------------------
 
+
 def _infer_data_columns(
-    sample_value: Any, data_col_name: Optional[str] = None
-) -> Tuple[dict, dict]:
+    sample_value: Any, data_col_name: str | None = None
+) -> tuple[dict, dict]:
     """
     From a sample data value, return:
       - data_col_types: dict of {col_name: duckdb_type_str}
@@ -410,6 +424,93 @@ def _infer_data_columns(
     return {col_name: ddb_type}, meta
 
 
+# DuckDB type categories used by _storage_signature.  Records can only share a
+# column if their values reduce to the same (category, array-depth) signature;
+# this is intentionally coarse so benign coercions (BIGINT -> DOUBLE) are
+# allowed while shape changes (scalar vs vector) and category changes
+# (DOUBLE vs VARCHAR) are rejected.
+_NUMERIC_DDB_TYPES = {
+    "BOOLEAN",
+    "TINYINT",
+    "SMALLINT",
+    "INTEGER",
+    "BIGINT",
+    "HUGEINT",
+    "UTINYINT",
+    "USMALLINT",
+    "UINTEGER",
+    "UBIGINT",
+    "FLOAT",
+    "REAL",
+    "DOUBLE",
+}
+_TEMPORAL_DDB_TYPES = {"DATE", "TIME", "TIMESTAMP", "INTERVAL"}
+
+
+def _storage_signature(ddb_type: str) -> tuple[str, int]:
+    """Reduce a DuckDB column type string to (base_category, array_depth).
+
+    array_depth counts trailing ``[]`` (0 = scalar, 1 = vector, 2 = matrix).
+    base_category is a coarse bucket so that, e.g., ``BIGINT`` and ``DOUBLE``
+    are both ``numeric`` (DuckDB coerces them into one column) but ``DOUBLE``
+    and ``VARCHAR`` differ.  This is the unit of comparison for deciding
+    whether two records can be stored in the same batch column.
+    """
+    t = ddb_type.strip().upper()
+    depth = 0
+    while t.endswith("[]"):
+        depth += 1
+        t = t[:-2].strip()
+    if t in _NUMERIC_DDB_TYPES or t.startswith("DECIMAL"):
+        category = "numeric"
+    elif t == "VARCHAR":
+        category = "string"
+    elif t == "JSON":
+        category = "json"
+    elif t in _TEMPORAL_DDB_TYPES:
+        category = "temporal"
+    else:
+        category = t
+    return (category, depth)
+
+
+def _record_schema_mismatch(ref_col_types: dict, rec_col_types: dict) -> str | None:
+    """Return a human-readable reason a record can't join the batch, or None.
+
+    A record "fits" the batch schema when it has exactly the reference column
+    set and every column's storage signature matches.  This is the predicate
+    used by save_batch to skip (with a warning) records that would otherwise
+    abort the atomic batch insert:
+
+      * empty/partial dicts  -> missing keys
+      * unexpected dict keys -> extra keys
+      * a scalar where the column stores a vector (or vice versa),
+        or a string where the column is numeric -> signature mismatch
+    """
+    ref_keys = set(ref_col_types)
+    rec_keys = set(rec_col_types)
+    if ref_keys != rec_keys:
+        missing = sorted(ref_keys - rec_keys)
+        extra = sorted(rec_keys - ref_keys)
+        parts = []
+        if missing:
+            parts.append(f"missing keys {missing}")
+        if extra:
+            parts.append(f"unexpected keys {extra}")
+        if not parts:
+            parts.append("key set differs from batch schema")
+        return "; ".join(parts)
+    for col in ref_col_types:
+        ref_sig = _storage_signature(ref_col_types[col])
+        rec_sig = _storage_signature(rec_col_types[col])
+        if ref_sig != rec_sig:
+            return (
+                f"column '{col}' shape/type mismatch: batch column is "
+                f"{ref_col_types[col]} but record value is {rec_col_types[col]}"
+            )
+    return None
+
+
 def _dataframe_to_storage_rows(df: pd.DataFrame, dtype_meta: dict) -> list:
     """Convert a DataFrame to a list of per-row storage values.
 
@@ -433,9 +534,7 @@ def _dataframe_to_storage_rows(df: pd.DataFrame, dtype_meta: dict) -> list:
     return rows
 
 
-def _bulk_df_to_storage_rows(
-    df_list: list, record_ids: list, dtype_meta: dict
-) -> list:
+def _bulk_df_to_storage_rows(df_list: list, record_ids: list, dtype_meta: dict) -> list:
     """Bulk convert N DataFrames to (record_id, ...storage_values) rows.
 
     Equivalent to calling _dataframe_to_storage_rows N times and assembling
@@ -453,7 +552,7 @@ def _bulk_df_to_storage_rows(
     # Fall back to per-row path if schemas differ (shouldn't happen in normal use).
     if not all(list(df.columns) == first_cols for df in df_list):
         rows: list = []
-        for rid, df in zip(record_ids, df_list):
+        for rid, df in zip(record_ids, df_list, strict=False):
             for storage_row in _dataframe_to_storage_rows(df, dtype_meta):
                 rows.append((rid,) + tuple(storage_row))
         return rows
@@ -461,7 +560,7 @@ def _bulk_df_to_storage_rows(
     # Build flat record_id list: one entry per storage row (multi-row records
     # contribute len(df) entries, typical 1-row records contribute 1).
     expanded_rids = []
-    for rid, df in zip(record_ids, df_list):
+    for rid, df in zip(record_ids, df_list, strict=False):
         expanded_rids.extend([rid] * len(df))
 
     # Concat once so column operations don't cross DataFrame boundaries.
@@ -476,7 +575,8 @@ def _bulk_df_to_storage_rows(
         if ptype == "ndarray":
             vals = raw.to_numpy()
             col_arrays[col] = [
-                v.tolist() if isinstance(v, np.ndarray)
+                v.tolist()
+                if isinstance(v, np.ndarray)
                 else (v if isinstance(v, list) else [v])
                 for v in vals
             ]
@@ -516,10 +616,7 @@ def _value_to_storage_row(value: Any, dtype_meta: dict) -> list:
             flat, _ = _flatten_dict(value)
         else:
             flat = value
-        return [
-            _python_to_storage(flat[col], col_metas[col])
-            for col in col_metas
-        ]
+        return [_python_to_storage(flat[col], col_metas[col]) for col in col_metas]
     else:
         # Single column — get the one key (could be "value" or a named column)
         col_name = next(iter(col_metas))
@@ -531,6 +628,43 @@ def _value_to_storage_row(value: Any, dtype_meta: dict) -> list:
 # Main class
 # ---------------------------------------------------------------------------
 
+
+def schema_keys_from_db(db_path: str | Path) -> list[str]:
+    """Read the dataset schema keys stored in an existing database.
+
+    Opens ``db_path`` read-only, reads the ``_schema`` table's key columns
+    (everything except ``schema_id``/``schema_level``, in ordinal order), and
+    closes the connection. This lets tools open a database without knowing
+    its schema keys in advance (e.g. the ``scidb`` CLI).
+
+    Raises ValueError if the file has no ``_schema`` table (not a
+    scidb/sciduckdb database) and whatever duckdb raises if the file does not
+    exist or is locked.
+    """
+    con = duckdb.connect(str(db_path), read_only=True)
+    try:
+        rows = con.execute(
+            "SELECT column_name FROM information_schema.columns "
+            "WHERE table_name = '_schema' "
+            "AND column_name NOT IN ('schema_id', 'schema_level') "
+            "ORDER BY ordinal_position"
+        ).fetchall()
+        has_table = (
+            con.execute(
+                "SELECT COUNT(*) FROM information_schema.tables "
+                "WHERE table_name = '_schema'"
+            ).fetchall()[0][0]
+            > 0
+        )
+    finally:
+        con.close()
+    if not has_table:
+        raise ValueError(
+            f"{db_path} has no _schema table — not a scidb/sciduckdb database"
+        )
+    return [r[0] for r in rows]
+
+
 class SciDuck:
     """
     A thin DuckDB layer for managing versioned, schema-aware scientific data.
@@ -541,15 +675,28 @@ class SciDuck:
         Path to the DuckDB database file.  Use ":memory:" for in-memory.
     dataset_schema : list of str
         Ordered hierarchy, e.g. ["subject", "session", "trial"].
+    read_only : bool
+        Open the underlying DuckDB connection read-only. No DDL is executed
+        (the database must already exist); DuckDB rejects every write on the
+        connection, so a read-only SciDuck can never contend for the write
+        lock beyond DuckDB's shared read lock.
     """
 
-    def __init__(self, db_path: Union[str, Path], dataset_schema: List[str]):
+    def __init__(
+        self, db_path: str | Path, dataset_schema: list[str], read_only: bool = False
+    ):
         self.db_path = str(db_path)
         self.dataset_schema = list(dataset_schema)
+        self.read_only = bool(read_only)
         self._lock = threading.Lock()
-        logger.info("DuckDB lock ACQUIRED: %s", self.db_path)
-        self.con = duckdb.connect(self.db_path)
-        self._init_metadata_tables()
+        logger.debug(
+            "DuckDB lock ACQUIRED (read_only=%s): %s", self.read_only, self.db_path
+        )
+        self.con = duckdb.connect(self.db_path, read_only=self.read_only)
+        if self.read_only:
+            self._validate_schema_columns()
+        else:
+            self._init_metadata_tables()
 
     # ------------------------------------------------------------------
     # Thin internal interface (future backend swap point)
@@ -570,6 +717,37 @@ class SciDuck:
         with self._lock:
             return self.con.executemany(sql, params_list)
 
+    def _bulk_insert(self, table: str, columns, rows, conflict_cols=None) -> None:
+        """Insert many rows with a single vectorized ``INSERT ... SELECT``.
+
+        DuckDB's ``executemany`` re-runs the prepared single-row statement once
+        per row; against a PRIMARY-KEY / indexed table that is pathologically
+        slow (per-row index probe + maintenance), e.g. ~497s for 8k rows into
+        ``_record``. This registers the rows as one DataFrame and issues a single
+        bulk insert instead (sub-second for the same data).
+
+        ``rows`` is an iterable of value tuples in ``columns`` order. When
+        ``conflict_cols`` is given, appends ``ON CONFLICT (...) DO NOTHING`` so
+        the insert stays idempotent. Safe to call inside an open transaction
+        (the register/insert/unregister run on the same connection).
+        """
+        rows = list(rows)
+        if not rows:
+            return
+        columns = list(columns)
+        df = pd.DataFrame(rows, columns=columns)
+        col_str = ", ".join(f'"{c}"' for c in columns)
+        sql = f'INSERT INTO "{table}" ({col_str}) SELECT * FROM _bulk_insert_df'
+        if conflict_cols:
+            conflict_str = ", ".join(f'"{c}"' for c in conflict_cols)
+            sql += f" ON CONFLICT ({conflict_str}) DO NOTHING"
+        with self._lock:
+            self.con.register("_bulk_insert_df", df)
+            try:
+                self.con.execute(sql)
+            finally:
+                self.con.unregister("_bulk_insert_df")
+
     def _begin(self):
         with self._lock:
             self.con.execute("BEGIN TRANSACTION")
@@ -600,8 +778,8 @@ class SciDuck:
 
     def _table_exists(self, name: str) -> bool:
         rows = self._fetchall(
-            "SELECT COUNT(*) FROM information_schema.tables "
-            "WHERE table_name = ?", [name]
+            "SELECT COUNT(*) FROM information_schema.tables WHERE table_name = ?",
+            [name],
         )
         return rows[0][0] > 0
 
@@ -647,25 +825,42 @@ class SciDuck:
 
         # Validate schema consistency if _schema already has data
         if self._fetchall("SELECT COUNT(*) FROM _schema")[0][0] > 0:
-            existing_cols = [
-                row[0] for row in self._fetchall(
-                    "SELECT column_name FROM information_schema.columns "
-                    "WHERE table_name = '_schema' "
-                    "AND column_name NOT IN ('schema_id', 'schema_level') "
-                    "ORDER BY ordinal_position"
-                )
-            ]
-            if existing_cols != self.dataset_schema:
+            self._validate_schema_columns()
+
+    def _validate_schema_columns(self):
+        """Check that the existing _schema columns match dataset_schema.
+
+        Read-only companion to _init_metadata_tables: runs the same
+        consistency check without any DDL, so it is safe on a read-only
+        connection (where the tables must already exist).
+        """
+        if not self._table_exists("_schema"):
+            if self.read_only:
                 raise ValueError(
-                    f"Database schema mismatch. "
-                    f"Existing: {existing_cols}, Provided: {self.dataset_schema}"
+                    f"{self.db_path} has no _schema table — not a scidb/sciduckdb "
+                    f"database (read-only open cannot create it)"
                 )
+            return
+        existing_cols = [
+            row[0]
+            for row in self._fetchall(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_name = '_schema' "
+                "AND column_name NOT IN ('schema_id', 'schema_level') "
+                "ORDER BY ordinal_position"
+            )
+        ]
+        if existing_cols != self.dataset_schema:
+            raise ValueError(
+                f"Database schema mismatch. "
+                f"Existing: {existing_cols}, Provided: {self.dataset_schema}"
+            )
 
     # ------------------------------------------------------------------
     # Schema entry management
     # ------------------------------------------------------------------
 
-    def _schema_key_columns(self, schema_level: str) -> List[str]:
+    def _schema_key_columns(self, schema_level: str) -> list[str]:
         """Return schema columns from the top down to (and including) schema_level."""
         idx = self.dataset_schema.index(schema_level)
         return self.dataset_schema[: idx + 1]
@@ -688,16 +883,16 @@ class SciDuck:
 
         where = " AND ".join(conditions)
         rows = self._fetchall(
-            f'SELECT schema_id FROM _schema WHERE schema_level = ? AND {where}',
+            f"SELECT schema_id FROM _schema WHERE schema_level = ? AND {where}",
             params,
         )
         if rows:
             return rows[0][0]
 
         # Insert new entry — use MAX+1 for consistency with batch path
-        new_id = self._fetchall(
-            "SELECT COALESCE(MAX(schema_id), 0) + 1 FROM _schema"
-        )[0][0]
+        new_id = self._fetchall("SELECT COALESCE(MAX(schema_id), 0) + 1 FROM _schema")[
+            0
+        ][0]
         col_names = ["schema_id", "schema_level"] + key_cols
         placeholders = ", ".join(["?"] * len(col_names))
         col_str = ", ".join(f'"{c}"' for c in col_names)
@@ -744,16 +939,14 @@ class SciDuck:
 
             # Build a single query to find all existing matches at this level
             # We fetch all rows for this schema_level and match in Python
-            null_conditions = " AND ".join(
-                f'"{col}" IS NULL' for col in null_cols
-            )
-            where_clause = f'schema_level = ?'
+            null_conditions = " AND ".join(f'"{col}" IS NULL' for col in null_cols)
+            where_clause = "schema_level = ?"
             if null_conditions:
-                where_clause += f' AND {null_conditions}'
+                where_clause += f" AND {null_conditions}"
 
             col_select = ", ".join(f'"{c}"' for c in key_cols)
             rows = self._fetchall(
-                f'SELECT schema_id, {col_select} FROM _schema WHERE {where_clause}',
+                f"SELECT schema_id, {col_select} FROM _schema WHERE {where_clause}",
                 [schema_level],
             )
 
@@ -761,7 +954,9 @@ class SciDuck:
             existing_lookup = {}
             for row in rows:
                 sid = row[0]
-                row_key = tuple(_schema_str(v) if v is not None else "" for v in row[1:])
+                row_key = tuple(
+                    _schema_str(v) if v is not None else "" for v in row[1:]
+                )
                 existing_lookup[row_key] = sid
 
             # Match entries against existing rows
@@ -782,7 +977,6 @@ class SciDuck:
                 first_id = max_row[0][0] + 1
 
                 col_names = ["schema_id", "schema_level"] + key_cols
-                col_str = ", ".join(f'"{c}"' for c in col_names)
 
                 insert_rows = []
                 for idx, (combo_key, key_values, _) in enumerate(missing):
@@ -793,11 +987,7 @@ class SciDuck:
                     insert_rows.append(row)
                     result[combo_key] = new_id
 
-                # Use DataFrame-based insert for speed
-                insert_df = pd.DataFrame(insert_rows, columns=col_names)
-                self.con.execute(
-                    f"INSERT INTO _schema ({col_str}) SELECT * FROM insert_df"
-                )
+                self._bulk_insert("_schema", col_names, insert_rows)
 
         return result
 
@@ -809,7 +999,7 @@ class SciDuck:
         self,
         name: str,
         data: Any,
-        schema_level: Optional[str] = None,
+        schema_level: str | None = None,
         description: str = "",
         force: bool = False,
         **schema_keys,
@@ -844,16 +1034,22 @@ class SciDuck:
         if schema_keys:
             provided_schema_cols = [k for k in self.dataset_schema if k in schema_keys]
             if schema_level is None:
-                schema_level = provided_schema_cols[-1] if provided_schema_cols else self.dataset_schema[-1]
+                schema_level = (
+                    provided_schema_cols[-1]
+                    if provided_schema_cols
+                    else self.dataset_schema[-1]
+                )
             if schema_level not in self.dataset_schema:
                 raise ValueError(
                     f"schema_level '{schema_level}' not in {self.dataset_schema}"
                 )
             key_cols = provided_schema_cols
-            entries = [(
-                {k: schema_keys[k] for k in key_cols},
-                data,
-            )]
+            entries = [
+                (
+                    {k: schema_keys[k] for k in key_cols},
+                    data,
+                )
+            ]
 
         else:
             if schema_level is None:
@@ -865,11 +1061,19 @@ class SciDuck:
             key_cols = self._schema_key_columns(schema_level)
 
             # Mode A: DataFrame with schema columns
-            if isinstance(data, pd.DataFrame) and all(c in data.columns for c in key_cols):
-                entries, data_col_name = self._entries_from_dataframe(data, key_cols, schema_level)
+            if isinstance(data, pd.DataFrame) and all(
+                c in data.columns for c in key_cols
+            ):
+                entries, data_col_name = self._entries_from_dataframe(
+                    data, key_cols, schema_level
+                )
 
             # Mode C: dict with tuple keys
-            elif isinstance(data, dict) and data and isinstance(next(iter(data.keys())), tuple):
+            elif (
+                isinstance(data, dict)
+                and data
+                and isinstance(next(iter(data.keys())), tuple)
+            ):
                 entries = []
                 for key_tuple, value in data.items():
                     if len(key_tuple) != len(key_cols):
@@ -877,7 +1081,7 @@ class SciDuck:
                             f"Key tuple length {len(key_tuple)} != "
                             f"expected {len(key_cols)} for level '{schema_level}'"
                         )
-                    key_dict = dict(zip(key_cols, key_tuple))
+                    key_dict = dict(zip(key_cols, key_tuple, strict=False))
                     entries.append((key_dict, value))
 
             else:
@@ -890,12 +1094,15 @@ class SciDuck:
 
         # --- Determine column types from the first entry's data ---
         sample_value = entries[0][1]
-        data_col_types, dtype_meta = self._infer_data_columns(sample_value, data_col_name)
+        data_col_types, dtype_meta = self._infer_data_columns(
+            sample_value, data_col_name
+        )
 
         # --- Ensure the variable table exists ---
         is_dataframe = dtype_meta.get("mode") == "dataframe"
-        self._ensure_variable_table(name, data_col_types, schema_level,
-                                    is_dataframe=is_dataframe)
+        self._ensure_variable_table(
+            name, data_col_types, schema_level, is_dataframe=is_dataframe
+        )
 
         # --- Insert rows (INSERT OR REPLACE for "latest wins" semantics) ---
         col_names = ["schema_id"] + list(data_col_types.keys())
@@ -916,7 +1123,8 @@ class SciDuck:
                 storage_values = self._value_to_storage_row(value, dtype_meta)
                 row = [schema_id] + storage_values
                 self._execute(
-                    f'INSERT OR REPLACE INTO "{name}" ({col_str}) VALUES ({placeholders})', row
+                    f'INSERT OR REPLACE INTO "{name}" ({col_str}) VALUES ({placeholders})',
+                    row,
                 )
 
         # --- Register in _variables (one row per variable) ---
@@ -928,8 +1136,8 @@ class SciDuck:
         )
 
     def _entries_from_dataframe(
-        self, df: pd.DataFrame, key_cols: List[str], schema_level: str
-    ) -> Tuple[List[Tuple[dict, Any]], Optional[str]]:
+        self, df: pd.DataFrame, key_cols: list[str], schema_level: str
+    ) -> tuple[list[tuple[dict, Any]], str | None]:
         """
         Convert a DataFrame (Mode A) into a list of (key_dict, row_data) entries.
 
@@ -959,8 +1167,8 @@ class SciDuck:
         return entries, single_col_name
 
     def _infer_data_columns(
-        self, sample_value: Any, data_col_name: Optional[str] = None
-    ) -> Tuple[dict, dict]:
+        self, sample_value: Any, data_col_name: str | None = None
+    ) -> tuple[dict, dict]:
         """Delegate to module-level _infer_data_columns."""
         return _infer_data_columns(sample_value, data_col_name)
 
@@ -968,8 +1176,13 @@ class SciDuck:
         """Delegate to module-level _value_to_storage_row."""
         return _value_to_storage_row(value, dtype_meta)
 
-    def _ensure_variable_table(self, name: str, data_col_types: dict, schema_level: str,
-                               is_dataframe: bool = False):
+    def _ensure_variable_table(
+        self,
+        name: str,
+        data_col_types: dict,
+        schema_level: str,
+        is_dataframe: bool = False,
+    ):
         """Create the variable table if it doesn't exist."""
         if self._table_exists(name):
             return
@@ -999,7 +1212,7 @@ class SciDuck:
         name: str,
         raw: bool = True,
         **schema_keys,
-    ) -> Union[pd.DataFrame, Any]:
+    ) -> pd.DataFrame | Any:
         """
         Load a variable from the database.
 
@@ -1037,9 +1250,9 @@ class SciDuck:
         data_select = ", ".join(f'v."{c}"' for c in data_cols)
 
         sql = (
-            f'SELECT {schema_select}, {data_select} '
+            f"SELECT {schema_select}, {data_select} "
             f'FROM "{name}" v '
-            f'JOIN _schema s ON v.schema_id = s.schema_id'
+            f"JOIN _schema s ON v.schema_id = s.schema_id"
         )
         params: list = []
 
@@ -1050,7 +1263,7 @@ class SciDuck:
                 conditions.append(f's."{col}" = ?')
                 params.append(_schema_str(val))
         if conditions:
-            sql += ' WHERE ' + ' AND '.join(conditions)
+            sql += " WHERE " + " AND ".join(conditions)
 
         df = self._fetchdf(sql, params or None)
 
@@ -1064,8 +1277,9 @@ class SciDuck:
             result = {}
             for c, meta in columns_meta.items():
                 if c in df.columns:
-                    result[c] = [_storage_to_python(df[c].iloc[i], meta)
-                                 for i in range(len(df))]
+                    result[c] = [
+                        _storage_to_python(df[c].iloc[i], meta) for i in range(len(df))
+                    ]
             df_columns = dtype_meta.get("df_columns", data_cols)
             return pd.DataFrame(result, columns=df_columns)
 
@@ -1139,18 +1353,14 @@ class SciDuck:
         """
         if self._table_exists(name):
             self._execute(f'DROP TABLE "{name}"')
-        self._execute(
-            "DELETE FROM _variables WHERE variable_name = ?", [name]
-        )
-        self._execute(
-            "DELETE FROM _variable_groups WHERE variable_name = ?", [name]
-        )
+        self._execute("DELETE FROM _variables WHERE variable_name = ?", [name])
+        self._execute("DELETE FROM _variable_groups WHERE variable_name = ?", [name])
 
     # ------------------------------------------------------------------
     # Groups
     # ------------------------------------------------------------------
 
-    def add_to_group(self, group_name: str, variable_names: Union[str, List[str]]):
+    def add_to_group(self, group_name: str, variable_names: str | list[str]):
         """Add one or more variables to a group."""
         if isinstance(variable_names, str):
             variable_names = [variable_names]
@@ -1161,7 +1371,7 @@ class SciDuck:
                 [group_name, vn],
             )
 
-    def remove_from_group(self, group_name: str, variable_names: Union[str, List[str]]):
+    def remove_from_group(self, group_name: str, variable_names: str | list[str]):
         """Remove one or more variables from a group."""
         if isinstance(variable_names, str):
             variable_names = [variable_names]
@@ -1172,14 +1382,14 @@ class SciDuck:
                 [group_name, vn],
             )
 
-    def list_groups(self) -> List[str]:
+    def list_groups(self) -> list[str]:
         """List all group names."""
         rows = self._fetchall(
             "SELECT DISTINCT group_name FROM _variable_groups ORDER BY group_name"
         )
         return [r[0] for r in rows]
 
-    def get_group(self, group_name: str) -> List[str]:
+    def get_group(self, group_name: str) -> list[str]:
         """Get all variable names in a group."""
         rows = self._fetchall(
             "SELECT variable_name FROM _variable_groups "
@@ -1192,12 +1402,11 @@ class SciDuck:
     # Schema introspection
     # ------------------------------------------------------------------
 
-    def distinct_schema_values(self, key: str) -> List:
+    def distinct_schema_values(self, key: str) -> list:
         """Return all distinct non-null values for a schema column, sorted."""
         if key not in self.dataset_schema:
             raise ValueError(
-                f"'{key}' is not a schema column. "
-                f"Available: {self.dataset_schema}"
+                f"'{key}' is not a schema column. Available: {self.dataset_schema}"
             )
         rows = self._fetchall(
             f'SELECT DISTINCT "{key}" FROM _schema '
@@ -1220,8 +1429,7 @@ class SciDuck:
         for k in keys:
             if k not in self.dataset_schema:
                 raise ValueError(
-                    f"'{k}' is not a schema column. "
-                    f"Available: {self.dataset_schema}"
+                    f"'{k}' is not a schema column. Available: {self.dataset_schema}"
                 )
         col_list = ", ".join(f'"{k}"' for k in keys)
         where_clause = " AND ".join(f'"{k}" IS NOT NULL' for k in keys)
@@ -1248,12 +1456,18 @@ class SciDuck:
     def close(self):
         """Close the DuckDB connection."""
         self.con.close()
-        logger.info("DuckDB lock RELEASED: %s", self.db_path)
+        logger.debug("DuckDB lock RELEASED: %s", self.db_path)
 
     def reopen(self):
-        """Reopen the DuckDB connection after close()."""
-        logger.info("DuckDB lock ACQUIRED (reopen): %s", self.db_path)
-        self.con = duckdb.connect(str(self.db_path))
+        """Reopen the DuckDB connection after close(), preserving read_only mode."""
+        logger.debug(
+            "DuckDB lock ACQUIRED (reopen, read_only=%s): %s",
+            getattr(self, "read_only", False),
+            self.db_path,
+        )
+        self.con = duckdb.connect(
+            str(self.db_path), read_only=getattr(self, "read_only", False)
+        )
 
     def __enter__(self):
         """Enter context manager."""
@@ -1273,4 +1487,4 @@ class SciDuck:
         return (
             f"SciDuck(path='{self.db_path}', "
             f"schema={self.dataset_schema}, variables={n_vars})"
-        )
+        )