fraiseql-confiture 0.3.7__cp311-cp311-macosx_11_0_arm64.whl

confiture/core/locking.py

@@ -0,0 +1,389 @@
+"""Distributed locking for migration coordination.
+
+Uses PostgreSQL advisory locks to ensure only one migration
+process runs at a time across all application instances.
+
+This is critical for Kubernetes/multi-pod deployments where
+multiple pods may start simultaneously and attempt to run migrations.
+
+PostgreSQL advisory locks are:
+- Session-scoped (auto-release on disconnect)
+- Reentrant (same session can acquire multiple times)
+- Database-scoped (different databases = different locks)
+"""
+
+import contextlib
+import hashlib
+import logging
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import psycopg
+
+logger = logging.getLogger(__name__)
+
+
+class LockMode(Enum):
+    """Lock acquisition modes."""
+
+    BLOCKING = "blocking"  # Wait until lock available
+    NON_BLOCKING = "non_blocking"  # Return immediately if locked
+
+
+@dataclass
+class LockConfig:
+    """Configuration for migration locking.
+
+    Attributes:
+        enabled: Whether locking is enabled (default: True)
+        timeout_ms: Lock acquisition timeout in milliseconds (default: 30000)
+        lock_id: Custom lock ID (auto-generated from database name if None)
+        mode: Lock acquisition mode (blocking or non-blocking)
+
+    Example:
+        >>> config = LockConfig(timeout_ms=60000)  # 1 minute timeout
+        >>> config = LockConfig(enabled=False)  # Disable locking
+        >>> config = LockConfig(mode=LockMode.NON_BLOCKING)  # Fail fast
+    """
+
+    enabled: bool = True
+    timeout_ms: int = 30000  # 30 seconds default
+    lock_id: int | None = None  # Custom lock ID (auto-generated if None)
+    mode: LockMode = field(default=LockMode.BLOCKING)
+
+
+class LockAcquisitionError(Exception):
+    """Raised when lock cannot be acquired.
+
+    Attributes:
+        timeout: True if the error was due to timeout, False otherwise
+    """
+
+    def __init__(self, message: str, timeout: bool = False):
+        super().__init__(message)
+        self.timeout = timeout
+
+
+class MigrationLock:
+    """Manages distributed locks for migration execution.
+
+    Uses PostgreSQL advisory locks which are:
+    - Session-scoped (auto-release on disconnect)
+    - Reentrant (same session can acquire multiple times)
+    - Database-scoped (different databases = different locks)
+
+    Advisory locks use two 32-bit integers: (classid, objid).
+    We use a fixed namespace (classid) and a database-specific objid.
+
+    Example:
+        >>> import psycopg
+        >>> conn = psycopg.connect('postgresql://localhost/mydb')
+        >>> lock = MigrationLock(conn)
+        >>> with lock.acquire():
+        ...     # Run migrations here - guaranteed exclusive access
+        ...     migrator.migrate_up()
+
+        >>> # Non-blocking mode
+        >>> lock = MigrationLock(conn, LockConfig(mode=LockMode.NON_BLOCKING))
+        >>> try:
+        ...     with lock.acquire():
+        ...         migrator.migrate_up()
+        ... except LockAcquisitionError:
+        ...     print("Another migration is running, skipping")
+    """
+
+    # Default lock namespace (first 32 bits of SHA256("confiture_migrations"))
+    DEFAULT_LOCK_NAMESPACE = 1751936052
+
+    def __init__(
+        self,
+        connection: "psycopg.Connection",
+        config: LockConfig | None = None,
+    ):
+        """Initialize migration lock.
+
+        Args:
+            connection: psycopg3 database connection
+            config: Lock configuration (uses defaults if None)
+        """
+        self.connection = connection
+        self.config = config or LockConfig()
+        self._lock_held = False
+        self._lock_id: int | None = None
+
+    def _get_lock_id(self) -> int:
+        """Get or generate the lock ID.
+
+        Returns:
+            Lock ID integer (32-bit positive)
+        """
+        if self._lock_id is not None:
+            return self._lock_id
+
+        if self.config.lock_id is not None:
+            self._lock_id = self.config.lock_id
+        else:
+            self._lock_id = self._generate_lock_id()
+
+        return self._lock_id
+
+    def _generate_lock_id(self) -> int:
+        """Generate deterministic lock ID from database name.
+
+        The lock ID is derived from the database name to ensure
+        each database has its own lock scope.
+
+        Returns:
+            32-bit positive integer lock ID
+        """
+        # Get database name from connection
+        with self.connection.cursor() as cur:
+            cur.execute("SELECT current_database()")
+            result = cur.fetchone()
+            db_name = result[0] if result else "unknown"
+
+        # Hash to 32-bit positive integer
+        hash_bytes = hashlib.sha256(db_name.encode()).digest()
+        return int.from_bytes(hash_bytes[:4], "big") & 0x7FFFFFFF
+
+    @contextmanager
+    def acquire(self) -> Generator[None, None, None]:
+        """Context manager for lock acquisition.
+
+        Acquires the lock on entry and releases it on exit (even if an
+        exception occurs). The lock is also automatically released if
+        the database connection drops.
+
+        Yields:
+            None - lock is held while in context
+
+        Raises:
+            LockAcquisitionError: If lock cannot be acquired
+
+        Example:
+            >>> with lock.acquire():
+            ...     # Exclusive access guaranteed here
+            ...     run_migrations()
+            # Lock automatically released here
+        """
+        if not self.config.enabled:
+            logger.debug("Locking disabled, skipping lock acquisition")
+            yield
+            return
+
+        try:
+            self._acquire_lock()
+            yield
+        finally:
+            self._release_lock()
+
+    def _acquire_lock(self) -> None:
+        """Acquire the advisory lock.
+
+        Raises:
+            LockAcquisitionError: If lock cannot be acquired
+        """
+        lock_id = self._get_lock_id()
+
+        if self.config.mode == LockMode.NON_BLOCKING:
+            self._acquire_non_blocking(lock_id)
+        else:
+            self._acquire_blocking(lock_id)
+
+        self._lock_held = True
+        logger.info(
+            f"Acquired migration lock (namespace={self.DEFAULT_LOCK_NAMESPACE}, id={lock_id})"
+        )
+
+    def _acquire_blocking(self, lock_id: int) -> None:
+        """Acquire lock with timeout.
+
+        Uses SET LOCAL statement_timeout to implement lock timeout.
+        This setting only affects the current transaction.
+
+        Args:
+            lock_id: Lock object ID
+
+        Raises:
+            LockAcquisitionError: If timeout expires
+        """
+        import psycopg
+
+        timeout_sec = self.config.timeout_ms / 1000
+
+        with self.connection.cursor() as cur:
+            # Set statement timeout for lock acquisition
+            # Using string formatting for timeout is safe (integer value)
+            cur.execute(f"SET LOCAL statement_timeout = '{self.config.timeout_ms}ms'")
+
+            try:
+                cur.execute(
+                    "SELECT pg_advisory_lock(%s, %s)",
+                    (self.DEFAULT_LOCK_NAMESPACE, lock_id),
+                )
+                # Reset statement timeout on success
+                cur.execute("SET LOCAL statement_timeout = '0'")
+            except psycopg.errors.QueryCanceled as e:
+                # Rollback the failed transaction to clear the error state
+                with contextlib.suppress(Exception):
+                    self.connection.rollback()
+                raise LockAcquisitionError(
+                    f"Could not acquire migration lock within {timeout_sec}s. "
+                    "Another migration may be running. "
+                    "Use --no-lock to bypass (dangerous in multi-pod environments).",
+                    timeout=True,
+                ) from e
+
+    def _acquire_non_blocking(self, lock_id: int) -> None:
+        """Try to acquire lock without waiting.
+
+        Uses pg_try_advisory_lock which returns immediately with
+        true (acquired) or false (locked by another session).
+
+        Args:
+            lock_id: Lock object ID
+
+        Raises:
+            LockAcquisitionError: If lock is held by another process
+        """
+        with self.connection.cursor() as cur:
+            cur.execute(
+                "SELECT pg_try_advisory_lock(%s, %s)",
+                (self.DEFAULT_LOCK_NAMESPACE, lock_id),
+            )
+            result = cur.fetchone()
+            acquired = result[0] if result else False
+
+            if not acquired:
+                # Get information about who holds the lock
+                holder = self.get_lock_holder()
+                holder_info = ""
+                if holder:
+                    holder_info = (
+                        f" Held by PID {holder['pid']}"
+                        f" ({holder['application'] or 'unknown app'})"
+                        f" since {holder['started_at']}"
+                    )
+
+                raise LockAcquisitionError(
+                    f"Migration lock is held by another process.{holder_info} "
+                    "Try again later or use blocking mode with --lock-timeout.",
+                    timeout=False,
+                )
+
+    def _release_lock(self) -> None:
+        """Release the advisory lock.
+
+        Safe to call even if lock was not acquired (no-op in that case).
+        Logs a warning if release fails but does not raise an exception
+        since the lock will be released when the connection closes anyway.
+        """
+        if not self._lock_held:
+            return
+
+        lock_id = self._get_lock_id()
+
+        try:
+            with self.connection.cursor() as cur:
+                cur.execute(
+                    "SELECT pg_advisory_unlock(%s, %s)",
+                    (self.DEFAULT_LOCK_NAMESPACE, lock_id),
+                )
+                result = cur.fetchone()
+                unlocked = result[0] if result else False
+
+                if unlocked:
+                    logger.info(f"Released migration lock (id={lock_id})")
+                else:
+                    logger.warning(
+                        f"Lock release returned false (id={lock_id}) - lock may not have been held"
+                    )
+
+        except Exception as e:
+            # Don't raise - lock will be released when connection closes
+            logger.warning(f"Error releasing lock (id={lock_id}): {e}")
+        finally:
+            self._lock_held = False
+
+    def is_locked(self) -> bool:
+        """Check if migration lock is currently held (by any process).
+
+        This can be used to check if another migration is running
+        before attempting to acquire the lock.
+
+        Returns:
+            True if lock is held, False otherwise
+        """
+        lock_id = self._get_lock_id()
+
+        with self.connection.cursor() as cur:
+            cur.execute(
+                """
+                SELECT EXISTS (
+                    SELECT 1 FROM pg_locks
+                    WHERE locktype = 'advisory'
+                    AND classid = %s
+                    AND objid = %s
+                )
+            """,
+                (self.DEFAULT_LOCK_NAMESPACE, lock_id),
+            )
+            result = cur.fetchone()
+            return result[0] if result else False
+
+    def get_lock_holder(self) -> dict | None:
+        """Get information about the current lock holder.
+
+        Useful for diagnostics when a lock cannot be acquired.
+
+        Returns:
+            Dictionary with lock holder info, or None if lock not held:
+            - pid: Process ID holding the lock
+            - user: Database username
+            - application: Application name (from connection)
+            - client_addr: Client IP address
+            - started_at: When the session started
+        """
+        lock_id = self._get_lock_id()
+
+        with self.connection.cursor() as cur:
+            cur.execute(
+                """
+                SELECT
+                    l.pid,
+                    a.usename,
+                    a.application_name,
+                    a.client_addr,
+                    a.backend_start
+                FROM pg_locks l
+                JOIN pg_stat_activity a ON l.pid = a.pid
+                WHERE l.locktype = 'advisory'
+                AND l.classid = %s
+                AND l.objid = %s
+            """,
+                (self.DEFAULT_LOCK_NAMESPACE, lock_id),
+            )
+            result = cur.fetchone()
+
+            if result:
+                return {
+                    "pid": result[0],
+                    "user": result[1],
+                    "application": result[2],
+                    "client_addr": str(result[3]) if result[3] else None,
+                    "started_at": result[4],
+                }
+            return None
+
+    @property
+    def lock_held(self) -> bool:
+        """Check if this instance currently holds the lock.
+
+        Returns:
+            True if this instance holds the lock, False otherwise
+        """
+        return self._lock_held

confiture/core/migration_generator.py

@@ -0,0 +1,298 @@
+"""Migration file generator from schema diffs.
+
+This module generates Python migration files from SchemaDiff objects.
+Each migration file contains up() and down() methods with the necessary SQL.
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+from confiture.models.schema import SchemaChange, SchemaDiff
+
+
+class MigrationGenerator:
+    """Generates Python migration files from schema diffs.
+
+    Example:
+        >>> generator = MigrationGenerator(migrations_dir=Path("db/migrations"))
+        >>> diff = SchemaDiff(changes=[...])
+        >>> migration_file = generator.generate(diff, name="add_users_table")
+    """
+
+    def __init__(self, migrations_dir: Path):
+        """Initialize migration generator.
+
+        Args:
+            migrations_dir: Directory where migration files will be created
+        """
+        self.migrations_dir = migrations_dir
+
+    def generate(self, diff: SchemaDiff, name: str) -> Path:
+        """Generate migration file from schema diff.
+
+        Args:
+            diff: Schema diff containing changes
+            name: Name for the migration (snake_case)
+
+        Returns:
+            Path to generated migration file
+
+        Raises:
+            ValueError: If diff has no changes
+        """
+        if not diff.has_changes():
+            raise ValueError("No changes to generate migration from")
+
+        # Get next version number
+        version = self._get_next_version()
+
+        # Generate file path
+        filename = f"{version}_{name}.py"
+        filepath = self.migrations_dir / filename
+
+        # Generate migration code
+        code = self._generate_migration_code(diff, version, name)
+
+        # Write file
+        filepath.write_text(code)
+
+        return filepath
+
+    def _get_next_version(self) -> str:
+        """Get next sequential migration version number.
+
+        Returns:
+            Version string (e.g., "001", "002", etc.)
+        """
+        if not self.migrations_dir.exists():
+            return "001"
+
+        # Find existing migration files
+        migration_files = sorted(self.migrations_dir.glob("*.py"))
+
+        if not migration_files:
+            return "001"
+
+        # Extract version from last file (e.g., "003_name.py" -> 3)
+        last_file = migration_files[-1]
+        last_version_str = last_file.name.split("_")[0]
+
+        try:
+            last_version = int(last_version_str)
+            next_version = last_version + 1
+            return f"{next_version:03d}"
+        except ValueError:
+            # If we can't parse version, start over
+            return "001"
+
+    def _generate_migration_code(self, diff: SchemaDiff, version: str, name: str) -> str:
+        """Generate Python migration code.
+
+        Args:
+            diff: Schema diff containing changes
+            version: Version number
+            name: Migration name
+
+        Returns:
+            Python code as string
+        """
+        class_name = self._to_class_name(name)
+        timestamp = datetime.now().isoformat()
+
+        # Generate up and down statements
+        up_statements = self._generate_up_statements(diff.changes)
+        down_statements = self._generate_down_statements(diff.changes)
+
+        template = '''"""Migration: {name}
+
+Version: {version}
+Generated: {timestamp}
+"""
+
+from confiture.models.migration import Migration
+
+
+class {class_name}(Migration):
+    """Migration: {name}."""
+
+    version = "{version}"
+    name = "{name}"
+
+    def up(self) -> None:
+        """Apply migration."""
+{up_statements}
+
+    def down(self) -> None:
+        """Rollback migration."""
+{down_statements}
+'''
+
+        return template.format(
+            name=name,
+            version=version,
+            class_name=class_name,
+            up_statements=up_statements,
+            down_statements=down_statements,
+            timestamp=timestamp,
+        )
+
+    def _to_class_name(self, snake_case: str) -> str:
+        """Convert snake_case to PascalCase.
+
+        Args:
+            snake_case: String in snake_case format
+
+        Returns:
+            String in PascalCase format
+
+        Example:
+            >>> gen._to_class_name("add_users_table")
+            'AddUsersTable'
+        """
+        words = snake_case.split("_")
+        return "".join(word.capitalize() for word in words)
+
+    def _generate_up_statements(self, changes: list[SchemaChange]) -> str:
+        """Generate SQL statements for up migration.
+
+        Args:
+            changes: List of schema changes
+
+        Returns:
+            Python code with execute() calls
+        """
+        statements = []
+
+        for change in changes:
+            sql = self._change_to_up_sql(change)
+            if sql:
+                statements.append(f'        self.execute("{sql}")')
+
+        return "\n".join(statements) if statements else "        pass  # No operations"
+
+    def _generate_down_statements(self, changes: list[SchemaChange]) -> str:
+        """Generate SQL statements for down migration.
+
+        Args:
+            changes: List of schema changes
+
+        Returns:
+            Python code with execute() calls
+        """
+        statements = []
+
+        # Process changes in reverse order for rollback
+        for change in reversed(changes):
+            sql = self._change_to_down_sql(change)
+            if sql:
+                statements.append(f'        self.execute("{sql}")')
+
+        return "\n".join(statements) if statements else "        pass  # No operations"
+
+    def _change_to_up_sql(self, change: SchemaChange) -> str | None:
+        """Convert schema change to SQL for up migration.
+
+        Args:
+            change: Schema change
+
+        Returns:
+            SQL string or None if not applicable
+        """
+        if change.type == "ADD_TABLE":
+            # We don't have full schema info, so create a placeholder
+            return f"# TODO: ADD_TABLE {change.table}"
+
+        elif change.type == "DROP_TABLE":
+            return f"DROP TABLE {change.table}"
+
+        elif change.type == "RENAME_TABLE":
+            return f"ALTER TABLE {change.old_value} RENAME TO {change.new_value}"
+
+        elif change.type == "ADD_COLUMN":
+            # For ADD_COLUMN, we might have type info in new_value
+            col_def = change.new_value if change.new_value else "TEXT"
+            return f"ALTER TABLE {change.table} ADD COLUMN {change.column} {col_def}"
+
+        elif change.type == "DROP_COLUMN":
+            return f"ALTER TABLE {change.table} DROP COLUMN {change.column}"
+
+        elif change.type == "RENAME_COLUMN":
+            return (
+                f"ALTER TABLE {change.table} RENAME COLUMN {change.old_value} TO {change.new_value}"
+            )
+
+        elif change.type == "CHANGE_COLUMN_TYPE":
+            return (
+                f"ALTER TABLE {change.table} ALTER COLUMN {change.column} TYPE {change.new_value}"
+            )
+
+        elif change.type == "CHANGE_COLUMN_NULLABLE":
+            if change.new_value == "false":
+                return f"ALTER TABLE {change.table} ALTER COLUMN {change.column} SET NOT NULL"
+            else:
+                return f"ALTER TABLE {change.table} ALTER COLUMN {change.column} DROP NOT NULL"
+
+        elif change.type == "CHANGE_COLUMN_DEFAULT":
+            if change.new_value:
+                return f"ALTER TABLE {change.table} ALTER COLUMN {change.column} SET DEFAULT {change.new_value}"
+            else:
+                return f"ALTER TABLE {change.table} ALTER COLUMN {change.column} DROP DEFAULT"
+
+        return None
+
+    def _change_to_down_sql(self, change: SchemaChange) -> str | None:
+        """Convert schema change to SQL for down migration (reverse).
+
+        Args:
+            change: Schema change
+
+        Returns:
+            SQL string or None if not applicable
+        """
+        if change.type == "ADD_TABLE":
+            # Reverse of ADD is DROP
+            return f"DROP TABLE {change.table}"
+
+        elif change.type == "DROP_TABLE":
+            # Can't recreate without schema info
+            return f"# WARNING: Cannot auto-generate down migration for DROP_TABLE {change.table}"
+
+        elif change.type == "RENAME_TABLE":
+            # Reverse the rename
+            return f"ALTER TABLE {change.new_value} RENAME TO {change.old_value}"
+
+        elif change.type == "ADD_COLUMN":
+            # Reverse of ADD is DROP
+            return f"ALTER TABLE {change.table} DROP COLUMN {change.column}"
+
+        elif change.type == "DROP_COLUMN":
+            # Can't recreate without schema info
+            return f"# WARNING: Cannot auto-generate down migration for DROP_COLUMN {change.table}.{change.column}"
+
+        elif change.type == "RENAME_COLUMN":
+            # Reverse the rename
+            return (
+                f"ALTER TABLE {change.table} RENAME COLUMN {change.new_value} TO {change.old_value}"
+            )
+
+        elif change.type == "CHANGE_COLUMN_TYPE":
+            # Reverse the type change
+            return (
+                f"ALTER TABLE {change.table} ALTER COLUMN {change.column} TYPE {change.old_value}"
+            )
+
+        elif change.type == "CHANGE_COLUMN_NULLABLE":
+            # Reverse the nullable change
+            if change.old_value == "false":
+                return f"ALTER TABLE {change.table} ALTER COLUMN {change.column} SET NOT NULL"
+            else:
+                return f"ALTER TABLE {change.table} ALTER COLUMN {change.column} DROP NOT NULL"
+
+        elif change.type == "CHANGE_COLUMN_DEFAULT":
+            # Reverse the default change
+            if change.old_value:
+                return f"ALTER TABLE {change.table} ALTER COLUMN {change.column} SET DEFAULT {change.old_value}"
+            else:
+                return f"ALTER TABLE {change.table} ALTER COLUMN {change.column} DROP DEFAULT"
+
+        return None