etlantic-snowflake 0.38.0__tar.gz

etlantic_snowflake-0.38.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+site/
+.venv/
+venv/
+.env
+
+# Tools
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+# macOS
+.DS_Store
+**/.DS_Store
+._*
+**/._*
+
+examples/_file_storage_out/
+examples/_generated_*.py
+tmp_cli_contracts/
+tmp_/
+
+# Local durable workspace (reports, artifacts, schema history)
+.etlantic/
+
+# Prefect test home (created by local/CI prefect plugin tests)
+.prefect-test-home/
+
+# Local authoring artifacts (not part of the repo)
+pipeline.definition.json

etlantic_snowflake-0.38.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: etlantic-snowflake
+Version: 0.38.0
+Summary: Experimental Snowflake connector for ETLantic.
+Project-URL: Homepage, https://github.com/eddiethedean/etlantic
+Project-URL: Documentation, https://github.com/eddiethedean/etlantic/tree/main/docs
+Project-URL: Repository, https://github.com/eddiethedean/etlantic
+Project-URL: Issues, https://github.com/eddiethedean/etlantic/issues
+Project-URL: Changelog, https://github.com/eddiethedean/etlantic/blob/main/CHANGELOG.md
+Author-email: Odo Matthews <odosmatthews@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: etlantic<0.39,>=0.38.0
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python<4,>=3.6; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# etlantic-snowflake (Experimental)
+
+Native Snowflake connector for [ETLantic](https://github.com/eddiethedean/etlantic).
+
+**Current release:** 0.38.0.
+
+**Maturity:** Experimental (Alpha classifier). CI uses an in-memory fake with
+`autocommit=False` transactional semantics and `query_id` evidence on
+`CommitReceipt`. Live Snowflake is optional:
+
+```bash
+pip install "etlantic-snowflake[snowflake]==0.38.0"
+```
+
+## Install
+
+```bash
+pip install 'etlantic-snowflake==0.38.0'
+```
+
+Core dependency: `etlantic>=0.38.0,<0.39`.
+
+## Entry points
+
+| Group | Name | Factory |
+|---|---|---|
+| `etlantic.source_connectors` | `snowflake` | `etlantic_snowflake:create_source` |
+| `etlantic.sink_connectors` | `snowflake` | `etlantic_snowflake:create_sink` |
+| `etlantic.storage_connectors` | `snowflake` | `etlantic_snowflake:create_storage` |
+
+## Links
+
+[Source](https://github.com/eddiethedean/etlantic/tree/main/packages/etlantic-snowflake) ·
+[Issues](https://github.com/eddiethedean/etlantic/issues)

etlantic_snowflake-0.38.0/README.md

@@ -0,0 +1,34 @@
+# etlantic-snowflake (Experimental)
+
+Native Snowflake connector for [ETLantic](https://github.com/eddiethedean/etlantic).
+
+**Current release:** 0.38.0.
+
+**Maturity:** Experimental (Alpha classifier). CI uses an in-memory fake with
+`autocommit=False` transactional semantics and `query_id` evidence on
+`CommitReceipt`. Live Snowflake is optional:
+
+```bash
+pip install "etlantic-snowflake[snowflake]==0.38.0"
+```
+
+## Install
+
+```bash
+pip install 'etlantic-snowflake==0.38.0'
+```
+
+Core dependency: `etlantic>=0.38.0,<0.39`.
+
+## Entry points
+
+| Group | Name | Factory |
+|---|---|---|
+| `etlantic.source_connectors` | `snowflake` | `etlantic_snowflake:create_source` |
+| `etlantic.sink_connectors` | `snowflake` | `etlantic_snowflake:create_sink` |
+| `etlantic.storage_connectors` | `snowflake` | `etlantic_snowflake:create_storage` |
+
+## Links
+
+[Source](https://github.com/eddiethedean/etlantic/tree/main/packages/etlantic-snowflake) ·
+[Issues](https://github.com/eddiethedean/etlantic/issues)

etlantic_snowflake-0.38.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "etlantic-snowflake"
+version = "0.38.0"
+description = "Experimental Snowflake connector for ETLantic."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Odo Matthews", email = "odosmatthews@gmail.com" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "etlantic>=0.38.0,<0.39",
+]
+
+[project.optional-dependencies]
+snowflake = ["snowflake-connector-python>=3.6,<4"]
+
+[project.urls]
+Homepage = "https://github.com/eddiethedean/etlantic"
+Documentation = "https://github.com/eddiethedean/etlantic/tree/main/docs"
+Repository = "https://github.com/eddiethedean/etlantic"
+Issues = "https://github.com/eddiethedean/etlantic/issues"
+Changelog = "https://github.com/eddiethedean/etlantic/blob/main/CHANGELOG.md"
+
+[project.entry-points."etlantic.source_connectors"]
+snowflake = "etlantic_snowflake:create_source"
+
+[project.entry-points."etlantic.sink_connectors"]
+snowflake = "etlantic_snowflake:create_sink"
+
+[project.entry-points."etlantic.storage_connectors"]
+snowflake = "etlantic_snowflake:create_storage"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/etlantic_snowflake"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/etlantic_snowflake/etlantic-plugin-manifest.json" = "etlantic_snowflake/etlantic-plugin-manifest.json"

etlantic_snowflake-0.38.0/src/etlantic_snowflake/__init__.py

@@ -0,0 +1,27 @@
+"""Experimental Snowflake connector package for ETLantic."""
+
+from __future__ import annotations
+
+__version__ = "0.38.0"
+
+from etlantic_snowflake.connectors import (
+    SnowflakeSinkConnector,
+    SnowflakeSourceConnector,
+    SnowflakeStorageConnector,
+    create_sink,
+    create_source,
+    create_storage,
+)
+from etlantic_snowflake.fake import FakeSnowflakeConnection, snowflake_sdk_available
+
+__all__ = [
+    "FakeSnowflakeConnection",
+    "SnowflakeSinkConnector",
+    "SnowflakeSourceConnector",
+    "SnowflakeStorageConnector",
+    "__version__",
+    "create_sink",
+    "create_source",
+    "create_storage",
+    "snowflake_sdk_available",
+]

etlantic_snowflake-0.38.0/src/etlantic_snowflake/connectors.py

@@ -0,0 +1,417 @@
+"""Snowflake source / sink / storage connectors (fake by default)."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from etlantic.connectors.capabilities import (
+    IDEMPOTENCY,
+    PUBLICATION_ATOMIC,
+    RECONCILIATION,
+    SOURCE_BATCH_SNAPSHOT,
+    SOURCE_SCHEMA_DISCOVERY,
+    SOURCE_STATISTICS_BOUNDED,
+    TRANSACTIONS,
+    WRITE_APPEND,
+    WRITE_MERGE,
+    WRITE_OVERWRITE,
+)
+from etlantic.connectors.errors import ConnectorConfigError, ConnectorWriteError
+from etlantic.connectors.maturity import ConnectorMaturity
+from etlantic.connectors.models import (
+    SINK_PROTOCOL,
+    SOURCE_PROTOCOL,
+    STORAGE_PROTOCOL,
+    CleanupReceipt,
+    CommitReceipt,
+    ConnectorInfo,
+    CursorProposal,
+    LandingReadManifest,
+    ReadBatch,
+    ReconciliationResult,
+    SchemaInspection,
+    SinkPlan,
+    SourcePlan,
+    WriteSession,
+    fingerprint_public_config,
+)
+from etlantic_snowflake.fake import FakeSnowflakeConnection, snowflake_sdk_available
+
+PROVIDER = "snowflake"
+PACKAGE_VERSION = "0.38.0"
+
+SOURCE_CAPS = frozenset(
+    {
+        SOURCE_BATCH_SNAPSHOT,
+        SOURCE_SCHEMA_DISCOVERY,
+        SOURCE_STATISTICS_BOUNDED,
+        IDEMPOTENCY,
+    }
+)
+SINK_CAPS = frozenset(
+    {
+        WRITE_APPEND,
+        WRITE_OVERWRITE,
+        WRITE_MERGE,
+        PUBLICATION_ATOMIC,
+        TRANSACTIONS,
+        RECONCILIATION,
+        IDEMPOTENCY,
+    }
+)
+
+
+def _public_config(binding: Mapping[str, Any]) -> dict[str, Any]:
+    raw = binding.get("config")
+    if isinstance(raw, dict):
+        return dict(raw)
+    keys = ("table", "schema", "database", "mode", "warehouse")
+    return {k: binding[k] for k in keys if k in binding and binding[k] is not None}
+
+
+def _table_name(binding: Mapping[str, Any], cfg: Mapping[str, Any]) -> str:
+    table = str(cfg.get("table") or binding.get("location") or "")
+    if not table:
+        raise ConnectorConfigError(
+            "snowflake binding requires table",
+            code="PMCONN831",
+            provider=PROVIDER,
+        )
+    schema = cfg.get("schema")
+    database = cfg.get("database")
+    parts = [p for p in (database, schema, table) if p]
+    return ".".join(str(p) for p in parts)
+
+
+@dataclass
+class SnowflakeSourceConnector:
+    connection: FakeSnowflakeConnection = field(default_factory=FakeSnowflakeConnection)
+
+    def info(self) -> ConnectorInfo:
+        return ConnectorInfo(
+            name=PROVIDER,
+            protocol=SOURCE_PROTOCOL,
+            version=PACKAGE_VERSION,
+            provider=PROVIDER,
+            capabilities=tuple(sorted(SOURCE_CAPS)),
+            maturity=ConnectorMaturity.EXPERIMENTAL,
+            metadata={
+                "fake": not snowflake_sdk_available(),
+                "autocommit": False,
+            },
+        )
+
+    async def plan_read(
+        self,
+        *,
+        binding: Mapping[str, Any],
+        context: Mapping[str, Any],
+    ) -> SourcePlan:
+        cfg = _public_config(binding)
+        table = _table_name(binding, cfg)
+        return SourcePlan(
+            provider=PROVIDER,
+            protocol=SOURCE_PROTOCOL,
+            mode="snapshot",
+            identity_scheme="snowflake_query_id/1",
+            listing_intent={"table": table},
+            config_fingerprint=fingerprint_public_config(cfg),
+            root_ref=table,
+            secret_refs=tuple(
+                sorted(str(k) for k in (binding.get("secret_refs") or {}))
+            ),
+        )
+
+    async def read_batches(
+        self,
+        *,
+        plan: SourcePlan,
+        binding: Mapping[str, Any],
+        context: Mapping[str, Any],
+    ) -> AsyncIterator[ReadBatch]:
+        table = str(plan.listing_intent.get("table") or "")
+        result = self.connection.select(table)
+        yield ReadBatch(
+            records=result.rows,
+            batch_index=0,
+            exhausted=True,
+            metadata={"table": table, "query_id": result.query_id},
+        )
+
+    async def propose_cursor(
+        self,
+        *,
+        plan: SourcePlan,
+        manifest: LandingReadManifest,
+        context: Mapping[str, Any],
+    ) -> CursorProposal | None:
+        return None
+
+
+@dataclass
+class SnowflakeSinkConnector:
+    connection: FakeSnowflakeConnection = field(default_factory=FakeSnowflakeConnection)
+    _sessions: dict[str, dict[str, Any]] = field(default_factory=dict, repr=False)
+
+    def info(self) -> ConnectorInfo:
+        return ConnectorInfo(
+            name=PROVIDER,
+            protocol=SINK_PROTOCOL,
+            version=PACKAGE_VERSION,
+            provider=PROVIDER,
+            capabilities=tuple(sorted(SINK_CAPS)),
+            maturity=ConnectorMaturity.EXPERIMENTAL,
+            metadata={
+                "fake": not snowflake_sdk_available(),
+                "autocommit": False,
+                "evidence": "query_id",
+            },
+        )
+
+    async def plan_write(
+        self,
+        *,
+        binding: Mapping[str, Any],
+        context: Mapping[str, Any],
+    ) -> SinkPlan:
+        cfg = _public_config(binding)
+        table = _table_name(binding, cfg)
+        mode = str(cfg.get("mode") or binding.get("mode") or "append")
+        if mode not in {"append", "overwrite", "replace", "merge"}:
+            raise ConnectorConfigError(
+                f"unsupported snowflake write mode {mode!r}",
+                code="PMCONN832",
+                provider=PROVIDER,
+            )
+        return SinkPlan(
+            provider=PROVIDER,
+            protocol=SINK_PROTOCOL,
+            write_mode=mode,
+            config_fingerprint=fingerprint_public_config(cfg),
+            root_ref=table,
+            secret_refs=tuple(
+                sorted(str(k) for k in (binding.get("secret_refs") or {}))
+            ),
+            metadata={"table": table},
+        )
+
+    async def begin_write(
+        self,
+        *,
+        plan: SinkPlan,
+        binding: Mapping[str, Any],
+        context: Mapping[str, Any],
+    ) -> WriteSession:
+        if self.connection.autocommit:
+            raise ConnectorWriteError(
+                "snowflake transactional path requires autocommit=False",
+                code="PMCONN833",
+                provider=PROVIDER,
+            )
+        session_id = f"sf-{uuid.uuid4().hex[:12]}"
+        self._sessions[session_id] = {
+            "table": str(plan.metadata.get("table") or plan.root_ref),
+            "mode": plan.write_mode or "append",
+            "rows": [],
+            "query_ids": [],
+            "status": "open",
+        }
+        return WriteSession(
+            session_id=session_id,
+            provider=PROVIDER,
+            protocol=SINK_PROTOCOL,
+            metadata={"table": plan.metadata.get("table"), "autocommit": False},
+        )
+
+    async def write_batch(
+        self,
+        session: WriteSession,
+        batch: Any,
+        *,
+        context: Mapping[str, Any],
+    ) -> None:
+        state = self._require(session.session_id)
+        if isinstance(batch, Mapping):
+            state["rows"].append(dict(batch))
+        elif isinstance(batch, (list, tuple)):
+            for item in batch:
+                state["rows"].append(
+                    dict(item) if isinstance(item, Mapping) else {"value": item}
+                )
+        else:
+            state["rows"].append({"value": batch})
+
+    async def prepare(
+        self,
+        session: WriteSession,
+        *,
+        context: Mapping[str, Any],
+    ) -> None:
+        state = self._require(session.session_id)
+        result = self.connection.execute(
+            f"STAGE {state['mode']} INTO {state['table']}",
+            table=str(state["table"]),
+            rows=list(state["rows"]),
+            operation=str(state["mode"]),
+        )
+        state["query_ids"].append(result.query_id)
+        state["prepared"] = True
+
+    async def commit(
+        self,
+        session: WriteSession,
+        *,
+        context: Mapping[str, Any],
+    ) -> CommitReceipt:
+        state = self._require(session.session_id)
+        if not state.get("prepared"):
+            await self.prepare(session, context=context)
+        query_ids = self.connection.commit()
+        # Prefer session-staged ids; fall back to connection commit list.
+        evidence_ids = list(state["query_ids"]) or query_ids
+        primary = evidence_ids[-1] if evidence_ids else None
+        state["status"] = "committed"
+        return CommitReceipt(
+            status="committed",
+            session_id=session.session_id,
+            provider=PROVIDER,
+            publication_id=primary,
+            message="snowflake transaction committed",
+            metadata={
+                "table": state["table"],
+                "query_id": primary,
+                "query_ids": evidence_ids,
+                "autocommit": False,
+            },
+        )
+
+    async def abort(
+        self,
+        session: WriteSession,
+        *,
+        context: Mapping[str, Any],
+    ) -> CommitReceipt:
+        state = self._require(session.session_id)
+        self.connection.rollback()
+        state["status"] = "aborted"
+        return CommitReceipt(
+            status="rolled_back",
+            session_id=session.session_id,
+            provider=PROVIDER,
+            message="snowflake transaction rolled back",
+            metadata={
+                "table": state["table"],
+                "query_ids": list(state["query_ids"]),
+                "autocommit": False,
+            },
+        )
+
+    async def reconcile(
+        self,
+        receipt: CommitReceipt,
+        *,
+        context: Mapping[str, Any],
+    ) -> ReconciliationResult:
+        query_id = receipt.publication_id or (receipt.metadata or {}).get("query_id")
+        if not query_id:
+            return ReconciliationResult(status="unknown", message="missing query_id")
+        found = self.connection.lookup_query(str(query_id))
+        if found is None:
+            return ReconciliationResult(
+                status="rolled_back",
+                message="query_id not found",
+                metadata={"query_id": query_id},
+            )
+        if str(query_id) in self.connection._pending_queries:
+            return ReconciliationResult(
+                status="unknown",
+                publication_id=str(query_id),
+                message="query still pending in open transaction",
+                metadata={"query_id": query_id},
+            )
+        return ReconciliationResult(
+            status="committed",
+            publication_id=str(query_id),
+            message="query_id found in committed history",
+            metadata={"query_id": query_id},
+        )
+
+    async def cleanup(
+        self,
+        receipt: CommitReceipt,
+        *,
+        context: Mapping[str, Any],
+    ) -> CleanupReceipt:
+        return CleanupReceipt(status="skipped", message="no cleanup for snowflake fake")
+
+    def _require(self, session_id: str) -> dict[str, Any]:
+        state = self._sessions.get(session_id)
+        if state is None:
+            raise ConnectorWriteError(
+                f"unknown snowflake session {session_id!r}",
+                code="PMCONN834",
+                provider=PROVIDER,
+            )
+        return state
+
+
+@dataclass
+class SnowflakeStorageConnector:
+    connection: FakeSnowflakeConnection = field(default_factory=FakeSnowflakeConnection)
+
+    def info(self) -> ConnectorInfo:
+        return ConnectorInfo(
+            name=PROVIDER,
+            protocol=STORAGE_PROTOCOL,
+            version=PACKAGE_VERSION,
+            provider=PROVIDER,
+            capabilities=(SOURCE_SCHEMA_DISCOVERY, SOURCE_STATISTICS_BOUNDED),
+            maturity=ConnectorMaturity.EXPERIMENTAL,
+            metadata={"fake": not snowflake_sdk_available()},
+        )
+
+    async def inspect_schema(
+        self,
+        *,
+        binding: Mapping[str, Any],
+        context: Mapping[str, Any],
+    ) -> SchemaInspection:
+        cfg = _public_config(binding)
+        table = _table_name(binding, cfg)
+        rows = self.connection.tables.get(table, [])
+        fields: tuple[dict[str, Any], ...] = ()
+        if rows:
+            fields = tuple(
+                {"name": k, "type": type(v).__name__} for k, v in rows[0].items()
+            )
+        return SchemaInspection(
+            provider=PROVIDER,
+            fields=fields,
+            row_estimate=len(rows),
+            metadata={"table": table},
+        )
+
+
+def create_source() -> SnowflakeSourceConnector:
+    return SnowflakeSourceConnector()
+
+
+def create_sink() -> SnowflakeSinkConnector:
+    return SnowflakeSinkConnector()
+
+
+def create_storage() -> SnowflakeStorageConnector:
+    return SnowflakeStorageConnector()
+
+
+__all__ = [
+    "SnowflakeSinkConnector",
+    "SnowflakeSourceConnector",
+    "SnowflakeStorageConnector",
+    "create_sink",
+    "create_source",
+    "create_storage",
+]

etlantic_snowflake-0.38.0/src/etlantic_snowflake/etlantic-plugin-manifest.json

@@ -0,0 +1,66 @@
+{
+  "capabilities": [
+    "source.batch_snapshot",
+    "source.schema_discovery",
+    "source.statistics_bounded",
+    "write.append",
+    "write.overwrite",
+    "write.merge",
+    "publication.atomic",
+    "transactions",
+    "reconciliation",
+    "idempotency"
+  ],
+  "digest": "sha256:3f13efa403ec55103580cc0794e4b321dd073021c23967c2533b87e5c9992385",
+  "entries": [
+    {
+      "capabilities": [
+        "source.batch_snapshot",
+        "source.schema_discovery",
+        "source.statistics_bounded",
+        "idempotency"
+      ],
+      "engine": "snowflake",
+      "group": "etlantic.source_connectors",
+      "name": "snowflake",
+      "protocol": "etlantic.source/1",
+      "target": "etlantic_snowflake:create_source"
+    },
+    {
+      "capabilities": [
+        "write.append",
+        "write.overwrite",
+        "write.merge",
+        "publication.atomic",
+        "transactions",
+        "reconciliation",
+        "idempotency"
+      ],
+      "engine": "snowflake",
+      "group": "etlantic.sink_connectors",
+      "name": "snowflake",
+      "protocol": "etlantic.sink/1",
+      "target": "etlantic_snowflake:create_sink"
+    },
+    {
+      "capabilities": [
+        "source.schema_discovery",
+        "source.statistics_bounded"
+      ],
+      "engine": "snowflake",
+      "group": "etlantic.storage_connectors",
+      "name": "snowflake",
+      "protocol": "etlantic.storage/1",
+      "target": "etlantic_snowflake:create_storage"
+    }
+  ],
+  "package": "etlantic-snowflake",
+  "privileges": [],
+  "protocol_range": "etlantic.source/1,etlantic.sink/1,etlantic.storage/1",
+  "provenance": {
+    "publisher": "etlantic",
+    "maturity": "experimental"
+  },
+  "schema": "etlantic.plugin_manifest/1",
+  "version": "0.38.0"
+}

etlantic_snowflake-0.38.0/src/etlantic_snowflake/fake.py

@@ -0,0 +1,116 @@
+"""In-memory Snowflake fake: autocommit-off + query_id evidence."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def snowflake_sdk_available() -> bool:
+    try:
+        import snowflake.connector  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+@dataclass
+class FakeQueryResult:
+    query_id: str
+    rows_affected: int = 0
+    rows: tuple[dict[str, Any], ...] = ()
+
+
+@dataclass
+class FakeSnowflakeConnection:
+    """Transactional fake: autocommit is always off.
+
+    Staged DML lives in a transaction buffer until ``commit()`` or ``rollback()``.
+    Every statement receives a stable ``query_id`` for CommitReceipt evidence and
+    post-loss reconciliation.
+    """
+
+    autocommit: bool = False
+    tables: dict[str, list[dict[str, Any]]] = field(default_factory=dict)
+    _txn: list[tuple[str, str, list[dict[str, Any]]]] = field(default_factory=list)
+    _committed_queries: dict[str, FakeQueryResult] = field(default_factory=dict)
+    _pending_queries: dict[str, FakeQueryResult] = field(default_factory=dict)
+    _query_seq: int = 0
+
+    def __post_init__(self) -> None:
+        # Enforce transactional path regardless of constructor override.
+        self.autocommit = False
+
+    def execute(
+        self,
+        sql: str,
+        *,
+        table: str,
+        rows: list[dict[str, Any]] | None = None,
+        operation: str = "append",
+    ) -> FakeQueryResult:
+        if self.autocommit:
+            raise RuntimeError("autocommit must remain False for transactional path")
+        self._query_seq += 1
+        query_id = f"sfqid-{self._query_seq:08d}-{uuid.uuid4().hex[:6]}"
+        payload = list(rows or [])
+        result = FakeQueryResult(query_id=query_id, rows_affected=len(payload), rows=())
+        self._txn.append((operation, table, payload))
+        self._pending_queries[query_id] = result
+        return result
+
+    def select(self, table: str) -> FakeQueryResult:
+        self._query_seq += 1
+        query_id = f"sfqid-{self._query_seq:08d}-{uuid.uuid4().hex[:6]}"
+        rows = tuple(self.tables.get(table, []))
+        result = FakeQueryResult(query_id=query_id, rows_affected=0, rows=rows)
+        self._committed_queries[query_id] = result
+        return result
+
+    def commit(self) -> list[str]:
+        query_ids: list[str] = []
+        for operation, table, rows in self._txn:
+            current = list(self.tables.get(table, []))
+            if operation in {"overwrite", "replace"}:
+                current = list(rows)
+            elif operation == "merge":
+                # Keyed upsert on "id" when present; else append.
+                by_id = {
+                    r["id"]: dict(r)
+                    for r in current
+                    if isinstance(r, dict) and "id" in r
+                }
+                rest = [r for r in current if not (isinstance(r, dict) and "id" in r)]
+                for row in rows:
+                    if isinstance(row, dict) and "id" in row:
+                        by_id[row["id"]] = dict(row)
+                    else:
+                        rest.append(
+                            dict(row) if isinstance(row, dict) else {"value": row}
+                        )
+                current = rest + list(by_id.values())
+            else:
+                current.extend(rows)
+            self.tables[table] = current
+        query_ids = list(self._pending_queries)
+        self._committed_queries.update(self._pending_queries)
+        self._pending_queries.clear()
+        self._txn.clear()
+        return query_ids
+
+    def rollback(self) -> None:
+        self._txn.clear()
+        self._pending_queries.clear()
+
+    def lookup_query(self, query_id: str) -> FakeQueryResult | None:
+        return self._committed_queries.get(query_id) or self._pending_queries.get(
+            query_id
+        )
+
+
+__all__ = [
+    "FakeQueryResult",
+    "FakeSnowflakeConnection",
+    "snowflake_sdk_available",
+]