velocity-python 0.0.131__py3-none-any.whl → 0.0.134__py3-none-any.whl

velocity/db/servers/base/sql.py

@@ -0,0 +1,503 @@
+"""
+Abstract base class for SQL dialect implementations.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Tuple, Union
+from collections.abc import Mapping, Sequence
+
+
+class BaseSQLDialect(ABC):
+    """
+    Abstract base class that defines the interface all database SQL dialects must implement.
+    
+    This class ensures consistency across all database implementations and makes it clear
+    what methods each database dialect needs to provide.
+    """
+
+    # Database server identifier - must be set by subclasses
+    server: str = ""
+    
+    # Column metadata identifiers - database specific
+    type_column_identifier: str = ""
+    is_nullable: str = ""
+    
+    # Default schema name for this database
+    default_schema: str = ""
+    
+    # Error code classifications - must be set by subclasses
+    ApplicationErrorCodes: List[str] = []
+    DatabaseMissingErrorCodes: List[str] = []
+    TableMissingErrorCodes: List[str] = []
+    ColumnMissingErrorCodes: List[str] = []
+    ForeignKeyMissingErrorCodes: List[str] = []
+    ConnectionErrorCodes: List[str] = []
+    DuplicateKeyErrorCodes: List[str] = []
+    RetryTransactionCodes: List[str] = []
+    TruncationErrorCodes: List[str] = []
+    LockTimeoutErrorCodes: List[str] = []
+    DatabaseObjectExistsErrorCodes: List[str] = []
+    DataIntegrityErrorCodes: List[str] = []
+
+    @classmethod
+    @abstractmethod
+    def get_error(cls, e: Exception) -> Optional[str]:
+        """
+        Extract error information from database exception.
+        
+        Args:
+            e: Database exception
+            
+        Returns:
+            Error code or message, or None if not applicable
+        """
+        pass
+
+    # Core CRUD Operations
+    @classmethod
+    @abstractmethod
+    def select(
+        cls,
+        tx: Any,
+        columns: Optional[Union[str, List[str]]] = None,
+        table: Optional[str] = None,
+        where: Optional[Union[str, Dict, List]] = None,
+        orderby: Optional[Union[str, List, Dict]] = None,
+        groupby: Optional[Union[str, List]] = None,
+        having: Optional[Union[str, Dict, List]] = None,
+        start: Optional[int] = None,
+        qty: Optional[int] = None,
+        lock: Optional[bool] = None,
+        skip_locked: Optional[bool] = None,
+    ) -> Tuple[str, List[Any]]:
+        """
+        Generate a SELECT statement.
+        
+        Returns:
+            Tuple of (sql_string, parameters)
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def insert(cls, table: str, data: Dict[str, Any]) -> Tuple[str, List[Any]]:
+        """
+        Generate an INSERT statement.
+        
+        Args:
+            table: Table name
+            data: Dictionary of column names to values
+            
+        Returns:
+            Tuple of (sql_string, parameters)
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def update(
+        cls, 
+        tx: Any, 
+        table: str, 
+        data: Dict[str, Any], 
+        where: Optional[Union[str, Dict, List]] = None, 
+        pk: Optional[Dict[str, Any]] = None, 
+        excluded: bool = False
+    ) -> Tuple[str, List[Any]]:
+        """
+        Generate an UPDATE statement.
+        
+        Args:
+            tx: Database transaction
+            table: Table name
+            data: Dictionary of columns to update
+            where: WHERE clause conditions
+            pk: Primary key conditions to merge with where
+            excluded: If True, creates EXCLUDED.col expressions for upserts
+            
+        Returns:
+            Tuple of (sql_string, parameters)
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def delete(cls, tx: Any, table: str, where: Union[str, Dict, List]) -> Tuple[str, List[Any]]:
+        """
+        Generate a DELETE statement.
+        
+        Args:
+            tx: Database transaction
+            table: Table name
+            where: WHERE clause conditions
+            
+        Returns:
+            Tuple of (sql_string, parameters)
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def merge(
+        cls,
+        tx: Any,
+        table: str,
+        data: Dict[str, Any],
+        pk: Dict[str, Any],
+        on_conflict_do_nothing: bool,
+        on_conflict_update: bool
+    ) -> Tuple[str, List[Any]]:
+        """
+        Generate an UPSERT/MERGE statement.
+        
+        Args:
+            tx: Database transaction
+            table: Table name
+            data: Data to insert/update
+            pk: Primary key columns
+            on_conflict_do_nothing: If True, ignore conflicts
+            on_conflict_update: If True, update on conflicts
+            
+        Returns:
+            Tuple of (sql_string, parameters)
+        """
+        pass
+
+    # Database Metadata Operations
+    @classmethod
+    @abstractmethod
+    def version(cls) -> str:
+        """Get database version query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def timestamp(cls) -> str:
+        """Get current timestamp query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def user(cls) -> str:
+        """Get current user query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def databases(cls) -> str:
+        """Get list of databases query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def schemas(cls) -> str:
+        """Get list of schemas query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def current_schema(cls) -> str:
+        """Get current schema query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def current_database(cls) -> str:
+        """Get current database query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def tables(cls, system: bool = False) -> str:
+        """
+        Get list of tables query.
+        
+        Args:
+            system: Include system tables
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def views(cls, system: bool = False) -> str:
+        """
+        Get list of views query.
+        
+        Args:
+            system: Include system views
+        """
+        pass
+
+    # Database Structure Operations
+    @classmethod
+    @abstractmethod
+    def create_database(cls, name: str) -> str:
+        """Generate CREATE DATABASE statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def drop_database(cls, name: str) -> str:
+        """Generate DROP DATABASE statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def create_table(cls, name: str, columns: Dict[str, Any] = None, drop: bool = False) -> str:
+        """
+        Generate CREATE TABLE statement.
+        
+        Args:
+            name: Table name
+            columns: Column definitions
+            drop: Drop table if exists first
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def drop_table(cls, name: str) -> str:
+        """Generate DROP TABLE statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def truncate(cls, table: str) -> str:
+        """Generate TRUNCATE statement."""
+        pass
+
+    # Column Operations
+    @classmethod
+    @abstractmethod
+    def columns(cls, name: str) -> str:
+        """Get table columns query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def column_info(cls, table: str, name: str) -> str:
+        """Get column information query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def drop_column(cls, table: str, name: str, cascade: bool = True) -> str:
+        """Generate DROP COLUMN statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def alter_add(cls, table: str, columns: Dict[str, Any], null_allowed: bool = True) -> str:
+        """Generate ALTER TABLE ADD COLUMN statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def alter_drop(cls, table: str, columns: List[str]) -> str:
+        """Generate ALTER TABLE DROP COLUMN statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def alter_column_by_type(cls, table: str, column: str, value: str, nullable: bool = True) -> str:
+        """Generate ALTER COLUMN statement by type."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def alter_column_by_sql(cls, table: str, column: str, value: str) -> str:
+        """Generate ALTER COLUMN statement by SQL."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def rename_column(cls, table: str, orig: str, new: str) -> str:
+        """Generate RENAME COLUMN statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def rename_table(cls, table: str, new: str) -> str:
+        """Generate RENAME TABLE statement."""
+        pass
+
+    # Key Operations
+    @classmethod
+    @abstractmethod
+    def primary_keys(cls, table: str) -> str:
+        """Get primary key columns query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def foreign_key_info(
+        cls, 
+        table: Optional[str] = None, 
+        column: Optional[str] = None, 
+        schema: Optional[str] = None
+    ) -> str:
+        """Get foreign key information query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def create_foreign_key(
+        cls,
+        table: str,
+        columns: List[str],
+        key_to_table: str,
+        key_to_columns: List[str],
+        name: Optional[str] = None,
+        schema: Optional[str] = None,
+    ) -> str:
+        """Generate CREATE FOREIGN KEY statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def drop_foreign_key(
+        cls,
+        table: str,
+        columns: List[str],
+        key_to_table: Optional[str] = None,
+        key_to_columns: Optional[List[str]] = None,
+        name: Optional[str] = None,
+        schema: Optional[str] = None,
+    ) -> str:
+        """Generate DROP FOREIGN KEY statement."""
+        pass
+
+    # Index Operations
+    @classmethod
+    @abstractmethod
+    def create_index(
+        cls,
+        tx: Any,
+        table: Optional[str] = None,
+        columns: Optional[List[str]] = None,
+        unique: bool = False,
+        direction: Optional[str] = None,
+        where: Optional[str] = None,
+        name: Optional[str] = None,
+        schema: Optional[str] = None,
+        trigram: Optional[bool] = None,
+        lower: Optional[bool] = None,
+    ) -> str:
+        """Generate CREATE INDEX statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def drop_index(
+        cls,
+        table: Optional[str] = None,
+        columns: Optional[List[str]] = None,
+        name: Optional[str] = None,
+        schema: Optional[str] = None,
+        trigram: Optional[bool] = None,
+    ) -> str:
+        """Generate DROP INDEX statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def indexes(cls, table: str) -> str:
+        """Get table indexes query."""
+        pass
+
+    # Transaction Operations
+    @classmethod
+    @abstractmethod
+    def create_savepoint(cls, sp: str) -> str:
+        """Generate SAVEPOINT statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def release_savepoint(cls, sp: str) -> str:
+        """Generate RELEASE SAVEPOINT statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def rollback_savepoint(cls, sp: str) -> str:
+        """Generate ROLLBACK TO SAVEPOINT statement."""
+        pass
+
+    # View Operations
+    @classmethod
+    @abstractmethod
+    def create_view(cls, name: str, query: str, temp: bool = False, silent: bool = True) -> str:
+        """Generate CREATE VIEW statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def drop_view(cls, name: str, silent: bool = True) -> str:
+        """Generate DROP VIEW statement."""
+        pass
+
+    # Sequence/Identity Operations
+    @classmethod
+    @abstractmethod
+    def last_id(cls, table: str) -> str:
+        """Get last inserted ID query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def current_id(cls, table: str) -> str:
+        """Get current sequence value query."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def set_id(cls, table: str, start: int) -> str:
+        """Generate set sequence value statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def set_sequence(cls, table: str, next_value: int) -> str:
+        """Generate set sequence next value statement."""
+        pass
+
+    # Utility Operations
+    @classmethod
+    @abstractmethod
+    def massage_data(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Massage data before insert/update operations.
+        Database-specific data transformations.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def alter_trigger(cls, table: str, state: str = "ENABLE", name: str = "USER") -> str:
+        """Generate ALTER TRIGGER statement."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def missing(
+        cls,
+        tx: Any,
+        table: str,
+        list_values: List[Any],
+        column: str = "SYS_ID",
+        where: Optional[Union[str, Dict, List]] = None,
+    ) -> Tuple[str, List[Any]]:
+        """
+        Generate query to find missing values from a list.
+        
+        Args:
+            tx: Database transaction
+            table: Table name
+            list_values: List of values to check
+            column: Column to check against
+            where: Additional WHERE conditions
+            
+        Returns:
+            Tuple of (sql_string, parameters)
+        """
+        pass

velocity/db/servers/base/types.py

@@ -0,0 +1,135 @@
+"""
+Abstract base class for database type mapping implementations.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Type, Union
+import datetime
+import decimal
+
+
+class BaseTypes(ABC):
+    """
+    Abstract base class that defines the interface for database type mappings.
+    
+    Each database implementation should provide concrete implementations of these
+    type mapping methods to handle conversion between Python types and SQL types.
+    """
+
+    # Basic SQL type constants - should be overridden by subclasses
+    TEXT: str = "TEXT"
+    INTEGER: str = "INTEGER"  
+    NUMERIC: str = "NUMERIC"
+    BOOLEAN: str = "BOOLEAN"
+    DATE: str = "DATE"
+    TIME: str = "TIME"
+    DATETIME: str = "DATETIME"
+    TIMESTAMP: str = "TIMESTAMP"
+    BINARY: str = "BINARY"
+    BIGINT: str = "BIGINT"
+    SMALLINT: str = "SMALLINT"
+
+    @classmethod
+    @abstractmethod
+    def get_type(cls, v: Any) -> str:
+        """
+        Returns a suitable SQL type string for a Python value/object.
+        
+        This method should handle conversion of Python types to appropriate
+        SQL column types for table creation and schema operations.
+        
+        Args:
+            v: Python value or type to convert
+            
+        Returns:
+            SQL type string appropriate for this database
+            
+        Examples:
+            get_type(str) -> "TEXT"
+            get_type("hello") -> "TEXT"
+            get_type(int) -> "INTEGER" 
+            get_type(123) -> "INTEGER"
+            get_type(datetime.datetime.now()) -> "TIMESTAMP"
+        """
+        pass
+
+    @classmethod
+    @abstractmethod  
+    def get_conv(cls, v: Any) -> str:
+        """
+        Returns a base SQL type for expression usage (e.g. CAST operations).
+        
+        This is typically used for CAST expressions and should return
+        the fundamental SQL type without precision/scale specifiers.
+        
+        Args:
+            v: Python value or type to convert
+            
+        Returns:
+            Base SQL type string for casting
+            
+        Examples:
+            get_conv(decimal.Decimal("123.45")) -> "NUMERIC"
+            get_conv(datetime.datetime.now()) -> "TIMESTAMP"
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def py_type(cls, sql_type: str) -> Type:
+        """
+        Returns the Python type that corresponds to an SQL type string.
+        
+        This method handles the reverse mapping from SQL types back to
+        Python types, typically used when reading schema information.
+        
+        Args:
+            sql_type: SQL type string from database schema
+            
+        Returns:
+            Corresponding Python type
+            
+        Examples:
+            py_type("INTEGER") -> int
+            py_type("TEXT") -> str
+            py_type("TIMESTAMP") -> datetime.datetime
+            
+        Raises:
+            Exception: If the SQL type is not recognized
+        """
+        pass
+
+    @classmethod
+    def _handle_special_values(cls, v: Any) -> tuple[bool, str]:
+        """
+        Helper method to handle special value prefixes like @@CURRENT_TIMESTAMP.
+        
+        Args:
+            v: Value to check
+            
+        Returns:
+            Tuple of (is_special, processed_value)
+        """
+        if isinstance(v, str) and v.startswith("@@"):
+            return True, v[2:] or cls.TEXT
+        return False, ""
+
+    @classmethod
+    def _get_basic_type_mapping(cls) -> dict[Type, str]:
+        """
+        Returns basic Python type to SQL type mappings.
+        Subclasses can override this to customize mappings.
+        
+        Returns:
+            Dictionary mapping Python types to SQL types
+        """
+        return {
+            str: cls.TEXT,
+            int: cls.INTEGER,
+            float: cls.NUMERIC,
+            bool: cls.BOOLEAN,
+            datetime.datetime: cls.DATETIME,
+            datetime.date: cls.DATE,
+            datetime.time: cls.TIME,
+            decimal.Decimal: cls.NUMERIC,
+            bytes: cls.BINARY,
+        }

velocity/db/servers/mysql/__init__.py

@@ -0,0 +1,73 @@
+import os
+from ..base.initializer import BaseInitializer
+from velocity.db.core import engine
+from .sql import SQL
+
+
+class MySQLInitializer(BaseInitializer):
+    """MySQL database initializer."""
+
+    @staticmethod
+    def initialize(config=None, schema_locked=False, **kwargs):
+        """
+        Initialize MySQL engine with mysql.connector driver.
+        
+        Args:
+            config: Configuration dictionary
+            schema_locked: Boolean to lock schema modifications
+            **kwargs: Additional configuration parameters
+            
+        Returns:
+            Configured Engine instance
+        """
+        try:
+            import mysql.connector
+        except ImportError:
+            raise ImportError(
+                "MySQL connector not available. Install with: pip install mysql-connector-python"
+            )
+        
+        # Base configuration from environment (if available)
+        base_config = {
+            "database": os.environ.get("DBDatabase"),
+            "host": os.environ.get("DBHost"),
+            "port": os.environ.get("DBPort"),
+            "user": os.environ.get("DBUser"),
+            "password": os.environ.get("DBPassword"),
+        }
+        
+        # Remove None values
+        base_config = {k: v for k, v in base_config.items() if v is not None}
+        
+        # Set MySQL-specific defaults
+        mysql_defaults = {
+            "host": "localhost",
+            "port": 3306,
+            "charset": "utf8mb4",
+            "autocommit": False,
+        }
+        
+        # Merge configurations: defaults < env < config < kwargs
+        final_config = mysql_defaults.copy()
+        final_config.update(base_config)
+        final_config = MySQLInitializer._merge_config(final_config, config, **kwargs)
+        
+        # Validate required configuration
+        required_keys = ["database", "host", "user"]
+        MySQLInitializer._validate_required_config(final_config, required_keys)
+        
+        # Check for environment variable override for schema locking
+        if os.environ.get("VELOCITY_SCHEMA_LOCKED", "").lower() in ('true', '1', 'yes'):
+            schema_locked = True
+        
+        return engine.Engine(mysql.connector, final_config, SQL, schema_locked=schema_locked)
+
+
+# Maintain backward compatibility
+def initialize(config=None, schema_locked=False, **kwargs):
+    """Backward compatible initialization function."""
+    # Check for environment variable override for schema locking
+    if os.environ.get("VELOCITY_SCHEMA_LOCKED", "").lower() in ('true', '1', 'yes'):
+        schema_locked = True
+        
+    return MySQLInitializer.initialize(config, schema_locked, **kwargs)