sqlspec 0.56.2__tar.gz → 0.57.0__tar.gz

{sqlspec-0.56.2 → sqlspec-0.57.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.56.2
+Version: 0.57.0
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.56.2 → sqlspec-0.57.0}/pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.56.2"
+version = "0.57.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -308,7 +308,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.56.2"
+current_version = "0.57.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/builder/_base.py

@@ -4,7 +4,7 @@ Provides abstract base classes and core functionality for SQL query builders.
 """
 
 import re
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from collections.abc import Callable, Iterable, Mapping
 from typing import Any, NoReturn, cast
 
@@ -115,7 +115,7 @@ class BuiltQuery:
         return hash((self.sql, frozenset(self.parameters.items()), self.dialect))
 
 
-class QueryBuilder(ABC):
+class QueryBuilder:
     """Abstract base class for SQL query builders.
 
     Provides common functionality for dialect handling, parameter management,

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/config.py

@@ -11,7 +11,7 @@ modules only after proving the boundary with installed-wheel smoke coverage.
 import asyncio
 import threading
 from abc import ABC, abstractmethod
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from inspect import Signature, signature
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeAlias, TypeVar, cast
@@ -145,7 +145,8 @@ class MigrationConfig(TypedDict):
     """List of extension names whose migrations should be included. Extension migrations maintain separate versioning and are prefixed with 'ext_{name}_'.
 
     Note: Extensions with migration support (litestar, adk, events) are auto-included when
-    their settings are present in ``extension_config``. Use ``exclude_extensions`` to opt out.
+    their settings are present in ``extension_config``, as is any extension whose settings
+    declare ``migrations_path``. Use ``exclude_extensions`` to opt out.
     """
 
     exclude_extensions: NotRequired["list[str]"]
@@ -238,6 +239,13 @@ class LitestarConfig(TypedDict):
     All fields are optional with sensible defaults.
     """
 
+    migrations_path: NotRequired[str | Path]
+    """Directory containing this extension's migrations, or a ``'<dotted.module>:<subdir>'`` specification.
+
+    Overrides the default ``sqlspec.extensions.<name>`` lookup. Setting this auto-includes the
+    extension in ``migration_config["include_extensions"]``.
+    """
+
     session_table: NotRequired["bool | str"]
     """Enable session table for server-side session storage.
 
@@ -476,6 +484,13 @@ class ADKConfig(TypedDict):
         3. Selective features (sessions OR memory, not both)
     """
 
+    migrations_path: NotRequired[str | Path]
+    """Directory containing this extension's migrations, or a ``'<dotted.module>:<subdir>'`` specification.
+
+    Overrides the default ``sqlspec.extensions.<name>`` lookup. Setting this auto-includes the
+    extension in ``migration_config["include_extensions"]``.
+    """
+
     manage_schema: NotRequired[bool]
     """Apply additive target-schema reconciliation. Default: True."""
 
@@ -591,6 +606,13 @@ class EventsConfig(TypedDict):
     Use in ``extension_config["events"]``.
     """
 
+    migrations_path: NotRequired[str | Path]
+    """Directory containing this extension's migrations, or a ``'<dotted.module>:<subdir>'`` specification.
+
+    Overrides the default ``sqlspec.extensions.<name>`` lookup. Setting this auto-includes the
+    extension in ``migration_config["include_extensions"]``.
+    """
+
     manage_schema: NotRequired[bool]
     """Apply additive target-schema reconciliation. Default: True."""
 
@@ -944,6 +966,40 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         """
         return self._ensure_migration_commands()
 
+    def add_extension_migrations(
+        self, name: str, migrations_path: "str | Path", settings: "dict[str, Any] | None" = None
+    ) -> None:
+        """Register migrations shipped by a package outside the ``sqlspec.extensions`` namespace.
+
+        Records the extension under ``extension_config``, opts it into
+        ``migration_config["include_extensions"]``, and rebuilds the cached migration
+        commands so the extension is discovered. Migrations are versioned under the
+        ``ext_{name}_`` prefix, so ``name`` must stay stable once migrations are applied.
+
+        Args:
+            name: Extension name, used as the ``ext_{name}_`` version prefix.
+            migrations_path: Directory containing the migrations, or a
+                ``'<dotted.module>:<subdir>'`` specification.
+            settings: Extension settings passed to its migrations. Merged into any
+                settings already registered under ``name``.
+        """
+        extension_config = cast("dict[str, Any]", self.extension_config)
+        existing = extension_config.get(name)
+        merged: dict[str, Any] = dict(existing) if isinstance(existing, Mapping) else {}
+        if settings:
+            merged.update(settings)
+        merged["migrations_path"] = migrations_path
+        extension_config[name] = merged
+
+        migration_config = cast("dict[str, Any]", self.migration_config)
+        include_extensions = migration_config.get("include_extensions")
+        include_list = list(include_extensions) if include_extensions else []
+        if name not in include_list:
+            include_list.append(name)
+        migration_config["include_extensions"] = include_list
+
+        self._rebuild_migration_commands()
+
     @abstractmethod
     def migrate_up(
         self,
@@ -1074,6 +1130,9 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         - **adk**: When any adk settings are present
         - **events**: When any events settings are present
 
+        Any other extension is auto-included when its settings declare ``migrations_path``,
+        which is how packages outside the ``sqlspec.extensions`` namespace ship migrations.
+
         Use ``exclude_extensions`` to opt out of auto-inclusion.
         """
         extension_settings = cast("dict[str, Any]", self.extension_config)
@@ -1087,7 +1146,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
 
         litestar_settings = extension_settings.get("litestar")
         if (
-            litestar_settings is not None
+            isinstance(litestar_settings, Mapping)
             and "session_table" in litestar_settings
             and "litestar" not in exclude_extensions
         ):
@@ -1104,22 +1163,21 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         if events_settings is not None and "events" not in exclude_extensions:
             extensions_to_add.append("events")
 
+        for ext_name, ext_settings in extension_settings.items():
+            if ext_name in extensions_to_add or ext_name in exclude_extensions:
+                continue
+            if isinstance(ext_settings, Mapping) and "migrations_path" in ext_settings:
+                extensions_to_add.append(ext_name)
+
         if not extensions_to_add:
             return
 
         include_extensions = migration_config.get("include_extensions")
-        if include_extensions is None:
-            include_list: list[str] = []
-            migration_config["include_extensions"] = include_list
-        elif isinstance(include_extensions, tuple):
-            include_list = list(include_extensions)  # pyright: ignore
-            migration_config["include_extensions"] = include_list
-        else:
-            include_list = cast("list[str]", include_extensions)
-
+        include_list = list(include_extensions) if include_extensions else []
         for ext in extensions_to_add:
             if ext not in include_list:
                 include_list.append(ext)
+        migration_config["include_extensions"] = include_list
 
     def _build_storage_capabilities(self) -> "StorageCapabilities":
         arrow_dependency_needed = self.supports_native_arrow_export or self.supports_native_arrow_import
@@ -1250,6 +1308,10 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         """Initialize migration loader and migration command helpers."""
         runtime = self.get_observability_runtime()
         self._migration_loader = SQLFileLoader(runtime=runtime)
+        self._rebuild_migration_commands()
+
+    def _rebuild_migration_commands(self) -> None:
+        """Rebuild the cached migration commands against current configuration."""
         self._migration_commands = create_migration_commands(self)  # pyright: ignore
 
     def _ensure_migration_loader(self) -> "SQLFileLoader":

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/core/filters.py

@@ -18,7 +18,7 @@ Features:
     - Cacheable filter configurations
 """
 
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from collections import abc
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeAlias
@@ -68,7 +68,7 @@ FilterTypeT = TypeVar("FilterTypeT", bound="StatementFilter")
 
 
 @mypyc_attr(allow_interpreted_subclasses=True)
-class StatementFilter(ABC):
+class StatementFilter:
     """Abstract base class for filters that can be appended to a statement."""
 
     __slots__ = ()
@@ -334,7 +334,7 @@ class OnBeforeAfterFilter(_DatetimeBoundFilter):
         return self._lower_value
 
 
-class InAnyFilter(StatementFilter, ABC, Generic[T]):
+class InAnyFilter(StatementFilter, Generic[T]):
     """Base class for collection-based filters that support ANY operations."""
 
     __slots__ = ("_field_name", "_values")
@@ -473,7 +473,7 @@ class NotAnyCollectionFilter(InAnyFilter[T]):
     _parameter_suffix: ClassVar[str] = "not_any"
 
 
-class PaginationFilter(StatementFilter, ABC):
+class PaginationFilter(StatementFilter):
     """Base class for pagination-related filters."""
 
     __slots__ = ()

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/core/result/_base.py

@@ -9,8 +9,7 @@ Classes:
     ArrowResult: Apache Arrow format results for data interchange.
 """
 
-from abc import ABC, abstractmethod
-from collections.abc import Iterable, Iterator, Sequence
+from abc import abstractmethod
 from typing import TYPE_CHECKING, Any, Final, Literal, cast, overload
 
 from mypy_extensions import mypyc_attr
@@ -42,6 +41,8 @@ from sqlspec.utils.module_loader import ensure_pandas, ensure_polars
 from sqlspec.utils.schema import to_schema
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
     from sqlspec.core.compiler import OperationType
     from sqlspec.typing import ArrowReturnFormat, ArrowTable, PandasDataFrame, PolarsDataFrame, SchemaT
 
@@ -57,7 +58,7 @@ _TWO_COLUMN_THRESHOLD: Final[int] = 2
 
 
 @mypyc_attr(allow_interpreted_subclasses=False)
-class StatementResult(ABC, Iterable[Any]):
+class StatementResult:
     """Abstract base class for SQL statement execution results.
 
     Provides a common interface for handling different types of SQL operation

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/core/splitter.py

@@ -16,7 +16,7 @@ MySQL, SQLite, DuckDB, and BigQuery.
 import logging
 import re
 import threading
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from collections.abc import Callable
 from enum import Enum
 from re import Pattern
@@ -141,7 +141,7 @@ SpecialTerminatorHandler: TypeAlias = Callable[[list[Token], int], bool]
 
 
 @mypyc_attr(allow_interpreted_subclasses=False)
-class DialectConfig(ABC):
+class DialectConfig:
     """Abstract base class for SQL dialect configurations."""
 
     __slots__ = DIALECT_CONFIG_SLOTS

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/extensions/events/_store.py

@@ -40,6 +40,7 @@ class BaseEventQueueStore(ABC, Generic[ConfigT]):
         "event_poll_interval",
         "lease_seconds",
         "manage_schema",
+        "migrations_path",
         "poll_interval",
         "queue_table",
         "retention_seconds",

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/extensions/litestar/store.py

@@ -63,6 +63,7 @@ class BaseSQLSpecStore(ABC, Generic[ConfigT]):
         "extra_commit_statuses",
         "extra_rollback_statuses",
         "manage_schema",
+        "migrations_path",
         "pool_key",
         "run_migrations",
         "session_key",

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/migrations/base.py

@@ -1,7 +1,7 @@
 """Base classes for SQLSpec migrations."""
 
 import os
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
 
@@ -13,6 +13,7 @@ from sqlspec.builder import CreateTable, Delete, Insert, Select, Update, sql
 from sqlspec.exceptions import MigrationError
 from sqlspec.migrations.templates import MigrationTemplateSettings, build_template_settings
 from sqlspec.migrations.utils import resolve_default_schema as _resolve_default_schema
+from sqlspec.migrations.utils import resolve_extension_migrations_path
 from sqlspec.migrations.utils import resolve_tracker_schema as _resolve_tracker_schema
 from sqlspec.migrations.version import parse_version
 from sqlspec.utils.logging import get_logger
@@ -70,7 +71,7 @@ class AppliedMigrationRecord(TypedDict):
 
 
 @mypyc_attr(allow_interpreted_subclasses=True)
-class BaseMigrationTracker(ABC, Generic[DriverT]):
+class BaseMigrationTracker(Generic[DriverT]):
     """Base class for migration version tracking."""
 
     __slots__ = ("_output_policy", "version_table", "version_table_name", "version_table_schema")
@@ -413,7 +414,7 @@ class BaseMigrationTracker(ABC, Generic[DriverT]):
 
 
 @mypyc_attr(allow_interpreted_subclasses=True)
-class BaseMigrationCommands(ABC, Generic[ConfigT, DriverT]):
+class BaseMigrationCommands(Generic[ConfigT, DriverT]):
     """Base class for migration commands."""
 
     extension_configs: "dict[str, dict[str, Any]]"
@@ -553,26 +554,52 @@ class BaseMigrationCommands(ABC, Generic[ConfigT, DriverT]):
     def _discover_extension_migrations(self) -> "dict[str, Path]":
         """Discover migration paths for configured extensions.
 
+        An extension may declare ``migrations_path`` in its ``extension_config`` entry to
+        ship migrations from any package. Extensions without it resolve against the
+        ``sqlspec.extensions.<name>`` namespace.
+
         Returns:
             Dictionary mapping extension names to their migration paths.
         """
 
         extension_migrations = {}
 
-        for ext_name in self.extension_configs:
-            module_name = "sqlspec.extensions.litestar" if ext_name == "litestar" else f"sqlspec.extensions.{ext_name}"
+        for ext_name, ext_options in self.extension_configs.items():
+            spec = ext_options.get("migrations_path")
+            if spec is not None:
+                resolved = resolve_extension_migrations_path(ext_name, spec)
+                if resolved is None:
+                    logger.warning(
+                        "Extension '%s' migrations_path %r is not an existing directory; "
+                        "no migrations were registered for it.",
+                        ext_name,
+                        spec,
+                    )
+                else:
+                    extension_migrations[ext_name] = resolved
+                    logger.debug("Found migrations for extension %s at %s", ext_name, resolved)
+                continue
 
+            module_name = f"sqlspec.extensions.{ext_name}"
             try:
                 module_path = module_to_os_path(module_name)
-                migrations_dir = module_path / "migrations"
+            except ImportError:
+                logger.warning(
+                    "Extension '%s' is configured but '%s' is not importable; no migrations were "
+                    "registered for it. Set extension_config['%s']['migrations_path'] to register "
+                    "migrations shipped by another package.",
+                    ext_name,
+                    module_name,
+                    ext_name,
+                )
+                continue
 
-                if migrations_dir.exists():
-                    extension_migrations[ext_name] = migrations_dir
-                    logger.debug("Found migrations for extension %s at %s", ext_name, migrations_dir)
-                else:
-                    logger.warning("No migrations directory found for extension %s", ext_name)
-            except TypeError:
-                logger.warning("Extension %s not found", ext_name)
+            migrations_dir = module_path / "migrations"
+            if migrations_dir.exists():
+                extension_migrations[ext_name] = migrations_dir
+                logger.debug("Found migrations for extension %s at %s", ext_name, migrations_dir)
+            else:
+                logger.debug("Extension %s ships no migrations directory", ext_name)
 
         return extension_migrations
 

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/migrations/loaders.py

@@ -14,7 +14,7 @@ from typing import Any, Final, cast
 
 from sqlspec.loader import SQLFileLoader as CoreSQLFileLoader
 from sqlspec.migrations.context import MigrationContext
-from sqlspec.migrations.version import _format_sequential_version
+from sqlspec.migrations.version import _format_sequential_version, parse_extension_stem
 from sqlspec.utils.sync_tools import await_
 
 __all__ = ("BaseMigrationLoader", "MigrationLoadError", "PythonFileLoader", "SQLFileLoader", "get_migration_loader")
@@ -26,7 +26,7 @@ class MigrationLoadError(Exception):
     """Exception raised when migration loading fails."""
 
 
-class BaseMigrationLoader(abc.ABC):
+class BaseMigrationLoader:
     """Abstract base class for migration loaders."""
 
     __slots__ = ()
@@ -169,16 +169,16 @@ class SQLFileLoader(BaseMigrationLoader):
         Returns:
             Version string or empty string if invalid.
         """
-        extension_version_parts = 3
         timestamp_min_length = 4
 
         name_without_ext = filename.rsplit(".", 1)[0]
 
         if name_without_ext.startswith("ext_"):
-            parts = name_without_ext.split("_", 3)
-            if len(parts) >= extension_version_parts:
-                return f"{parts[0]}_{parts[1]}_{parts[2]}"
-            return ""
+            extension = parse_extension_stem(name_without_ext)
+            if extension is None:
+                return ""
+            ext_name, ext_version = extension
+            return f"ext_{ext_name}_{ext_version}"
 
         parts = name_without_ext.split("_", 1)
         if parts and parts[0].isdigit():

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/migrations/runner.py

@@ -5,7 +5,7 @@ import hashlib
 import logging
 import re
 import time
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
@@ -15,7 +15,7 @@ from sqlspec.migrations.context import MigrationContext
 from sqlspec.migrations.loaders import _load_migration_sql, get_migration_loader
 from sqlspec.migrations.templates import TemplateDescriptionHints
 from sqlspec.migrations.utils import resolve_default_schema as _resolve_default_schema
-from sqlspec.migrations.version import _format_sequential_version, parse_version
+from sqlspec.migrations.version import _format_sequential_version, parse_extension_stem, parse_version
 from sqlspec.observability import resolve_db_system
 from sqlspec.utils.logging import get_logger, log_with_context
 from sqlspec.utils.sync_tools import async_
@@ -57,7 +57,7 @@ class _MigrationFileEntry:
         self.extension_name = extension_name
 
 
-class BaseMigrationRunner(ABC):
+class BaseMigrationRunner:
     """Base migration runner with common functionality shared between sync and async implementations."""
 
     def __init__(
@@ -238,16 +238,16 @@ class BaseMigrationRunner(ABC):
         Returns:
             The extracted version string or None.
         """
-        extension_version_parts = 3
         timestamp_min_length = 4
 
         name_without_ext = filename.rsplit(".", 1)[0]
 
         if name_without_ext.startswith("ext_"):
-            parts = name_without_ext.split("_", 3)
-            if len(parts) >= extension_version_parts:
-                return f"{parts[0]}_{parts[1]}_{parts[2]}"
-            return None
+            extension = parse_extension_stem(name_without_ext)
+            if extension is None:
+                return None
+            ext_name, ext_version = extension
+            return f"ext_{ext_name}_{ext_version}"
 
         parts = name_without_ext.split("_", 1)
         if parts and parts[0].isdigit():
@@ -435,10 +435,9 @@ class BaseMigrationRunner(ABC):
         if context_to_use and file_path.name.startswith("ext_"):
             version = self._extract_version(file_path.name)
             if version and version.startswith("ext_"):
-                min_extension_version_parts = 3
-                parts = version.split("_", 2)
-                if len(parts) >= min_extension_version_parts:
-                    ext_name = parts[1]
+                extension = parse_extension_stem(version)
+                if extension is not None:
+                    ext_name = extension[0]
                     if ext_name in self.extension_configs:
                         context_to_use = MigrationContext(
                             dialect=self.context.dialect if self.context else None,
@@ -486,7 +485,7 @@ class BaseMigrationRunner(ABC):
     def _resolve_default_schema(self) -> str | None:
         """Return the configured default schema for migration execution."""
         config = self.context.config if self.context else None
-        migration_config = cast("dict[str, Any]", getattr(config, "migration_config", None))
+        migration_config = cast("dict[str, Any] | None", getattr(config, "migration_config", None))
         return _resolve_default_schema(migration_config)
 
     def _resolve_use_transaction(self, migration: "LoadedMigrationMetadata", use_transaction: "bool | None") -> bool:

{sqlspec-0.56.2 → sqlspec-0.57.0}/sqlspec/migrations/utils.py

@@ -8,18 +8,28 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 
+from sqlspec.exceptions import MigrationError
 from sqlspec.migrations.templates import MigrationTemplateSettings, TemplateValidationError, build_template_settings
 from sqlspec.utils.logging import get_logger
+from sqlspec.utils.module_loader import module_to_os_path
 from sqlspec.utils.text import slugify
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
 
     from sqlspec.config import DatabaseConfigProtocol
-__all__ = ("create_migration_file", "get_author", "resolve_default_schema", "resolve_tracker_schema")
+__all__ = (
+    "create_migration_file",
+    "get_author",
+    "resolve_default_schema",
+    "resolve_extension_migrations_path",
+    "resolve_tracker_schema",
+)
 
 logger = get_logger(__name__)
 
+_MIN_MODULE_NAME_LENGTH = 2
+
 
 def resolve_default_schema(migration_config: "Mapping[str, Any] | None") -> str | None:
     """Resolve the configured default migration schema.
@@ -149,6 +159,93 @@ def get_author(
     return _resolve_git_author()
 
 
+def resolve_extension_migrations_path(ext_name: str, spec: "str | Path") -> "Path | None":
+    """Resolve an extension ``migrations_path`` setting to a migrations directory.
+
+    Accepts a filesystem path, or a ``<dotted.module>:<subdir>`` specification resolved
+    against the installed package. Relative filesystem paths resolve against the current
+    working directory, matching ``script_location``.
+
+    Args:
+        ext_name: Extension name the setting belongs to, used in error messages.
+        spec: Filesystem path or ``<dotted.module>:<subdir>`` specification.
+
+    Raises:
+        MigrationError: The value is not a string or path, is empty, or names a module
+            that cannot be imported.
+
+    Returns:
+        The resolved directory, or None when it does not exist.
+    """
+    if isinstance(spec, Path):
+        candidate = spec
+    elif isinstance(spec, str):
+        if not spec.strip():
+            msg = (
+                f"Extension '{ext_name}' has an empty migrations_path; "
+                f"set extension_config['{ext_name}']['migrations_path'] to a directory "
+                f"or a '<dotted.module>:<subdir>' specification."
+            )
+            raise MigrationError(msg)
+        candidate = _resolve_migrations_spec(ext_name, spec)
+    else:
+        msg = (
+            f"Extension '{ext_name}' has an invalid migrations_path of type "
+            f"{type(spec).__name__}; set extension_config['{ext_name}']['migrations_path'] "
+            f"to a string or Path."
+        )
+        raise MigrationError(msg)
+
+    return candidate if candidate.is_dir() else None
+
+
+def _resolve_migrations_spec(ext_name: str, spec: str) -> "Path":
+    """Resolve a string migrations_path to a directory, honoring module specifications.
+
+    Args:
+        ext_name: Extension name the setting belongs to, used in error messages.
+        spec: Filesystem path or ``<dotted.module>:<subdir>`` specification.
+
+    Raises:
+        MigrationError: The specification names a module that cannot be imported.
+
+    Returns:
+        The resolved directory, which may not exist.
+    """
+    module_name, separator, subdir = spec.partition(":")
+    if not separator or not _is_module_name(module_name):
+        return Path(spec)
+
+    try:
+        module_path = module_to_os_path(module_name)
+    except ImportError as exc:
+        msg = (
+            f"Extension '{ext_name}' migrations_path names module '{module_name}', "
+            f"which could not be imported ({exc}); correct "
+            f"extension_config['{ext_name}']['migrations_path'] or install the package."
+        )
+        raise MigrationError(msg) from exc
+
+    return module_path / subdir if subdir else module_path
+
+
+def _is_module_name(value: str) -> bool:
+    r"""Return whether a string is a dotted Python module name.
+
+    Single-character values are rejected so Windows drive letters in paths such as
+    ``C:\\srv\\migrations`` are treated as filesystem paths rather than modules.
+
+    Args:
+        value: Candidate module name.
+
+    Returns:
+        True when every dot-separated segment is a valid identifier.
+    """
+    if len(value) < _MIN_MODULE_NAME_LENGTH:
+        return False
+    return all(segment.isidentifier() for segment in value.split("."))
+
+
 def _get_git_config(config_key: str) -> str | None:
     """Retrieve git configuration value.