refactor: retract storage staging and expose destination resolution

docs/changelog.rst

@@ -23,6 +23,27 @@ Unreleased
 * Removed the undocumented ``sqlspec.exceptions.wrap_exceptions`` helper,
   superseded by the typed per-adapter exception handlers.
 
+**Added:**
+
+* Storage pipelines expose ``resolve_destination()``, returning a
+  ``ResolvedStorageTarget(uri, protocol)`` without opening a database session.
+  Direct remote URIs retain their address, alias paths resolve relative to the
+  configured backend, and local paths become absolute. Backend options come
+  only from the method's explicit ``storage_options`` argument, not pipeline
+  writer defaults.
+
+**Breaking changes:**
+
+* Removed the unimplemented driver methods ``stage_artifact()``,
+  ``flush_staging_artifacts()``, and ``get_storage_job()``, and the exported
+  ``StorageLoadRequest`` and ``StagedArtifact`` types. Retain the
+  ``StorageBridgeJob`` returned by a storage operation instead of looking it up.
+* Removed pipeline ``allocate_staging_artifacts()`` and
+  ``cleanup_staging_artifacts()``, the ``requires_staging_for_load`` and
+  ``staging_protocols`` capability settings, and the unused
+  ``storage_bridge.partitions_created`` diagnostic counter. Working storage
+  import, export, and per-operation partition telemetry remain available.
+
 v0.62.2 - Litestar config lookup diagnostics
 ---------------------------------------------
 

docs/reference/storage.rst

@@ -64,10 +64,12 @@ Pipelines
 
 .. autoclass:: sqlspec.storage.SyncStoragePipeline
    :members:
+   :inherited-members:
    :show-inheritance:
 
 .. autoclass:: sqlspec.storage.AsyncStoragePipeline
    :members:
+   :inherited-members:
    :show-inheritance:
 
 Registry
@@ -88,19 +90,15 @@ Configuration Types
    :members:
    :show-inheritance:
 
-.. autoclass:: sqlspec.storage.StorageLoadRequest
-   :members:
-   :show-inheritance:
-
-.. autoclass:: sqlspec.storage.StagedArtifact
+.. autoclass:: sqlspec.storage.StorageTelemetry
    :members:
    :show-inheritance:
 
-.. autoclass:: sqlspec.storage.StorageTelemetry
+.. autoclass:: sqlspec.storage.StorageBridgeJob
    :members:
    :show-inheritance:
 
-.. autoclass:: sqlspec.storage.StorageBridgeJob
+.. autoclass:: sqlspec.storage.ResolvedStorageTarget
    :members:
    :show-inheritance:
 

sqlspec/adapters/bigquery/config.py

@@ -170,8 +170,6 @@ class BigQueryConfig(NoPoolSyncConfig[BigQueryConnection, BigQueryDriver]):
     supports_arrow_streaming: ClassVar[bool] = True
     supports_native_row_streaming: ClassVar[bool] = True
     supports_native_parquet_export: ClassVar[bool] = True
-    requires_staging_for_load: ClassVar[bool] = True
-    staging_protocols: "ClassVar[tuple[str, ...]]" = ("gs://",)
     _connection_context_class: "ClassVar[type[BigQueryConnectionContext]]" = BigQueryConnectionContext
     _session_factory_class: "ClassVar[type[_BigQuerySessionConnectionHandler]]" = _BigQuerySessionConnectionHandler
     _session_context_class: "ClassVar[type[BigQuerySessionContext]]" = BigQuerySessionContext

sqlspec/adapters/spanner/config.py

@@ -255,7 +255,6 @@ class SpannerSyncConfig(SyncDatabaseConfig["SpannerConnection", "AbstractSession
     supports_native_arrow_import: ClassVar[bool] = True
     supports_native_parquet_export: ClassVar[bool] = False
     supports_native_parquet_import: ClassVar[bool] = False
-    requires_staging_for_load: ClassVar[bool] = False
     _connection_context_class: "ClassVar[type[SpannerConnectionContext]]" = SpannerConnectionContext
     _session_factory_class: "ClassVar[type[_SpannerSessionConnectionHandler]]" = _SpannerSessionConnectionHandler
     _session_context_class: "ClassVar[type[SpannerSessionContext]]" = SpannerSessionContext

sqlspec/config.py

@@ -943,8 +943,6 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     supports_migration_schemas: "ClassVar[bool]" = False
     supports_native_parquet_import: "ClassVar[bool]" = False
     supports_native_parquet_export: "ClassVar[bool]" = False
-    requires_staging_for_load: "ClassVar[bool]" = False
-    staging_protocols: "ClassVar[tuple[str, ...]]" = ()
     default_storage_profile: "ClassVar[str | None]" = None
     storage_partition_strategies: "ClassVar[tuple[str, ...]]" = ("fixed",)
     bind_key: "str | None"
@@ -1349,8 +1347,6 @@ def _build_storage_capabilities(self) -> "StorageCapabilities":
             "arrow_import_enabled": bool(self.supports_native_arrow_import and arrow_dependency_ready),
             "parquet_export_enabled": bool(self.supports_native_parquet_export and parquet_dependency_ready),
             "parquet_import_enabled": bool(self.supports_native_parquet_import and parquet_dependency_ready),
-            "requires_staging_for_load": self.requires_staging_for_load,
-            "staging_protocols": list(self.staging_protocols),
             "partition_strategies": list(self.storage_partition_strategies),
         }
         if self.default_storage_profile is not None:

sqlspec/driver/_async.py

@@ -1648,39 +1648,6 @@ async def load_from_records(
         arrow_table = self._records_to_arrow_table(prepared_records, columns)
         return await self.load_from_arrow(table, arrow_table, overwrite=overwrite)
 
-    def stage_artifact(self, request: "dict[str, Any]") -> "dict[str, Any]":
-        """Provision staging metadata for adapters that require remote URIs.
-
-        Args:
-            request: Staging request configuration.
-
-        Returns:
-            Staging metadata dict.
-        """
-        self._raise_storage_not_implemented("stage_artifact")
-        raise NotImplementedError
-
-    def flush_staging_artifacts(self, artifacts: "list[dict[str, Any]]", *, error: Exception | None = None) -> None:
-        """Clean up staged artifacts after a job completes.
-
-        Args:
-            artifacts: List of staging artifacts to clean up.
-            error: Optional error that triggered cleanup.
-        """
-        if artifacts:
-            self._raise_storage_not_implemented("flush_staging_artifacts")
-
-    def get_storage_job(self, job_id: str) -> "StorageBridgeJob | None":
-        """Fetch a previously created job handle.
-
-        Args:
-            job_id: Job identifier.
-
-        Returns:
-            StorageBridgeJob if found, None otherwise.
-        """
-        return None
-
     # ─────────────────────────────────────────────────────────────────────────────
     # UTILITY METHODS
     # ─────────────────────────────────────────────────────────────────────────────

sqlspec/driver/_sync.py

@@ -1636,39 +1636,6 @@ def load_from_records(
         arrow_table = self._records_to_arrow_table(prepared_records, columns)
         return self.load_from_arrow(table, arrow_table, overwrite=overwrite)
 
-    def stage_artifact(self, request: "dict[str, Any]") -> "dict[str, Any]":
-        """Provision staging metadata for adapters that require remote URIs.
-
-        Args:
-            request: Staging request configuration.
-
-        Returns:
-            Staging metadata dict.
-        """
-        self._raise_storage_not_implemented("stage_artifact")
-        raise NotImplementedError
-
-    def flush_staging_artifacts(self, artifacts: "list[dict[str, Any]]", *, error: Exception | None = None) -> None:
-        """Clean up staged artifacts after a job completes.
-
-        Args:
-            artifacts: List of staging artifacts to clean up.
-            error: Optional error that triggered cleanup.
-        """
-        if artifacts:
-            self._raise_storage_not_implemented("flush_staging_artifacts")
-
-    def get_storage_job(self, job_id: str) -> "StorageBridgeJob | None":
-        """Fetch a previously created job handle.
-
-        Args:
-            job_id: Job identifier.
-
-        Returns:
-            StorageBridgeJob if found, None otherwise.
-        """
-        return None
-
     # ─────────────────────────────────────────────────────────────────────────────
     # UTILITY METHODS
     # ─────────────────────────────────────────────────────────────────────────────

sqlspec/storage/__init__.py

@@ -12,12 +12,11 @@
 from sqlspec.storage.pipeline import (
     AsyncStoragePipeline,
     PartitionStrategyConfig,
-    StagedArtifact,
+    ResolvedStorageTarget,
     StorageBridgeJob,
     StorageCapabilities,
     StorageDestination,
     StorageFormat,
-    StorageLoadRequest,
     StorageTelemetry,
     SyncStoragePipeline,
     create_storage_bridge_job,
@@ -30,12 +29,11 @@
 __all__ = (
     "AsyncStoragePipeline",
     "PartitionStrategyConfig",
-    "StagedArtifact",
+    "ResolvedStorageTarget",
     "StorageBridgeJob",
     "StorageCapabilities",
     "StorageDestination",
     "StorageFormat",
-    "StorageLoadRequest",
     "StorageRegistry",
     "StorageTelemetry",
     "SyncStoragePipeline",