Keep read checks independent of write limits and database creation

Author: TonisOrmisson

src/openstatspec/api.py

@@ -33,6 +33,7 @@
     install_in_place_transformation_schema as _install_in_place_schema,
 )
 from .transform import TransformationPlan
+from .sql.database_urls import require_existing_database_url
 from .sql.capabilities import (
     SPECIFICATION_COMMIT, SPECIFICATION_RELEASE, SPECIFICATION_STATUS,
     active_connection, catalog_binding,
@@ -53,8 +54,11 @@ def capability_matrix(
     blocks export unless the documented explicit loss opt-in exists; a plain
     fail-closed feature has no faithful writer route at all.
     """
+    if database_url:
+        require_existing_database_url(database_url)
     declaration = {
         "specification": "OpenStatSpec",
+        "database_io_policy": "openstatspec-database-io-v1",
         "specification_status": SPECIFICATION_STATUS,
         "specification_release": SPECIFICATION_RELEASE,
         "specification_commit": SPECIFICATION_COMMIT,

src/openstatspec/sql/capabilities.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import re
+import sys
 from dataclasses import replace
 from pathlib import Path
 from typing import Any, Mapping
@@ -12,6 +13,7 @@
 
 from .dolt_conformance import DoltConformanceSource, effective_limits as dolt_effective_limits
 from .normative import catalog
+from .database_urls import require_existing_database_url
 from .profiles import DOLT, MYSQL, POSTGRESQL, SQLITE, MYSQL_WIRE_PROFILES, SqlProfile
 from .profiles import validate_connection_url
 from ..core import UnsupportedOperationError
@@ -138,6 +140,8 @@ def profile_declarations(
     dolt_conformance_source: DoltConformanceSource | None = None,
 ) -> dict[str, dict[str, Any]]:
     """Declare every profile and, optionally, one active connection."""
+    if database_url:
+        require_existing_database_url(database_url)
     source = dolt_conformance_source
     active = (
         active_connection(database_url, dolt_conformance_source=source)
@@ -307,6 +311,7 @@ def read_profile(
     dolt_conformance_source: DoltConformanceSource | None = None,
 ) -> tuple[SqlProfile, dict[str, Any]]:
     """Identify a read connection without requiring evidence for Dolt writes."""
+    require_existing_database_url(database_url)
     return _effective_profile(database_url, dolt_conformance_source, for_write=False)
 
 
@@ -331,7 +336,7 @@ def _effective_profile(
     if active["profile"] == "dolt" and not for_write:
         # Existing data is validated against the adapter's data model, not a
         # write-conformance envelope or INSERT statement/packet limits.
-        return DOLT, active
+        return replace(DOLT, max_source_variables=sys.maxsize), active
     dolt_declaration = None
     if active["profile"] == "dolt" and source is not None:
         dolt_declaration = source.require_exact_match(

src/openstatspec/sql/catalog_api.py

@@ -10,6 +10,7 @@
     CATALOG_CONTRACT_ID, CATALOG_SCHEMA_VERSION, catalog as core_catalog,
 )
 from .profiles import validate_connection_url
+from .database_urls import require_existing_database_url
 from .workflow import (
     PROFILE_ID, PROFILE_SCHEMA_VERSION, TransformationError, workflow_catalog,
 )
@@ -55,6 +56,7 @@ def _assert_workflow(connection: Any, tables: Any) -> None:
 
 def catalog_datasets(*, database_url: str, kind: str | None = None) -> dict[str, Any]:
     """List source and/or derived datasets without mutating either catalog."""
+    require_existing_database_url(database_url)
     if kind not in {None, "core", "derived"}:
         raise ValueError("kind must be core, derived, or None.")
     engine = create_engine(database_url)
@@ -96,6 +98,7 @@ def catalog_datasets(*, database_url: str, kind: str | None = None) -> dict[str,
 
 def catalog_dataset(*, database_url: str, dataset_id: str, kind: str) -> dict[str, Any]:
     """Return one public catalog record, variables, weight, and derived lineage."""
+    require_existing_database_url(database_url)
     dataset_id = _uuid(dataset_id)
     if kind not in {"core", "derived"}:
         raise ValueError("kind must be core or derived.")

src/openstatspec/sql/database_urls.py

@@ -1,10 +1,27 @@
 """Database URL invariants shared by persistent catalog operations."""
 
+from pathlib import Path
+from urllib.parse import unquote
+
 from sqlalchemy.engine import make_url
 
 from ..core import UnsupportedOperationError
 
 
+def require_existing_database_url(database_url: str) -> None:
+    """Prevent SQLite's implicit file creation during a read operation."""
+    url = make_url(database_url)
+    if url.get_backend_name() != "sqlite":
+        return
+    database = url.database or ""
+    if database in {"", ":memory:", "file::memory:"} or url.query.get("mode") == "memory":
+        return
+    if str(url.query.get("uri", "")).lower() == "true" and database.startswith("file:"):
+        database = unquote(database[5:])
+    if not Path(database).is_file():
+        raise UnsupportedOperationError("Read operations require an existing SQLite database file.")
+
+
 def require_persistent_database_url(database_url: str) -> None:
     """Reject SQLite URLs whose catalog disappears with a connection or engine."""
     parsed_url = make_url(database_url)

src/openstatspec/sql/wide.py

@@ -32,7 +32,7 @@
     store_imported_dataset as store_normative_dataset,
 )
 from .catalog_verification import verify_catalog_relations
-from .database_urls import require_persistent_database_url
+from .database_urls import require_existing_database_url, require_persistent_database_url
 
 _IDENTIFIER = re.compile(r"[^a-zA-Z0-9_]+")
 
@@ -648,6 +648,7 @@ def dolt_state_snapshot(
     *, database_url: str, dolt_conformance_source: Any | None = None,
 ) -> dict[str, Any]:
     """Return read-only branch, HEAD, status, and diff evidence for Dolt."""
+    require_existing_database_url(database_url)
     validate_connection_url(database_url)
     active = active_connection(
         database_url, dolt_conformance_source=dolt_conformance_source,
@@ -1049,6 +1050,7 @@ def read_wide_dataset(
     dolt_conformance_source: Any | None = None,
 ) -> tuple[dict[str, Any], list[dict[str, Any]], list[dict[str, Any]]]:
     """Read an export descriptor from the normative catalog without mutation."""
+    require_existing_database_url(database_url)
     if profile is None:
         profile, _active = read_profile(
             database_url, dolt_conformance_source=dolt_conformance_source,

src/openstatspec/sql/workflow.py

@@ -2492,7 +2492,9 @@ def reconcile_physical_removals(
 def validate_derived_dataset(*, database_url: str, derived_dataset_id: str) -> dict[str, Any]:
     """Validate without creating or migrating catalog state."""
     from .catalog_api import _assert_workflow
+    from .database_urls import require_existing_database_url
 
+    require_existing_database_url(database_url)
     derived_id = _uuid(derived_dataset_id, "derived_dataset_id")
     profile = validate_connection_url(database_url)
     engine = _workflow_engine(database_url, profile.name)

tests/test_read_only_export.py

@@ -135,10 +135,6 @@ def check(_connection, _cursor, statement, _parameters, _context, _many):
 def test_export_and_reads_leave_no_database_trace(read_catalog, tmp_path, suffix):
     url, snapshot, source = read_catalog
     before = snapshot()
-    if make_url(url).get_backend_name() == "mysql":
-        # This is the real server identity and the empty packaged registry.
-        with pytest.raises(UnsupportedOperationError):
-            wide.initialize_wide_catalog(database_url=url)
     output = tmp_path / ("export" + suffix)
     result = openstatspec.export_sav(database_url=url, dataset_id="sample", destination=output)
     assert "operation_id" not in result
@@ -216,7 +212,11 @@ def test_dolt_reads_do_not_enable_undeclared_writes(monkeypatch):
         "server_version": "2.3.0",
     }
     monkeypatch.setattr(capabilities, "active_connection", lambda *_a, **_k: active)
-    assert capabilities.read_profile(url)[0].name == "dolt"
+    profile = capabilities.read_profile(url)[0]
+    assert profile.name == "dolt"
+    # A table imported under a larger explicit write envelope stays readable.
+    from openstatspec.sql.profiles import preflight
+    preflight(profile, 1_016)
     with pytest.raises(UnsupportedOperationError):
         capabilities.effective_profile(url)
     with pytest.raises(UnsupportedOperationError):
@@ -228,6 +228,30 @@ def test_dolt_reads_do_not_enable_undeclared_writes(monkeypatch):
         )
 
 
+@pytest.mark.parametrize("operation", ["export", "validate", "capabilities", "list", "get", "derived", "dolt_state"])
+@pytest.mark.parametrize("uri", [False, True])
+def test_reads_do_not_create_a_missing_sqlite_file(tmp_path, operation, uri):
+    path = tmp_path / "absent.sqlite"
+    url = f"sqlite:///file:{path}?uri=true" if uri else f"sqlite:///{path}"
+    calls = {
+        "export": lambda: openstatspec.export_sav(database_url=url, dataset_id="sample", destination=tmp_path / "out.sav"),
+        "validate": lambda: openstatspec.validate(database_url=url, dataset_id="sample"),
+        "capabilities": lambda: openstatspec.capabilities(url),
+        "list": lambda: openstatspec.list_datasets(database_url=url),
+        "get": lambda: openstatspec.get_dataset(database_url=url, dataset_id=str(uuid4()), kind="core"),
+        "derived": lambda: openstatspec.validate_derived(database_url=url, derived_dataset_id=str(uuid4())),
+        "dolt_state": lambda: openstatspec.dolt_state_snapshot(database_url=url),
+    }
+    with pytest.raises(UnsupportedOperationError, match="existing SQLite"):
+        calls[operation]()
+    assert not path.exists()
+    assert not (tmp_path / "out.sav").exists()
+
+
+def test_database_io_policy_is_explicit():
+    assert openstatspec.capabilities()["database_io_policy"] == "openstatspec-database-io-v1"
+
+
 def test_derived_validation_does_not_initialize_catalog(tmp_path):
     url = f"sqlite:///{tmp_path / 'catalog.sqlite'}"
     openstatspec.initialize_catalog(database_url=url)