dtSpark 1.0.4__py3-none-any.whl

dtSpark/database/backends.py

@@ -0,0 +1,329 @@
+"""
+Database backend abstraction for multi-database support.
+
+Supports:
+- SQLite (default, local file-based)
+- MySQL/MariaDB (remote database server)
+- PostgreSQL (remote database server)
+- Microsoft SQL Server (remote database server)
+
+
+"""
+
+import logging
+import sqlite3
+import os
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any, Union
+from dataclasses import dataclass
+
+from dtPyAppFramework.paths import ApplicationPaths
+
+@dataclass
+class DatabaseCredentials:
+    """Database connection credentials."""
+    host: Optional[str] = None
+    port: Optional[int] = None
+    database: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+    ssl: bool = False
+    driver: Optional[str] = None  # For MSSQL
+    path: Optional[str] = None  # For SQLite
+
+
+class DatabaseBackend(ABC):
+    """Abstract base class for database backends."""
+
+    def __init__(self, credentials: DatabaseCredentials):
+        """
+        Initialise database backend.
+
+        Args:
+            credentials: Database connection credentials
+        """
+        self.credentials = credentials
+        self.connection = None
+
+    @abstractmethod
+    def connect(self):
+        """
+        Establish database connection.
+
+        Returns:
+            Database connection object
+        """
+        pass
+
+    @abstractmethod
+    def get_placeholder(self) -> str:
+        """
+        Get SQL parameter placeholder for this database.
+
+        Returns:
+            Placeholder string (?, %s, etc.)
+        """
+        pass
+
+    @abstractmethod
+    def get_autoincrement_syntax(self) -> str:
+        """
+        Get auto-increment syntax for this database.
+
+        Returns:
+            Auto-increment SQL syntax
+        """
+        pass
+
+    @abstractmethod
+    def supports_returning(self) -> bool:
+        """
+        Check if database supports RETURNING clause.
+
+        Returns:
+            True if RETURNING is supported
+        """
+        pass
+
+    def close(self):
+        """Close database connection."""
+        if self.connection:
+            self.connection.close()
+            self.connection = None
+
+    def test_connection(self) -> bool:
+        """
+        Test database connection.
+
+        Returns:
+            True if connection successful
+        """
+        try:
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute("SELECT 1")
+            cursor.close()
+            return True
+        except Exception as e:
+            logging.error(f"Database connection test failed: {e}")
+            return False
+
+
+class SQLiteBackend(DatabaseBackend):
+    """SQLite database backend (local file-based)."""
+
+    def connect(self):
+        """Establish SQLite connection."""
+        if self.connection is None:
+            self.connection = sqlite3.connect(
+                os.path.join(ApplicationPaths().usr_data_root_path, "conversations.db"),
+                check_same_thread=False
+            )
+            self.connection.row_factory = sqlite3.Row
+        return self.connection
+
+    def get_placeholder(self) -> str:
+        return "?"
+
+    def get_autoincrement_syntax(self) -> str:
+        return "AUTOINCREMENT"
+
+    def supports_returning(self) -> bool:
+        return False  # SQLite < 3.35 doesn't support RETURNING
+
+
+class MySQLBackend(DatabaseBackend):
+    """MySQL/MariaDB database backend."""
+
+    def connect(self):
+        """Establish MySQL connection."""
+        try:
+            import mysql.connector
+        except ImportError:
+            raise ImportError(
+                "mysql-connector-python is required for MySQL support. "
+                "Install it with: pip install mysql-connector-python"
+            )
+
+        if self.connection is None:
+            connection_params = {
+                'host': self.credentials.host,
+                'port': self.credentials.port or 3306,
+                'database': self.credentials.database,
+                'user': self.credentials.username,
+                'password': self.credentials.password,
+                'autocommit': False
+            }
+
+            if self.credentials.ssl:
+                connection_params['ssl_disabled'] = False
+
+            self.connection = mysql.connector.connect(**connection_params)
+
+        return self.connection
+
+    def get_placeholder(self) -> str:
+        return "%s"
+
+    def get_autoincrement_syntax(self) -> str:
+        return "AUTO_INCREMENT"
+
+    def supports_returning(self) -> bool:
+        return False  # MySQL doesn't support RETURNING
+
+
+class PostgreSQLBackend(DatabaseBackend):
+    """PostgreSQL database backend."""
+
+    def connect(self):
+        """Establish PostgreSQL connection."""
+        try:
+            import psycopg2
+            import psycopg2.extras
+        except ImportError:
+            raise ImportError(
+                "psycopg2 is required for PostgreSQL support. "
+                "Install it with: pip install psycopg2-binary"
+            )
+
+        if self.connection is None:
+            connection_params = {
+                'host': self.credentials.host,
+                'port': self.credentials.port or 5432,
+                'database': self.credentials.database,
+                'user': self.credentials.username,
+                'password': self.credentials.password
+            }
+
+            if self.credentials.ssl:
+                connection_params['sslmode'] = 'require'
+
+            self.connection = psycopg2.connect(**connection_params)
+            self.connection.autocommit = False
+
+        return self.connection
+
+    def get_placeholder(self) -> str:
+        return "%s"
+
+    def get_autoincrement_syntax(self) -> str:
+        return "SERIAL"
+
+    def supports_returning(self) -> bool:
+        return True
+
+
+class MSSQLBackend(DatabaseBackend):
+    """Microsoft SQL Server database backend."""
+
+    def connect(self):
+        """Establish MSSQL connection."""
+        try:
+            import pyodbc
+        except ImportError:
+            raise ImportError(
+                "pyodbc is required for Microsoft SQL Server support. "
+                "Install it with: pip install pyodbc"
+            )
+
+        if self.connection is None:
+            driver = self.credentials.driver or "ODBC Driver 17 for SQL Server"
+
+            connection_string = (
+                f"DRIVER={{{driver}}};"
+                f"SERVER={self.credentials.host};"
+                f"DATABASE={self.credentials.database};"
+                f"UID={self.credentials.username};"
+                f"PWD={self.credentials.password};"
+            )
+
+            if self.credentials.port:
+                connection_string = connection_string.replace(
+                    f"SERVER={self.credentials.host};",
+                    f"SERVER={self.credentials.host},{self.credentials.port};"
+                )
+
+            if self.credentials.ssl:
+                connection_string += "Encrypt=yes;TrustServerCertificate=no;"
+
+            self.connection = pyodbc.connect(connection_string)
+            self.connection.autocommit = False
+
+        return self.connection
+
+    def get_placeholder(self) -> str:
+        return "?"
+
+    def get_autoincrement_syntax(self) -> str:
+        return "IDENTITY"
+
+    def supports_returning(self) -> bool:
+        return False  # MSSQL uses OUTPUT clause instead
+
+
+def create_backend(db_type: str, credentials: DatabaseCredentials) -> DatabaseBackend:
+    """
+    Factory function to create appropriate database backend.
+
+    Args:
+        db_type: Database type (sqlite, mysql, mariadb, postgresql, mssql)
+        credentials: Database connection credentials
+
+    Returns:
+        Appropriate DatabaseBackend instance
+
+    Raises:
+        ValueError: If database type is not supported
+    """
+    db_type_lower = db_type.lower()
+
+    if db_type_lower == 'sqlite':
+        return SQLiteBackend(credentials)
+    elif db_type_lower in ('mysql', 'mariadb'):
+        return MySQLBackend(credentials)
+    elif db_type_lower == 'postgresql':
+        return PostgreSQLBackend(credentials)
+    elif db_type_lower in ('mssql', 'sqlserver', 'mssqlserver'):
+        return MSSQLBackend(credentials)
+    else:
+        raise ValueError(
+            f"Unsupported database type: {db_type}. "
+            f"Supported types: sqlite, mysql, mariadb, postgresql, mssql"
+        )
+
+
+def validate_credentials(db_type: str, credentials: DatabaseCredentials) -> tuple[bool, Optional[str]]:
+    """
+    Validate database credentials for given database type.
+
+    Args:
+        db_type: Database type
+        credentials: Database credentials
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    db_type_lower = db_type.lower()
+
+    if db_type_lower == 'sqlite':
+        if not credentials.path:
+            return False, "SQLite database path is required"
+        return True, None
+
+    # Remote databases require connection details
+    required_fields = ['host', 'database', 'username', 'password']
+
+    missing = []
+    if not credentials.host:
+        missing.append('host')
+    if not credentials.database:
+        missing.append('database')
+    if not credentials.username:
+        missing.append('username')
+    if not credentials.password:
+        missing.append('password')
+
+    if missing:
+        return False, f"Missing required credentials: {', '.join(missing)}"
+
+    return True, None

dtSpark/database/connection.py

@@ -0,0 +1,122 @@
+"""
+Database connection management module.
+
+This module handles:
+- Multi-database backend support (SQLite, MySQL, PostgreSQL, MSSQL)
+- Database connection setup
+- Connection lifecycle management
+- Directory management for database files
+
+
+"""
+
+import sqlite3
+import logging
+import threading
+from pathlib import Path
+from typing import Optional, Any
+
+from .backends import (
+    DatabaseBackend,
+    DatabaseCredentials,
+    create_backend,
+    validate_credentials
+)
+
+
+class DatabaseConnection:
+    """Manages database connection lifecycle with multi-backend support."""
+
+    def __init__(self, db_type: str = 'sqlite', credentials: Optional[DatabaseCredentials] = None,
+                 db_path: Optional[str] = None):
+        """
+        Initialise the database connection.
+
+        Args:
+            db_type: Database type (sqlite, mysql, mariadb, postgresql, mssql)
+            credentials: Database connection credentials
+            db_path: Path to SQLite database file (for backward compatibility)
+        """
+        self.db_type = db_type.lower()
+        self._lock = threading.RLock()  # Reentrant lock for thread-safe operations
+
+        # Handle backward compatibility with old SQLite-only constructor
+        if credentials is None and db_path:
+            credentials = DatabaseCredentials(path=db_path)
+            self.db_type = 'sqlite'
+
+        if credentials is None:
+            raise ValueError("Database credentials are required")
+
+        # Validate credentials
+        is_valid, error_msg = validate_credentials(self.db_type, credentials)
+        if not is_valid:
+            raise ValueError(f"Invalid database credentials: {error_msg}")
+
+        # Create appropriate backend
+        self.backend = create_backend(self.db_type, credentials)
+
+        # For SQLite, ensure directory exists
+        if self.db_type == 'sqlite':
+            self._ensure_database_directory(credentials.path)
+
+        # Establish connection
+        self.conn = self.backend.connect()
+
+        # Configure connection based on backend
+        self._configure_connection()
+
+        logging.info(f"Database connection established: type={self.db_type}")
+
+    def _ensure_database_directory(self, db_path: str):
+        """
+        Ensure the directory for the database file exists (SQLite only).
+
+        Args:
+            db_path: Path to database file
+        """
+        db_dir = Path(db_path).parent
+        db_dir.mkdir(parents=True, exist_ok=True)
+
+    def _configure_connection(self):
+        """Configure connection based on database backend."""
+        if self.db_type == 'sqlite':
+            # Enable WAL (Write-Ahead Logging) mode for better concurrency
+            cursor = self.conn.execute("PRAGMA journal_mode=WAL")
+            journal_mode = cursor.fetchone()[0]
+            cursor.close()
+            logging.info(f"SQLite journal mode: {journal_mode}")
+
+    def get_connection(self) -> Any:
+        """
+        Get the database connection.
+
+        Returns:
+            Database connection object
+        """
+        return self.conn
+
+    def get_backend(self) -> DatabaseBackend:
+        """
+        Get the database backend.
+
+        Returns:
+            DatabaseBackend instance
+        """
+        return self.backend
+
+    def close(self):
+        """Close the database connection."""
+        if self.conn:
+            self.backend.close()
+            self.conn = None
+            logging.info(f"Database connection closed: type={self.db_type}")
+
+    def test_connection(self) -> bool:
+        """
+        Test database connection.
+
+        Returns:
+            True if connection is working
+        """
+        return self.backend.test_connection()