fraiseql-confiture 0.3.7__cp311-cp311-macosx_11_0_arm64.whl

confiture/exceptions.py

@@ -0,0 +1,192 @@
+"""Confiture exception hierarchy
+
+All exceptions raised by Confiture inherit from ConfiturError.
+This allows users to catch all Confiture-specific errors with a single except clause.
+"""
+
+
+class ConfiturError(Exception):
+    """Base exception for all Confiture errors
+
+    All Confiture-specific exceptions inherit from this base class.
+    This allows catching all Confiture errors with:
+
+        try:
+            confiture.build()
+        except ConfiturError as e:
+            # Handle any Confiture error
+            pass
+    """
+
+    pass
+
+
+class ConfigurationError(ConfiturError):
+    """Invalid configuration (YAML, environment, database connection)
+
+    Raised when:
+    - Environment YAML file is malformed or missing
+    - Required configuration fields are missing
+    - Database connection string is invalid
+    - Include/exclude directory patterns are invalid
+
+    Example:
+        >>> raise ConfigurationError("Missing database_url in local.yaml")
+    """
+
+    pass
+
+
+class MigrationError(ConfiturError):
+    """Migration execution failure
+
+    Raised when:
+    - Migration file cannot be loaded
+    - Migration up() or down() fails
+    - Migration has already been applied
+    - Migration rollback fails
+
+    Attributes:
+        version: Migration version that failed (e.g., "001")
+        migration_name: Human-readable migration name
+    """
+
+    def __init__(
+        self,
+        message: str,
+        version: str | None = None,
+        migration_name: str | None = None,
+    ):
+        super().__init__(message)
+        self.version = version
+        self.migration_name = migration_name
+
+
+class SchemaError(ConfiturError):
+    """Invalid schema DDL or schema build failure
+
+    Raised when:
+    - SQL syntax error in DDL files
+    - Missing required schema directories
+    - Circular dependencies between schema files
+    - Schema hash computation fails
+
+    Example:
+        >>> raise SchemaError("Syntax error in 10_tables/users.sql at line 15")
+    """
+
+    pass
+
+
+class SyncError(ConfiturError):
+    """Production data sync failure
+
+    Raised when:
+    - Cannot connect to source database
+    - Table does not exist in source or target
+    - Anonymization rule fails
+    - Data copy operation fails
+
+    Example:
+        >>> raise SyncError("Table 'users' not found in source database")
+    """
+
+    pass
+
+
+class DifferError(ConfiturError):
+    """Schema diff detection error
+
+    Raised when:
+    - Cannot parse SQL DDL
+    - Schema comparison fails
+    - Ambiguous schema changes detected
+
+    Example:
+        >>> raise DifferError("Cannot parse CREATE TABLE statement")
+    """
+
+    pass
+
+
+class ValidationError(ConfiturError):
+    """Data or schema validation error
+
+    Raised when:
+    - Row count mismatch after migration
+    - Foreign key constraints violated
+    - Custom validation rules fail
+
+    Example:
+        >>> raise ValidationError("Row count mismatch: expected 10000, got 9999")
+    """
+
+    pass
+
+
+class RollbackError(ConfiturError):
+    """Migration rollback failure
+
+    Raised when:
+    - Cannot rollback migration (irreversible change)
+    - Rollback SQL fails
+    - Database state is inconsistent after rollback
+
+    This is a critical error that may require manual intervention.
+
+    Example:
+        >>> raise RollbackError("Cannot rollback: data already deleted")
+    """
+
+    pass
+
+
+class SQLError(ConfiturError):
+    """SQL execution error with detailed context
+
+    Raised when:
+    - SQL statement fails during migration execution
+    - Provides context about which SQL statement failed
+    - Includes original SQL and error details
+
+    Attributes:
+        sql: The SQL statement that failed
+        params: Query parameters (if any)
+        original_error: The underlying database error
+
+    Example:
+        >>> raise SQLError(
+        ...     "CREATE TABLE users (id INT PRIMARY KEY, name TEXT)",
+        ...     None,
+        ...     psycopg_error
+        ... )
+    """
+
+    def __init__(
+        self,
+        sql: str,
+        params: tuple[str, ...] | None,
+        original_error: Exception,
+    ):
+        self.sql = sql
+        self.params = params
+        self.original_error = original_error
+
+        # Create detailed error message
+        message_parts = ["SQL execution failed"]
+
+        # Add SQL snippet (first 100 chars)
+        sql_preview = sql.strip()[:100]
+        if len(sql.strip()) > 100:
+            sql_preview += "..."
+        message_parts.append(f"SQL: {sql_preview}")
+
+        # Add parameters if present
+        if params:
+            message_parts.append(f"Parameters: {params}")
+
+        # Add original error
+        message_parts.append(f"Error: {original_error}")
+
+        message = " | ".join(message_parts)
+        super().__init__(message)

confiture/models/__init__.py

@@ -0,0 +1,24 @@
+"""Confiture migration models.
+
+This module provides the base classes for creating migrations:
+- Migration: Abstract base class for Python migrations
+- SQLMigration: Convenience class for SQL-only migrations with up_sql/down_sql attributes
+- FileSQLMigration: Migrations loaded from .up.sql/.down.sql file pairs
+"""
+
+from confiture.models.migration import Migration, SQLMigration
+from confiture.models.sql_file_migration import (
+    FileSQLMigration,
+    find_sql_migration_files,
+    get_sql_migration_version,
+)
+
+__all__ = [
+    # Base migration classes
+    "Migration",
+    "SQLMigration",
+    "FileSQLMigration",
+    # SQL file discovery
+    "find_sql_migration_files",
+    "get_sql_migration_version",
+]

confiture/models/lint.py

@@ -0,0 +1,193 @@
+"""Linting models for schema validation.
+
+This module provides data structures for schema linting including:
+- Violation: A single schema quality issue
+- LintSeverity: Severity level of violations
+- LintConfig: Configuration for linting rules
+- LintReport: Aggregated linting results
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class LintSeverity(str, Enum):
+    """Severity levels for linting violations.
+
+    Attributes:
+        ERROR: Blocking issue - must fix before migration
+        WARNING: Should fix but optional
+        INFO: Informational only
+    """
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass
+class Violation:
+    """A single schema quality violation.
+
+    Attributes:
+        rule_name: Name of the rule that detected this violation
+        severity: Severity level (ERROR, WARNING, INFO)
+        message: Human-readable description of the issue
+        location: Where the violation occurred (table name, column, etc.)
+        suggested_fix: Optional suggestion on how to fix it
+    """
+
+    rule_name: str
+    severity: LintSeverity
+    message: str
+    location: str
+    suggested_fix: str | None = None
+
+    def __str__(self) -> str:
+        """Format violation for human consumption."""
+        return f"[{self.severity.upper()}] {self.location}: {self.message}"
+
+    def __repr__(self) -> str:
+        """Return repr for debugging."""
+        return (
+            f"Violation(rule={self.rule_name}, severity={self.severity}, location={self.location})"
+        )
+
+
+@dataclass
+class LintConfig:
+    """Configuration for schema linting.
+
+    Attributes:
+        enabled: Whether linting is enabled
+        rules: Dict mapping rule names to their configs
+        fail_on_error: Exit with error code if violations found
+        fail_on_warning: Exit with error code if warnings found (stricter)
+        exclude_tables: List of table name patterns to exclude from linting
+    """
+
+    enabled: bool = True
+    rules: dict[str, Any] = field(default_factory=dict)
+    fail_on_error: bool = True
+    fail_on_warning: bool = False
+    exclude_tables: list[str] = field(default_factory=list)
+
+    @classmethod
+    def default(cls) -> "LintConfig":
+        """Create LintConfig with sensible defaults for all rules.
+
+        Returns:
+            LintConfig with all 6 rules enabled with default settings
+
+        Example:
+            >>> config = LintConfig.default()
+            >>> config.rules.keys()
+            dict_keys(['naming_convention', 'primary_key', ...])
+        """
+        return cls(
+            enabled=True,
+            fail_on_error=True,
+            fail_on_warning=False,
+            rules={
+                "naming_convention": {
+                    "enabled": True,
+                    "style": "snake_case",
+                },
+                "primary_key": {
+                    "enabled": True,
+                },
+                "documentation": {
+                    "enabled": True,
+                },
+                "multi_tenant": {
+                    "enabled": True,
+                    "identifier": "tenant_id",
+                },
+                "missing_index": {
+                    "enabled": True,
+                },
+                "security": {
+                    "enabled": True,
+                },
+            },
+        )
+
+
+@dataclass
+class LintReport:
+    """Results of a complete linting pass.
+
+    Attributes:
+        violations: List of all violations found
+        schema_name: Name of schema that was linted
+        tables_checked: Total number of tables checked
+        columns_checked: Total number of columns checked
+        errors_count: Number of ERROR level violations
+        warnings_count: Number of WARNING level violations
+        info_count: Number of INFO level violations
+        execution_time_ms: Time taken to lint in milliseconds
+    """
+
+    violations: list[Violation]
+    schema_name: str
+    tables_checked: int
+    columns_checked: int
+    errors_count: int
+    warnings_count: int
+    info_count: int
+    execution_time_ms: int
+
+    @property
+    def has_errors(self) -> bool:
+        """Whether there are any ERROR level violations.
+
+        Returns:
+            True if errors_count > 0, False otherwise
+        """
+        return self.errors_count > 0
+
+    @property
+    def has_warnings(self) -> bool:
+        """Whether there are any WARNING level violations.
+
+        Returns:
+            True if warnings_count > 0, False otherwise
+        """
+        return self.warnings_count > 0
+
+    def violations_by_severity(self) -> dict[LintSeverity, list[Violation]]:
+        """Group violations by their severity level.
+
+        Returns:
+            Dict mapping LintSeverity to list of violations at that level
+
+        Example:
+            >>> report.violations_by_severity()
+            {
+                <LintSeverity.ERROR: 'error'>: [Violation(...), ...],
+                <LintSeverity.WARNING: 'warning'>: [...],
+                <LintSeverity.INFO: 'info'>: [...],
+            }
+        """
+        grouped: dict[LintSeverity, list[Violation]] = {}
+
+        for severity in LintSeverity:
+            grouped[severity] = [v for v in self.violations if v.severity == severity]
+
+        return grouped
+
+    def __str__(self) -> str:
+        """Format report for human consumption.
+
+        Returns:
+            Multi-line string with summary of linting results
+        """
+        tables_with_violations = {v.location.split(".")[0] for v in self.violations}
+        lines = [
+            f"Schema: {self.schema_name}",
+            f"Tables: {self.tables_checked} checked, {len(tables_with_violations)} with violations",
+            f"Violations: {self.errors_count} errors, {self.warnings_count} warnings, {self.info_count} info",
+            f"Time: {self.execution_time_ms}ms",
+        ]
+        return "\n".join(lines)

confiture/models/migration.py

@@ -0,0 +1,265 @@
+"""Migration base class for database migrations."""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+import psycopg
+
+if TYPE_CHECKING:
+    from confiture.core.hooks import Hook
+
+
+class Migration(ABC):
+    """Base class for all database migrations.
+
+    Each migration must:
+    - Define a version (e.g., "001", "002")
+    - Define a name (e.g., "create_users")
+    - Implement up() method for applying the migration
+    - Implement down() method for rolling back the migration
+
+    Alternatively, for simple SQL-only migrations, subclass SQLMigration
+    and define `up_sql` and `down_sql` class attributes instead of methods.
+
+    Migrations can optionally define hooks that execute before/after DDL:
+    - before_validation_hooks: Pre-flight checks before migration
+    - before_ddl_hooks: Data prep before structural changes
+    - after_ddl_hooks: Data backfill after structural changes
+    - after_validation_hooks: Verification after data operations
+    - cleanup_hooks: Final cleanup operations
+    - error_hooks: Error handlers during rollback
+
+    Transaction Control:
+        By default, migrations run inside a transaction with savepoints.
+        Set `transactional = False` for operations that cannot run in
+        a transaction, such as:
+        - CREATE INDEX CONCURRENTLY
+        - DROP INDEX CONCURRENTLY
+        - VACUUM
+        - REINDEX CONCURRENTLY
+
+        WARNING: Non-transactional migrations cannot be automatically
+        rolled back if they fail. Manual cleanup may be required.
+
+    Example:
+        >>> class CreateUsers(Migration):
+        ...     version = "001"
+        ...     name = "create_users"
+        ...
+        ...     def up(self):
+        ...         self.execute('''
+        ...             CREATE TABLE users (
+        ...                 id SERIAL PRIMARY KEY,
+        ...                 username TEXT NOT NULL
+        ...             )
+        ...         ''')
+        ...
+        ...     def down(self):
+        ...         self.execute('DROP TABLE users')
+
+    Example with hooks:
+        >>> class AddAnalyticsTable(Migration):
+        ...     version = "002"
+        ...     name = "add_analytics_table"
+        ...     after_ddl_hooks = [BackfillAnalyticsHook()]
+        ...
+        ...     def up(self):
+        ...         self.execute('CREATE TABLE analytics (...)')
+        ...
+        ...     def down(self):
+        ...         self.execute('DROP TABLE analytics')
+
+    Example non-transactional (CREATE INDEX CONCURRENTLY):
+        >>> class AddSearchIndex(Migration):
+        ...     version = "015"
+        ...     name = "add_search_index"
+        ...     transactional = False  # Required for CONCURRENTLY
+        ...
+        ...     def up(self):
+        ...         self.execute('CREATE INDEX CONCURRENTLY idx_search ON products(name)')
+        ...
+        ...     def down(self):
+        ...         self.execute('DROP INDEX CONCURRENTLY IF EXISTS idx_search')
+
+    Example SQL-only migration (using SQLMigration):
+        >>> class MoveCatalogTables(SQLMigration):
+        ...     version = "003"
+        ...     name = "move_catalog_tables"
+        ...
+        ...     up_sql = "ALTER TABLE tenant.products SET SCHEMA catalog;"
+        ...     down_sql = "ALTER TABLE catalog.products SET SCHEMA tenant;"
+    """
+
+    # Subclasses must define these
+    version: str
+    name: str
+
+    # Configuration attributes
+    transactional: bool = True  # Default: run in transaction with savepoints
+    strict_mode: bool = False  # Default: lenient error handling
+
+    # Hook attributes (optional, default to empty lists)
+    before_validation_hooks: list["Hook"] = []
+    before_ddl_hooks: list["Hook"] = []
+    after_ddl_hooks: list["Hook"] = []
+    after_validation_hooks: list["Hook"] = []
+    cleanup_hooks: list["Hook"] = []
+    error_hooks: list["Hook"] = []
+
+    def __init__(self, connection: psycopg.Connection):
+        """Initialize migration with database connection.
+
+        Args:
+            connection: psycopg3 database connection
+
+        Raises:
+            TypeError: If version or name not defined in subclass
+        """
+        self.connection = connection
+
+        # Ensure subclass defined version and name
+        if not hasattr(self.__class__, "version") or self.__class__.version is None:
+            raise TypeError(f"{self.__class__.__name__} must define a 'version' class attribute")
+        if not hasattr(self.__class__, "name") or self.__class__.name is None:
+            raise TypeError(f"{self.__class__.__name__} must define a 'name' class attribute")
+
+    @abstractmethod
+    def up(self) -> None:
+        """Apply the migration.
+
+        This method must be implemented by subclasses to perform
+        the forward migration (e.g., CREATE TABLE, ALTER TABLE).
+
+        Raises:
+            NotImplementedError: If not implemented by subclass
+        """
+        raise NotImplementedError(f"{self.__class__.__name__}.up() must be implemented")
+
+    @abstractmethod
+    def down(self) -> None:
+        """Rollback the migration.
+
+        This method must be implemented by subclasses to perform
+        the reverse migration (e.g., DROP TABLE, revert ALTER).
+
+        Raises:
+            NotImplementedError: If not implemented by subclass
+        """
+        raise NotImplementedError(f"{self.__class__.__name__}.down() must be implemented")
+
+    def execute(self, sql: str, params: tuple[Any, ...] | None = None) -> None:
+        """Execute a SQL statement.
+
+        In strict mode:
+        - Validates statement success explicitly
+        - May check for PostgreSQL warnings (future enhancement)
+
+        In normal mode:
+        - Only fails on actual errors (default)
+        - Ignores notices and warnings
+
+        Args:
+            sql: SQL statement to execute
+            params: Optional query parameters (for parameterized queries)
+
+        Raises:
+            SQLError: If SQL execution fails, with detailed context
+
+        Example:
+            >>> self.execute("CREATE TABLE users (id INT)")
+            >>> self.execute("INSERT INTO users (name) VALUES (%s)", ("Alice",))
+        """
+        from confiture.exceptions import SQLError
+
+        try:
+            with self.connection.cursor() as cursor:
+                if params:
+                    cursor.execute(sql, params)
+                else:
+                    cursor.execute(sql)
+
+                # In strict mode, we could check for warnings here
+                # For now, this is a placeholder for future enhancement
+                if self.strict_mode:
+                    # TODO: Implement warning detection
+                    # PostgreSQL notices are sent via connection.notices
+                    # or through a notice handler
+                    pass
+
+        except Exception as e:
+            # Wrap the error with SQL context
+            raise SQLError(sql, params, e) from e
+
+
+class SQLMigration(Migration):
+    """Migration that executes SQL from class attributes.
+
+    A convenience class for simple SQL-only migrations that don't need
+    Python logic. Instead of implementing up() and down() methods,
+    define `up_sql` and `down_sql` class attributes.
+
+    This reduces boilerplate for simple schema changes while maintaining
+    full compatibility with the migration system (hooks, transactions, etc.).
+
+    Attributes:
+        up_sql: SQL to execute for the forward migration
+        down_sql: SQL to execute for the rollback
+
+    Example:
+        >>> class MoveCatalogTables(SQLMigration):
+        ...     version = "003"
+        ...     name = "move_catalog_tables"
+        ...
+        ...     up_sql = '''
+        ...         ALTER TABLE tenant.tb_datasupplier SET SCHEMA catalog;
+        ...         ALTER TABLE tenant.tb_product SET SCHEMA catalog;
+        ...     '''
+        ...
+        ...     down_sql = '''
+        ...         ALTER TABLE catalog.tb_datasupplier SET SCHEMA tenant;
+        ...         ALTER TABLE catalog.tb_product SET SCHEMA tenant;
+        ...     '''
+
+    Example with non-transactional mode:
+        >>> class AddConcurrentIndex(SQLMigration):
+        ...     version = "004"
+        ...     name = "add_concurrent_index"
+        ...     transactional = False
+        ...
+        ...     up_sql = "CREATE INDEX CONCURRENTLY idx_name ON users(name);"
+        ...     down_sql = "DROP INDEX CONCURRENTLY IF EXISTS idx_name;"
+
+    Note:
+        - Multi-statement SQL is supported (separate with semicolons)
+        - For complex migrations with conditional logic, use Migration base class
+        - Hooks are fully supported with SQLMigration
+    """
+
+    # Subclasses must define these
+    up_sql: str
+    down_sql: str
+
+    def __init__(self, connection: psycopg.Connection):
+        """Initialize SQL migration.
+
+        Args:
+            connection: psycopg3 database connection
+
+        Raises:
+            TypeError: If version, name, up_sql, or down_sql not defined
+        """
+        super().__init__(connection)
+
+        # Validate SQL attributes are defined
+        if not hasattr(self.__class__, "up_sql") or self.__class__.up_sql is None:
+            raise TypeError(f"{self.__class__.__name__} must define an 'up_sql' class attribute")
+        if not hasattr(self.__class__, "down_sql") or self.__class__.down_sql is None:
+            raise TypeError(f"{self.__class__.__name__} must define a 'down_sql' class attribute")
+
+    def up(self) -> None:
+        """Apply the migration by executing up_sql."""
+        self.execute(self.up_sql)
+
+    def down(self) -> None:
+        """Rollback the migration by executing down_sql."""
+        self.execute(self.down_sql)