"""
数据库连接抽象基类

定义数据库连接的通用接口
"""

from abc import ABC, abstractmethod
from typing import List, Dict, Any, Optional


class BaseDatabaseConnection(ABC):
    """数据库连接抽象基类"""

    def __init__(self, config: Optional[Dict[str, Any]] = None):
        """
        初始化数据库连接

        Args:
            config: 数据库配置字典
        """
        self.config = config or {}
        self.connection = None

    @abstractmethod
    def connect(self):
        """
        建立数据库连接

        Returns:
            数据库连接对象
        """
        pass

    @abstractmethod
    def disconnect(self):
        """关闭数据库连接"""
        pass

    @abstractmethod
    def execute_query(self, sql: str, params: Optional[tuple] = None) -> List[Dict[str, Any]]:
        """
        执行查询语句并返回结果

        Args:
            sql: SQL 查询语句
            params: 查询参数（可选）

        Returns:
            List[Dict[str, Any]]: 查询结果列表，每个元素为一行数据的字典
        """
        pass

    @abstractmethod
    def execute_update(self, sql: str, params: Optional[tuple] = None) -> int:
        """
        执行更新/插入/删除语句

        Args:
            sql: SQL 语句
            params: 参数（可选）

        Returns:
            int: 受影响的行数
        """
        pass

    def __enter__(self):
        """支持 with 语句的上下文管理器入口"""
        self.connect()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        """支持 with 语句的上下文管理器出口"""
        self.disconnect()

    @abstractmethod
    def get_placeholder(self) -> str:
        """
        获取参数占位符

        Returns:
            参数占位符字符串（SQL Server: "?" 或 MySQL: "%s"）
        """
        pass