sqlspec 0.26.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/adapters/oracledb/migrations.py

@@ -5,12 +5,14 @@ to handle Oracle's unique SQL syntax requirements.
 """
 
 import getpass
-from typing import TYPE_CHECKING, Any, Optional, cast
+from typing import TYPE_CHECKING, Any
 
-from sqlspec._sql import sql
-from sqlspec.builder import CreateTable
+from rich.console import Console
+
+from sqlspec.builder import CreateTable, Select, sql
 from sqlspec.migrations.base import BaseMigrationTracker
 from sqlspec.utils.logging import get_logger
+from sqlspec.utils.version import parse_version
 
 if TYPE_CHECKING:
     from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
@@ -18,10 +20,20 @@ if TYPE_CHECKING:
 __all__ = ("OracleAsyncMigrationTracker", "OracleSyncMigrationTracker")
 
 logger = get_logger("migrations.oracle")
+console = Console()
 
 
 class OracleMigrationTrackerMixin:
-    """Mixin providing Oracle-specific migration table creation."""
+    """Mixin providing Oracle-specific migration table creation and querying.
+
+    Oracle has unique identifier handling rules:
+    - Unquoted identifiers are case-insensitive and stored as UPPERCASE
+    - Quoted identifiers are case-sensitive and stored exactly as written
+
+    This mixin overrides SQL builder methods to add quoted identifiers for
+    all column references, ensuring they match the lowercase column names
+    created by the migration table.
+    """
 
     __slots__ = ()
 
@@ -41,6 +53,8 @@ class OracleMigrationTrackerMixin:
         return (
             sql.create_table(self.version_table)
             .column("version_num", "VARCHAR2(32)", primary_key=True)
+            .column("version_type", "VARCHAR2(16)")
+            .column("execution_sequence", "INTEGER")
             .column("description", "VARCHAR2(2000)")
             .column("applied_at", "TIMESTAMP", default="CURRENT_TIMESTAMP")
             .column("execution_time_ms", "INTEGER")
@@ -48,16 +62,152 @@ class OracleMigrationTrackerMixin:
             .column("applied_by", "VARCHAR2(255)")
         )
 
+    def _get_current_version_sql(self) -> Select:
+        """Get Oracle-specific SQL for retrieving current version.
+
+        Uses uppercase column names with lowercase aliases to match Python expectations.
+        Oracle stores unquoted identifiers as UPPERCASE, so we query UPPERCASE columns
+        and alias them as quoted "lowercase" for result consistency.
+
+        Returns:
+            SQL builder object for version query.
+        """
+        return (
+            sql.select('VERSION_NUM AS "version_num"')
+            .from_(self.version_table)
+            .order_by("EXECUTION_SEQUENCE DESC")
+            .limit(1)
+        )
+
+    def _get_applied_migrations_sql(self) -> Select:
+        """Get Oracle-specific SQL for retrieving all applied migrations.
+
+        Uses uppercase column names with lowercase aliases to match Python expectations.
+        Oracle stores unquoted identifiers as UPPERCASE, so we query UPPERCASE columns
+        and alias them as quoted "lowercase" for result consistency.
+
+        Returns:
+            SQL builder object for migrations query.
+        """
+        return (
+            sql.select(
+                'VERSION_NUM AS "version_num"',
+                'VERSION_TYPE AS "version_type"',
+                'EXECUTION_SEQUENCE AS "execution_sequence"',
+                'DESCRIPTION AS "description"',
+                'APPLIED_AT AS "applied_at"',
+                'EXECUTION_TIME_MS AS "execution_time_ms"',
+                'CHECKSUM AS "checksum"',
+                'APPLIED_BY AS "applied_by"',
+            )
+            .from_(self.version_table)
+            .order_by("EXECUTION_SEQUENCE")
+        )
+
+    def _get_next_execution_sequence_sql(self) -> Select:
+        """Get Oracle-specific SQL for retrieving next execution sequence.
+
+        Uses uppercase column names with lowercase alias to match Python expectations.
+        Oracle stores unquoted identifiers as UPPERCASE, so we query UPPERCASE columns
+        and alias them as quoted "lowercase" for result consistency.
+
+        Returns:
+            SQL builder object for sequence query.
+        """
+        return sql.select('COALESCE(MAX(EXECUTION_SEQUENCE), 0) + 1 AS "next_seq"').from_(self.version_table)
+
+    def _get_existing_columns_sql(self) -> str:
+        """Get SQL to query existing columns in the tracking table.
+
+        Returns:
+            Raw SQL string for Oracle's USER_TAB_COLUMNS query.
+        """
+        return f"""
+            SELECT column_name
+            FROM user_tab_columns
+            WHERE table_name = '{self.version_table.upper()}'
+        """
+
+    def _detect_missing_columns(self, existing_columns: "set[str]") -> "set[str]":
+        """Detect which columns are missing from the current schema.
+
+        Args:
+            existing_columns: Set of existing column names (uppercase).
+
+        Returns:
+            Set of missing column names (lowercase).
+        """
+        target_create = self._get_create_table_sql()
+        target_columns = {col.name.lower() for col in target_create.columns}
+        existing_lower = {col.lower() for col in existing_columns}
+        return target_columns - existing_lower
+
 
 class OracleSyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTracker["SyncDriverAdapterBase"]):
     """Oracle-specific sync migration tracker."""
 
     __slots__ = ()
 
+    def _migrate_schema_if_needed(self, driver: "SyncDriverAdapterBase") -> None:
+        """Check for and add any missing columns to the tracking table.
+
+        Uses the driver's data dictionary to query existing columns from Oracle's
+        USER_TAB_COLUMNS metadata table.
+
+        Args:
+            driver: The database driver to use.
+        """
+        try:
+            columns_data = driver.data_dictionary.get_columns(driver, self.version_table)
+            existing_columns = {str(row["column_name"]).upper() for row in columns_data}
+            missing_columns = self._detect_missing_columns(existing_columns)
+
+            if not missing_columns:
+                logger.debug("Migration tracking table schema is up-to-date")
+                return
+
+            console.print(
+                f"[cyan]Migrating tracking table schema, adding columns: {', '.join(sorted(missing_columns))}[/]"
+            )
+
+            for col_name in sorted(missing_columns):
+                self._add_column(driver, col_name)
+
+            driver.commit()
+            console.print("[green]Migration tracking table schema updated successfully[/]")
+
+        except Exception as e:
+            logger.warning("Could not check or migrate tracking table schema: %s", e)
+
+    def _add_column(self, driver: "SyncDriverAdapterBase", column_name: str) -> None:
+        """Add a single column to the tracking table.
+
+        Args:
+            driver: The database driver to use.
+            column_name: Name of the column to add (lowercase).
+        """
+        target_create = self._get_create_table_sql()
+        column_def = next((col for col in target_create.columns if col.name.lower() == column_name), None)
+
+        if not column_def:
+            return
+
+        default_clause = f" DEFAULT {column_def.default}" if column_def.default else ""
+        not_null_clause = " NOT NULL" if column_def.not_null else ""
+
+        alter_sql = f"""
+            ALTER TABLE {self.version_table}
+            ADD {column_def.name} {column_def.dtype}{default_clause}{not_null_clause}
+        """
+
+        driver.execute(alter_sql)
+        logger.debug("Added column %s to tracking table", column_name)
+
     def ensure_tracking_table(self, driver: "SyncDriverAdapterBase") -> None:
         """Create the migration tracking table if it doesn't exist.
 
         Uses a PL/SQL block to make the operation atomic and prevent race conditions.
+        Also checks for and adds missing columns to support schema migrations.
 
         Args:
             driver: The database driver to use.
@@ -67,6 +217,8 @@ class OracleSyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrack
             EXECUTE IMMEDIATE '
             CREATE TABLE {self.version_table} (
                 version_num VARCHAR2(32) PRIMARY KEY,
+                version_type VARCHAR2(16),
+                execution_sequence INTEGER,
                 description VARCHAR2(2000),
                 applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                 execution_time_ms INTEGER,
@@ -85,7 +237,9 @@ class OracleSyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrack
         driver.execute_script(create_script)
         driver.commit()
 
-    def get_current_version(self, driver: "SyncDriverAdapterBase") -> "Optional[str]":
+        self._migrate_schema_if_needed(driver)
+
+    def get_current_version(self, driver: "SyncDriverAdapterBase") -> "str | None":
         """Get the latest applied migration version.
 
         Args:
@@ -95,7 +249,8 @@ class OracleSyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrack
             The current migration version or None if no migrations applied.
         """
         result = driver.execute(self._get_current_version_sql())
-        return result.data[0]["VERSION_NUM"] if result.data else None
+        data = result.get_data()
+        return data[0]["version_num"] if data else None
 
     def get_applied_migrations(self, driver: "SyncDriverAdapterBase") -> "list[dict[str, Any]]":
         """Get all applied migrations in order.
@@ -104,15 +259,10 @@ class OracleSyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrack
             driver: The database driver to use.
 
         Returns:
-            List of migration records as dictionaries.
+            List of migration records as dictionaries with lowercase keys.
         """
         result = driver.execute(self._get_applied_migrations_sql())
-        if not result.data:
-            return []
-
-        normalized_data = [{key.lower(): value for key, value in row.items()} for row in result.data]
-
-        return cast("list[dict[str, Any]]", normalized_data)
+        return result.get_data()
 
     def record_migration(
         self, driver: "SyncDriverAdapterBase", version: str, description: str, execution_time_ms: int, checksum: str
@@ -126,10 +276,17 @@ class OracleSyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrack
             execution_time_ms: Execution time in milliseconds.
             checksum: MD5 checksum of the migration content.
         """
-
         applied_by = getpass.getuser()
+        parsed_version = parse_version(version)
+        version_type = parsed_version.type.value
+
+        next_seq_result = driver.execute(self._get_next_execution_sequence_sql())
+        seq_data = next_seq_result.get_data()
+        execution_sequence = seq_data[0]["next_seq"] if seq_data else 1
 
-        record_sql = self._get_record_migration_sql(version, description, execution_time_ms, checksum, applied_by)
+        record_sql = self._get_record_migration_sql(
+            version, version_type, execution_sequence, description, execution_time_ms, checksum, applied_by
+        )
         driver.execute(record_sql)
         driver.commit()
 
@@ -144,16 +301,107 @@ class OracleSyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrack
         driver.execute(remove_sql)
         driver.commit()
 
+    def update_version_record(self, driver: "SyncDriverAdapterBase", old_version: str, new_version: str) -> None:
+        """Update migration version record from timestamp to sequential.
+
+        Updates version_num and version_type while preserving execution_sequence,
+        applied_at, and other tracking metadata. Used during fix command.
+
+        Idempotent: If the version is already updated, logs and continues without error.
+        This allows fix command to be safely re-run after pulling changes.
+
+        Args:
+            driver: The database driver to use.
+            old_version: Current timestamp version string.
+            new_version: New sequential version string.
+
+        Raises:
+            ValueError: If neither old_version nor new_version found in database.
+        """
+        parsed_new_version = parse_version(new_version)
+        new_version_type = parsed_new_version.type.value
+
+        result = driver.execute(self._get_update_version_sql(old_version, new_version, new_version_type))
+
+        if result.rows_affected == 0:
+            check_result = driver.execute(self._get_applied_migrations_sql())
+            applied_versions = {row["version_num"] for row in check_result.data} if check_result.data else set()
+
+            if new_version in applied_versions:
+                logger.debug("Version already updated: %s -> %s", old_version, new_version)
+                return
+
+            msg = f"Migration {old_version} not found in database for update to {new_version}"
+            raise ValueError(msg)
+
+        driver.commit()
+
 
 class OracleAsyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTracker["AsyncDriverAdapterBase"]):
     """Oracle-specific async migration tracker."""
 
     __slots__ = ()
 
+    async def _migrate_schema_if_needed(self, driver: "AsyncDriverAdapterBase") -> None:
+        """Check for and add any missing columns to the tracking table.
+
+        Uses the driver's data dictionary to query existing columns from Oracle's
+        USER_TAB_COLUMNS metadata table.
+
+        Args:
+            driver: The database driver to use.
+        """
+        try:
+            columns_data = await driver.data_dictionary.get_columns(driver, self.version_table)
+            existing_columns = {str(row["column_name"]).upper() for row in columns_data}
+            missing_columns = self._detect_missing_columns(existing_columns)
+
+            if not missing_columns:
+                logger.debug("Migration tracking table schema is up-to-date")
+                return
+
+            console.print(
+                f"[cyan]Migrating tracking table schema, adding columns: {', '.join(sorted(missing_columns))}[/]"
+            )
+
+            for col_name in sorted(missing_columns):
+                await self._add_column(driver, col_name)
+
+            await driver.commit()
+            console.print("[green]Migration tracking table schema updated successfully[/]")
+
+        except Exception as e:
+            logger.warning("Could not check or migrate tracking table schema: %s", e)
+
+    async def _add_column(self, driver: "AsyncDriverAdapterBase", column_name: str) -> None:
+        """Add a single column to the tracking table.
+
+        Args:
+            driver: The database driver to use.
+            column_name: Name of the column to add (lowercase).
+        """
+        target_create = self._get_create_table_sql()
+        column_def = next((col for col in target_create.columns if col.name.lower() == column_name), None)
+
+        if not column_def:
+            return
+
+        default_clause = f" DEFAULT {column_def.default}" if column_def.default else ""
+        not_null_clause = " NOT NULL" if column_def.not_null else ""
+
+        alter_sql = f"""
+            ALTER TABLE {self.version_table}
+            ADD {column_def.name} {column_def.dtype}{default_clause}{not_null_clause}
+        """
+
+        await driver.execute(alter_sql)
+        logger.debug("Added column %s to tracking table", column_name)
+
     async def ensure_tracking_table(self, driver: "AsyncDriverAdapterBase") -> None:
         """Create the migration tracking table if it doesn't exist.
 
         Uses a PL/SQL block to make the operation atomic and prevent race conditions.
+        Also checks for and adds missing columns to support schema migrations.
 
         Args:
             driver: The database driver to use.
@@ -163,6 +411,8 @@ class OracleAsyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrac
             EXECUTE IMMEDIATE '
             CREATE TABLE {self.version_table} (
                 version_num VARCHAR2(32) PRIMARY KEY,
+                version_type VARCHAR2(16),
+                execution_sequence INTEGER,
                 description VARCHAR2(2000),
                 applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                 execution_time_ms INTEGER,
@@ -181,7 +431,9 @@ class OracleAsyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrac
         await driver.execute_script(create_script)
         await driver.commit()
 
-    async def get_current_version(self, driver: "AsyncDriverAdapterBase") -> "Optional[str]":
+        await self._migrate_schema_if_needed(driver)
+
+    async def get_current_version(self, driver: "AsyncDriverAdapterBase") -> "str | None":
         """Get the latest applied migration version.
 
         Args:
@@ -191,7 +443,8 @@ class OracleAsyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrac
             The current migration version or None if no migrations applied.
         """
         result = await driver.execute(self._get_current_version_sql())
-        return result.data[0]["VERSION_NUM"] if result.data else None
+        data = result.get_data()
+        return data[0]["version_num"] if data else None
 
     async def get_applied_migrations(self, driver: "AsyncDriverAdapterBase") -> "list[dict[str, Any]]":
         """Get all applied migrations in order.
@@ -200,15 +453,10 @@ class OracleAsyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrac
             driver: The database driver to use.
 
         Returns:
-            List of migration records as dictionaries.
+            List of migration records as dictionaries with lowercase keys.
         """
         result = await driver.execute(self._get_applied_migrations_sql())
-        if not result.data:
-            return []
-
-        normalized_data = [{key.lower(): value for key, value in row.items()} for row in result.data]
-
-        return cast("list[dict[str, Any]]", normalized_data)
+        return result.get_data()
 
     async def record_migration(
         self, driver: "AsyncDriverAdapterBase", version: str, description: str, execution_time_ms: int, checksum: str
@@ -224,8 +472,16 @@ class OracleAsyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrac
         """
 
         applied_by = getpass.getuser()
+        parsed_version = parse_version(version)
+        version_type = parsed_version.type.value
+
+        next_seq_result = await driver.execute(self._get_next_execution_sequence_sql())
+        seq_data = next_seq_result.get_data()
+        execution_sequence = seq_data[0]["next_seq"] if seq_data else 1
 
-        record_sql = self._get_record_migration_sql(version, description, execution_time_ms, checksum, applied_by)
+        record_sql = self._get_record_migration_sql(
+            version, version_type, execution_sequence, description, execution_time_ms, checksum, applied_by
+        )
         await driver.execute(record_sql)
         await driver.commit()
 
@@ -239,3 +495,38 @@ class OracleAsyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTrac
         remove_sql = self._get_remove_migration_sql(version)
         await driver.execute(remove_sql)
         await driver.commit()
+
+    async def update_version_record(self, driver: "AsyncDriverAdapterBase", old_version: str, new_version: str) -> None:
+        """Update migration version record from timestamp to sequential.
+
+        Updates version_num and version_type while preserving execution_sequence,
+        applied_at, and other tracking metadata. Used during fix command.
+
+        Idempotent: If the version is already updated, logs and continues without error.
+        This allows fix command to be safely re-run after pulling changes.
+
+        Args:
+            driver: The database driver to use.
+            old_version: Current timestamp version string.
+            new_version: New sequential version string.
+
+        Raises:
+            ValueError: If neither old_version nor new_version found in database.
+        """
+        parsed_new_version = parse_version(new_version)
+        new_version_type = parsed_new_version.type.value
+
+        result = await driver.execute(self._get_update_version_sql(old_version, new_version, new_version_type))
+
+        if result.rows_affected == 0:
+            check_result = await driver.execute(self._get_applied_migrations_sql())
+            applied_versions = {row["version_num"] for row in check_result.data} if check_result.data else set()
+
+            if new_version in applied_versions:
+                logger.debug("Version already updated: %s -> %s", old_version, new_version)
+                return
+
+            msg = f"Migration {old_version} not found in database for update to {new_version}"
+            raise ValueError(msg)
+
+        await driver.commit()

sqlspec/adapters/oracledb/type_converter.py

@@ -4,14 +4,16 @@ Provides specialized type handling for Oracle databases, including
 efficient LOB (Large Object) processing and JSON storage detection.
 """
 
+import array
 import re
 from datetime import datetime
+from functools import lru_cache
 from typing import Any, Final
 
 from sqlspec.core.type_conversion import BaseTypeConverter
+from sqlspec.typing import NUMPY_INSTALLED
 from sqlspec.utils.sync_tools import ensure_async_
 
-# Oracle-specific JSON storage detection
 ORACLE_JSON_STORAGE_REGEX: Final[re.Pattern[str]] = re.compile(
     r"^(?:"
     r"(?P<json_type>JSON)|"
@@ -22,15 +24,50 @@ ORACLE_JSON_STORAGE_REGEX: Final[re.Pattern[str]] = re.compile(
     re.IGNORECASE,
 )
 
+ORACLE_SPECIAL_CHARS: Final[frozenset[str]] = frozenset({"{", "[", "-", ":", "T", "."})
+
 
 class OracleTypeConverter(BaseTypeConverter):
     """Oracle-specific type conversion with LOB optimization.
 
     Extends the base TypeDetector with Oracle-specific functionality
     including streaming LOB support and JSON storage type detection.
+    Includes per-instance LRU cache for improved performance.
     """
 
-    __slots__ = ()
+    __slots__ = ("_convert_cache",)
+
+    def __init__(self, cache_size: int = 5000) -> None:
+        """Initialize converter with per-instance conversion cache.
+
+        Args:
+            cache_size: Maximum number of string values to cache (default: 5000)
+        """
+        super().__init__()
+
+        @lru_cache(maxsize=cache_size)
+        def _cached_convert(value: str) -> Any:
+            if not value or not any(c in value for c in ORACLE_SPECIAL_CHARS):
+                return value
+            detected_type = self.detect_type(value)
+            if detected_type:
+                return self.convert_value(value, detected_type)
+            return value
+
+        self._convert_cache = _cached_convert
+
+    def convert_if_detected(self, value: Any) -> Any:
+        """Convert string if special type detected (cached).
+
+        Args:
+            value: Value to potentially convert
+
+        Returns:
+            Converted value or original value
+        """
+        if not isinstance(value, str):
+            return value
+        return self._convert_cache(value)
 
     async def process_lob(self, value: Any) -> Any:
         """Process Oracle LOB objects efficiently.
@@ -44,7 +81,6 @@ class OracleTypeConverter(BaseTypeConverter):
         if not hasattr(value, "read"):
             return value
 
-        # Use ensure_async_ for unified sync/async handling
         read_func = ensure_async_(value.read)
         return await read_func()
 
@@ -106,27 +142,66 @@ class OracleTypeConverter(BaseTypeConverter):
         Returns:
             Converted value appropriate for the column type.
         """
-        # Handle LOB objects
         if hasattr(value, "read"):
             if self.detect_json_storage_type(column_info):
-                # For JSON storage types, decode the LOB content
                 content = self.handle_large_lob(value)
                 content_str = content.decode("utf-8") if isinstance(content, bytes) else content
-                # Try to parse as JSON
-                detected_type = self.detect_type(content_str)
-                if detected_type == "json":
-                    return self.convert_value(content_str, detected_type)
-                return content_str
-            # For other LOB types, return raw content
+                return self.convert_if_detected(content_str)
             return self.handle_large_lob(value)
 
-        # Use base type detection for non-LOB values
         if isinstance(value, str):
-            detected_type = self.detect_type(value)
-            if detected_type:
-                return self.convert_value(value, detected_type)
+            return self.convert_if_detected(value)
+
+        return value
+
+    def convert_vector_to_numpy(self, value: Any) -> Any:
+        """Convert Oracle VECTOR to NumPy array.
+
+        Provides manual conversion API for users who need explicit control
+        over vector transformations or have disabled automatic handlers.
+
+        Args:
+            value: Oracle VECTOR value (array.array) or other value.
+
+        Returns:
+            NumPy ndarray if value is array.array and NumPy is installed,
+            otherwise original value.
+        """
+        if not NUMPY_INSTALLED:
+            return value
+
+        if isinstance(value, array.array):
+            from sqlspec.adapters.oracledb._numpy_handlers import numpy_converter_out
+
+            return numpy_converter_out(value)
+
+        return value
+
+    def convert_numpy_to_vector(self, value: Any) -> Any:
+        """Convert NumPy array to Oracle VECTOR format.
+
+        Provides manual conversion API for users who need explicit control
+        over vector transformations or have disabled automatic handlers.
+
+        Args:
+            value: NumPy ndarray or other value.
+
+        Returns:
+            array.array compatible with Oracle VECTOR if value is ndarray,
+            otherwise original value.
+
+        """
+        if not NUMPY_INSTALLED:
+            return value
+
+        import numpy as np
+
+        if isinstance(value, np.ndarray):
+            from sqlspec.adapters.oracledb._numpy_handlers import numpy_converter_in
+
+            return numpy_converter_in(value)
 
         return value
 
 
-__all__ = ("ORACLE_JSON_STORAGE_REGEX", "OracleTypeConverter")
+__all__ = ("ORACLE_JSON_STORAGE_REGEX", "ORACLE_SPECIAL_CHARS", "OracleTypeConverter")

sqlspec/adapters/psqlpy/_type_handlers.py

@@ -0,0 +1,44 @@
+"""Psqlpy pgvector type handlers for vector data type support.
+
+Provides automatic conversion between NumPy arrays and PostgreSQL vector types
+via pgvector-python library when integrated with psqlpy connection pool.
+
+Note:
+    Full pgvector support for psqlpy is planned for a future release.
+    The driver_features infrastructure (enable_pgvector) has been implemented
+    to enable this feature when the underlying psqlpy library adds support for
+    custom type handlers on pool initialization.
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+from sqlspec.typing import PGVECTOR_INSTALLED
+
+if TYPE_CHECKING:
+    from psqlpy import Connection
+
+__all__ = ("register_pgvector",)
+
+
+logger = logging.getLogger(__name__)
+
+
+def register_pgvector(connection: "Connection") -> None:
+    """Register pgvector type handlers on psqlpy connection.
+
+    Currently a placeholder for future implementation. The psqlpy library
+    does not yet expose a type handler registration API compatible with
+    pgvector's automatic conversion system.
+
+    Args:
+        connection: Psqlpy connection instance.
+
+    Note:
+        When psqlpy adds type handler support, this function will:
+        - Register pgvector extension on the connection
+        - Enable automatic NumPy array <-> PostgreSQL vector conversion
+        - Support vector similarity search operations
+    """
+    if not PGVECTOR_INSTALLED:
+        return

sqlspec/adapters/psqlpy/_types.py

@@ -1,8 +1,9 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from typing import TypeAlias
+
     from psqlpy import Connection
-    from typing_extensions import TypeAlias
 
     PsqlpyConnection: TypeAlias = Connection
 else: