fix: add URL signing methods to ObjectStoreProtocol and storage backends (#287)

Adds proper URL signing support to storage backends with type-safe methods in the `ObjectStoreProtocol`. Also includes logging improvements across the codebase and a new config normalization utility.

Author: cofin

AGENTS.md

@@ -510,6 +510,53 @@ class AdapterConfig(AsyncDatabaseConfig):  # or SyncDatabaseConfig
 
 - v0.33.0+: `pool_config` → `connection_config`, `pool_instance` → `connection_instance`
 
+### Parameter Deprecation Pattern
+
+For backwards-compatible parameter renames in configuration classes:
+
+```python
+def __init__(
+    self,
+    *,
+    new_param: dict[str, Any] | None = None,
+    **kwargs: Any,  # Capture old parameter names
+) -> None:
+    from sqlspec.utils.deprecation import warn_deprecation
+
+    if "old_param" in kwargs:
+        warn_deprecation(
+            version="0.33.0",
+            deprecated_name="old_param",
+            kind="parameter",
+            removal_in="0.34.0",
+            alternative="new_param",
+            info="Parameter renamed for consistency across pooled and non-pooled adapters",
+        )
+        if new_param is None:
+            new_param = kwargs.pop("old_param")
+        else:
+            kwargs.pop("old_param")  # Discard if new param provided
+
+    # Continue with initialization using new_param
+```
+
+**Use this pattern when:**
+
+- Renaming configuration parameters for consistency
+- Need backwards compatibility during migration period
+- Want clear deprecation warnings for users
+
+**Key principles:**
+
+- Use `**kwargs` to capture old parameter names without changing signature
+- Import `warn_deprecation` inside function to avoid circular imports
+- New parameter takes precedence when both old and new provided
+- Use `kwargs.pop()` to remove handled parameters and avoid `**kwargs` passing issues
+- Provide clear migration path (version, alternative, removal timeline)
+- Set removal timeline (typically next minor or major version)
+
+**Reference implementation:** `sqlspec/config.py` (lines 920-1517, all 4 base config classes)
+
 ### Error Handling
 
 - Custom exceptions inherit from `SQLSpecError` in `sqlspec/exceptions.py`

docs/migration-guides/v0.33.0.md

@@ -0,0 +1,151 @@
+# Migration Guide: v0.33.0
+
+## Configuration Parameter Renaming
+
+SQLSpec v0.33.0 renames configuration parameters for consistency across all database adapters.
+
+### Changed Parameters
+
+| Old Name | New Name | Affected Configs |
+|----------|----------|------------------|
+| `pool_config` | `connection_config` | All adapters |
+| `pool_instance` | `connection_instance` | All adapters |
+
+### Migration Steps
+
+Update your configuration instantiation to use the new parameter names:
+
+```python
+# Before (deprecated, will be removed in v0.34.0)
+from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+config = AsyncpgConfig(
+    pool_config={"dsn": "postgresql://localhost/mydb"},
+    pool_instance=existing_pool,
+)
+```
+
+```python
+# After (recommended)
+from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+config = AsyncpgConfig(
+    connection_config={"dsn": "postgresql://localhost/mydb"},
+    connection_instance=existing_pool,
+)
+```
+
+### Rationale
+
+The new parameter names accurately reflect usage across both:
+
+- **Pooled adapters** (AsyncPG, DuckDB, Psycopg, etc.) - where the parameters configure connection pools
+- **Non-pooled adapters** (BigQuery, ADBC, Spanner) - where the parameters configure individual connections
+
+This eliminates conceptual confusion and provides consistent API across all adapters.
+
+### Backwards Compatibility
+
+**Deprecation Period**: v0.33.0 - v0.33.x
+
+Old parameter names continue to work with deprecation warnings. You will see warnings like:
+
+```
+DeprecationWarning: Use of deprecated parameter 'pool_config'.
+Deprecated in SQLSpec 0.33.0.
+This parameter will be removed in 0.34.0.
+Use 'connection_config' instead.
+Parameter renamed for consistency across pooled and non-pooled adapters.
+```
+
+**Breaking Change**: v0.34.0
+
+Old parameter names will be completely removed in v0.34.0. Update your code during the deprecation period to avoid breakage.
+
+### Affected Adapters
+
+All database adapter configurations are affected:
+
+- **Async Pooled**: AsyncPG, Asyncmy, Aiosqlite, Psqlpy, Psycopg (async), Spanner (async), Oracle (async)
+- **Sync Pooled**: DuckDB, SQLite, Psycopg (sync), Spanner (sync), Oracle (sync)
+- **Non-pooled**: BigQuery, ADBC
+
+### Type Checking
+
+Type checkers (mypy, pyright) will not autocomplete or recognize the old parameter names. This is intentional to encourage migration to the new names.
+
+### Examples
+
+#### AsyncPG (Pooled)
+
+```python
+from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+# Old
+config = AsyncpgConfig(
+    pool_config={"dsn": "postgresql://localhost/db", "min_size": 5, "max_size": 10}
+)
+
+# New
+config = AsyncpgConfig(
+    connection_config={"dsn": "postgresql://localhost/db", "min_size": 5, "max_size": 10}
+)
+```
+
+#### BigQuery (Non-pooled)
+
+```python
+from sqlspec.adapters.bigquery import BigQueryConfig
+
+# Old
+config = BigQueryConfig(
+    pool_config={"project": "my-project"}
+)
+
+# New
+config = BigQueryConfig(
+    connection_config={"project": "my-project"}
+)
+```
+
+#### Pre-created Pool Instance
+
+```python
+import asyncpg
+from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+pool = await asyncpg.create_pool(dsn="postgresql://localhost/db")
+
+# Old
+config = AsyncpgConfig(pool_instance=pool)
+
+# New
+config = AsyncpgConfig(connection_instance=pool)
+```
+
+### Search and Replace
+
+For quick migration across your codebase:
+
+```bash
+# Find all occurrences
+grep -r "pool_config" . --include="*.py"
+grep -r "pool_instance" . --include="*.py"
+
+# Replace (GNU sed)
+find . -name "*.py" -exec sed -i 's/pool_config=/connection_config=/g' {} +
+find . -name "*.py" -exec sed -i 's/pool_instance=/connection_instance=/g' {} +
+```
+
+Review changes carefully after automated replacement to ensure correctness.
+
+## Questions?
+
+If you encounter issues during migration:
+
+1. Check that you're using SQLSpec v0.33.0 or later
+2. Verify deprecation warnings appear (ensures old names are recognized)
+3. Update to new parameter names when you see warnings
+4. Test your application thoroughly after migration
+
+Report migration issues at: https://github.com/litestar-org/sqlspec/issues