db_client_toolkit 0.0.1__py3-none-any.whl

db_toolkit/clients/redis.py

@@ -0,0 +1,321 @@
+"""
+Redis数据库客户端
+"""
+
+from typing import Any, Dict, List, Optional, Union
+import logging
+import json
+
+from ..core.base import BaseClient
+from ..exceptions import ConnectionError, QueryError, NotSupportedError
+
+logger = logging.getLogger(__name__)
+
+
+class RedisClient(BaseClient):
+    """Redis数据库客户端实现"""
+    
+    def _validate_config(self) -> None:
+        """验证Redis配置"""
+        super()._validate_config()
+        # Redis的配置比较灵活，不强制要求特定字段
+    
+    def connect(self) -> bool:
+        """连接Redis数据库"""
+        try:
+            import redis
+            
+            self.connection = redis.Redis(
+                host=self.config.get('host', 'localhost'),
+                port=self.config.get('port', 6379),
+                password=self.config.get('password'),
+                db=self.config.get('db', 0),
+                decode_responses=True,
+                **self.config.get('options', {})
+            )
+            
+            # 测试连接
+            self.connection.ping()
+            
+            self._connected = True
+            logger.info(f"Redis连接成功: {self.config.get('host', 'localhost')}:{self.config.get('port', 6379)}")
+            return True
+            
+        except ImportError:
+            raise ConnectionError("未安装redis库，请运行: pip install redis")
+        except Exception as e:
+            self._connected = False
+            logger.error(f"Redis连接失败: {e}")
+            raise ConnectionError(f"Redis连接失败: {e}")
+    
+    def disconnect(self) -> bool:
+        """断开Redis连接"""
+        if self.connection:
+            try:
+                self.connection.close()
+                self._connected = False
+                logger.info("Redis连接已关闭")
+                return True
+            except Exception as e:
+                logger.error(f"关闭Redis连接失败: {e}")
+                return False
+        return True
+    
+    def is_connected(self) -> bool:
+        """检查Redis连接状态"""
+        if not self.connection:
+            return False
+        try:
+            self.connection.ping()
+            return True
+        except Exception:
+            self._connected = False
+            return False
+    
+    def execute(self, query: str, params: Optional[tuple] = None) -> Any:
+        """
+        Redis不支持SQL查询
+        
+        Raises:
+            NotSupportedError: 总是抛出此异常
+        """
+        raise NotSupportedError("Redis不支持SQL查询，请使用专用方法")
+    
+    # ============ 基础键值操作 ============
+    
+    def get(self, key: str) -> Optional[str]:
+        """
+        获取键值
+        
+        Args:
+            key: 键名
+            
+        Returns:
+            Optional[str]: 值，不存在返回None
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            return self.connection.get(key)
+        except Exception as e:
+            logger.error(f"获取键值失败: {e}")
+            raise QueryError(f"获取键值失败: {e}")
+    
+    def set(self, key: str, value: str, ex: Optional[int] = None, 
+            nx: bool = False, xx: bool = False) -> bool:
+        """
+        设置键值
+        
+        Args:
+            key: 键名
+            value: 值
+            ex: 过期时间（秒）
+            nx: 只在键不存在时设置
+            xx: 只在键存在时设置
+            
+        Returns:
+            bool: 是否设置成功
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            return self.connection.set(key, value, ex=ex, nx=nx, xx=xx)
+        except Exception as e:
+            logger.error(f"设置键值失败: {e}")
+            raise QueryError(f"设置键值失败: {e}")
+    
+    def delete_key(self, *keys: str) -> int:
+        """
+        删除键
+        
+        Args:
+            *keys: 要删除的键
+            
+        Returns:
+            int: 删除的键数量
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            return self.connection.delete(*keys)
+        except Exception as e:
+            logger.error(f"删除键失败: {e}")
+            raise QueryError(f"删除键失败: {e}")
+    
+    def exists_key(self, *keys: str) -> int:
+        """
+        检查键是否存在
+        
+        Args:
+            *keys: 要检查的键
+            
+        Returns:
+            int: 存在的键数量
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            return self.connection.exists(*keys)
+        except Exception as e:
+            logger.error(f"检查键存在失败: {e}")
+            raise QueryError(f"检查键存在失败: {e}")
+    
+    # ============ Hash操作 ============
+    
+    def hget(self, name: str, key: str) -> Optional[str]:
+        """获取Hash字段值"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            return self.connection.hget(name, key)
+        except Exception as e:
+            logger.error(f"获取Hash字段失败: {e}")
+            raise QueryError(f"获取Hash字段失败: {e}")
+    
+    def hset(self, name: str, key: str = None, value: str = None, 
+             mapping: Dict[str, Any] = None) -> int:
+        """设置Hash字段"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            if mapping:
+                return self.connection.hset(name, mapping=mapping)
+            else:
+                return self.connection.hset(name, key, value)
+        except Exception as e:
+            logger.error(f"设置Hash字段失败: {e}")
+            raise QueryError(f"设置Hash字段失败: {e}")
+    
+    def hgetall(self, name: str) -> Dict[str, str]:
+        """获取Hash所有字段"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            return self.connection.hgetall(name)
+        except Exception as e:
+            logger.error(f"获取Hash所有字段失败: {e}")
+            raise QueryError(f"获取Hash所有字段失败: {e}")
+    
+    # ============ 实现基类抽象方法（使用Hash存储） ============
+    
+    def insert(self, table: str, data: Dict[str, Any]) -> Any:
+        """
+        使用Hash存储数据
+        
+        Args:
+            table: 表名（用作键前缀）
+            data: 数据，必须包含'id'字段
+            
+        Returns:
+            str: 键名
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        # 获取或生成ID
+        if 'id' in data:
+            record_id = data['id']
+        else:
+            record_id = self.connection.incr(f'{table}:id')
+            data['id'] = str(record_id)
+        
+        key = f"{table}:{record_id}"
+        
+        # 将数据转换为字符串存储
+        str_data = {k: json.dumps(v) if isinstance(v, (dict, list)) else str(v) 
+                    for k, v in data.items()}
+        
+        try:
+            self.hset(key, mapping=str_data)
+            logger.debug(f"插入数据成功，键: {key}")
+            return key
+        except Exception as e:
+            logger.error(f"插入数据失败: {e}")
+            raise QueryError(f"插入数据失败: {e}")
+    
+    def update(self, table: str, data: Dict[str, Any], 
+               condition: Dict[str, Any]) -> int:
+        """更新Hash数据"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        if 'id' not in condition:
+            raise ValueError("Redis更新操作需要提供id条件")
+        
+        key = f"{table}:{condition['id']}"
+        
+        if not self.exists_key(key):
+            return 0
+        
+        # 转换数据
+        str_data = {k: json.dumps(v) if isinstance(v, (dict, list)) else str(v) 
+                    for k, v in data.items()}
+        
+        try:
+            self.hset(key, mapping=str_data)
+            logger.debug(f"更新数据成功，键: {key}")
+            return 1
+        except Exception as e:
+            logger.error(f"更新数据失败: {e}")
+            raise QueryError(f"更新数据失败: {e}")
+    
+    def delete(self, table: str, condition: Dict[str, Any]) -> int:
+        """删除Hash数据"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        if 'id' not in condition:
+            raise ValueError("Redis删除操作需要提供id条件")
+        
+        key = f"{table}:{condition['id']}"
+        
+        try:
+            count = self.delete_key(key)
+            logger.debug(f"删除了 {count} 条数据")
+            return count
+        except Exception as e:
+            logger.error(f"删除数据失败: {e}")
+            raise QueryError(f"删除数据失败: {e}")
+    
+    def select(self, table: str,
+               fields: Optional[List[str]] = None,
+               condition: Optional[Dict[str, Any]] = None,
+               limit: Optional[int] = None,
+               offset: Optional[int] = None,
+               order_by: Optional[List[tuple]] = None) -> List[Dict]:
+        """查询Hash数据"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        # Redis简化实现，只支持通过id查询
+        if not condition or 'id' not in condition:
+            logger.warning("Redis select操作建议提供id条件以提高性能")
+            return []
+        
+        key = f"{table}:{condition['id']}"
+        
+        try:
+            data = self.hgetall(key)
+            if not data:
+                return []
+            
+            # 尝试解析JSON
+            result = {}
+            for k, v in data.items():
+                try:
+                    result[k] = json.loads(v)
+                except (json.JSONDecodeError, ValueError):
+                    result[k] = v
+            
+            return [result]
+            
+        except Exception as e:
+            logger.error(f"查询数据失败: {e}")
+            raise QueryError(f"查询数据失败: {e}")

db_toolkit/clients/sqlite.py

@@ -0,0 +1,152 @@
+"""
+SQLite数据库客户端
+"""
+
+from typing import Any, Dict, List, Optional
+import logging
+import sqlite3
+
+from ..core.sql_base import SQLBaseClient
+from ..exceptions import ConnectionError, QueryError
+
+logger = logging.getLogger(__name__)
+
+
+class SQLiteClient(SQLBaseClient):
+    """SQLite数据库客户端实现"""
+    
+    @property
+    def placeholder(self) -> str:
+        return "?"
+    
+    def _validate_config(self) -> None:
+        """验证SQLite配置"""
+        super()._validate_config()
+        if 'database' not in self.config:
+            raise ValueError("SQLite配置缺少必需字段: database")
+    
+    def connect(self) -> bool:
+        """连接SQLite数据库"""
+        try:
+            database = self.config.get('database', ':memory:')
+            self.connection = sqlite3.connect(database)
+            self.connection.row_factory = sqlite3.Row
+            self._connected = True
+            logger.info(f"SQLite连接成功: {database}")
+            return True
+            
+        except Exception as e:
+            self._connected = False
+            logger.error(f"SQLite连接失败: {e}")
+            raise ConnectionError(f"SQLite连接失败: {e}")
+    
+    def disconnect(self) -> bool:
+        """断开SQLite连接"""
+        if self.connection:
+            try:
+                self.connection.close()
+                self._connected = False
+                logger.info("SQLite连接已关闭")
+                return True
+            except Exception as e:
+                logger.error(f"关闭SQLite连接失败: {e}")
+                return False
+        return True
+    
+    def is_connected(self) -> bool:
+        """检查SQLite连接状态"""
+        if not self.connection:
+            return False
+        try:
+            # 尝试执行一个简单的查询
+            self.connection.execute("SELECT 1")
+            return True
+        except Exception:
+            self._connected = False
+            return False
+    
+    def execute(self, query: str, params: Optional[tuple] = None) -> Any:
+        """执行SQLite查询"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            cursor = self.connection.cursor()
+            cursor.execute(query, params or ())
+            
+            if query.strip().upper().startswith('SELECT'):
+                result = [dict(row) for row in cursor.fetchall()]
+            else:
+                self.connection.commit()
+                result = cursor.rowcount
+            
+            cursor.close()
+            return result
+            
+        except Exception as e:
+            logger.error(f"查询执行失败: {e}")
+            raise QueryError(f"查询执行失败: {e}")
+    
+    def insert(self, table: str, data: Dict[str, Any]) -> Any:
+        """插入数据到SQLite"""
+        query, params = self._build_insert_query(table, data)
+        
+        try:
+            cursor = self.connection.cursor()
+            cursor.execute(query, params)
+            self.connection.commit()
+            last_id = cursor.lastrowid
+            cursor.close()
+            logger.debug(f"插入数据成功，ID: {last_id}")
+            return last_id
+            
+        except Exception as e:
+            logger.error(f"插入数据失败: {e}")
+            raise QueryError(f"插入数据失败: {e}")
+    
+    def update(self, table: str, data: Dict[str, Any], 
+               condition: Dict[str, Any]) -> int:
+        """更新SQLite数据"""
+        query, params = self._build_update_query(table, data, condition)
+        result = self.execute(query, params)
+        logger.debug(f"更新了 {result} 条记录")
+        return result
+    
+    def delete(self, table: str, condition: Dict[str, Any]) -> int:
+        """删除SQLite数据"""
+        query, params = self._build_delete_query(table, condition)
+        result = self.execute(query, params)
+        logger.debug(f"删除了 {result} 条记录")
+        return result
+    
+    def select(self, table: str,
+               fields: Optional[List[str]] = None,
+               condition: Optional[Dict[str, Any]] = None,
+               limit: Optional[int] = None,
+               offset: Optional[int] = None,
+               order_by: Optional[List[tuple]] = None) -> List[Dict]:
+        """查询SQLite数据"""
+        query, params = self._build_select_query(
+            table, fields, condition, limit, offset, order_by
+        )
+        result = self.execute(query, params)
+        logger.debug(f"查询到 {len(result)} 条记录")
+        return result
+    
+    def execute_script(self, script: str) -> None:
+        """
+        执行SQL脚本
+        
+        Args:
+            script: SQL脚本内容
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            self.connection.executescript(script)
+            self.connection.commit()
+            logger.debug("SQL脚本执行成功")
+        except Exception as e:
+            logger.error(f"SQL脚本执行失败: {e}")
+            raise QueryError(f"SQL脚本执行失败: {e}")

db_toolkit/clients/supabase.py

@@ -0,0 +1,230 @@
+"""
+Supabase数据库客户端
+"""
+
+from typing import Any, Dict, List, Optional, Union
+import logging
+
+from ..core.base import BaseClient
+from ..exceptions import ConnectionError, QueryError, NotSupportedError
+
+logger = logging.getLogger(__name__)
+
+
+class SupabaseClient(BaseClient):
+    """Supabase数据库客户端实现"""
+    
+    def _validate_config(self) -> None:
+        """验证Supabase配置"""
+        super()._validate_config()
+        required = ['url', 'key']
+        missing = [key for key in required if key not in self.config]
+        if missing:
+            raise ValueError(f"Supabase配置缺少必需字段: {', '.join(missing)}")
+    
+    def connect(self) -> bool:
+        """连接Supabase"""
+        try:
+            from supabase import create_client, Client
+            
+            url = self.config['url']
+            key = self.config['key']
+            
+            self.connection: Client = create_client(url, key)
+            self._connected = True
+            logger.info(f"Supabase连接成功: {url}")
+            return True
+            
+        except ImportError:
+            raise ConnectionError("未安装supabase库，请运行: pip install supabase")
+        except Exception as e:
+            self._connected = False
+            logger.error(f"Supabase连接失败: {e}")
+            raise ConnectionError(f"Supabase连接失败: {e}")
+    
+    def disconnect(self) -> bool:
+        """断开Supabase连接"""
+        # Supabase客户端不需要显式断开连接
+        self._connected = False
+        logger.info("Supabase会话结束")
+        return True
+    
+    def is_connected(self) -> bool:
+        """检查Supabase连接状态"""
+        # Supabase使用REST API，只要有客户端实例就认为是连接的
+        return self.connection is not None and self._connected
+    
+    def execute(self, query: str, params: Optional[tuple] = None) -> Any:
+        """
+        Supabase不直接支持SQL查询
+        
+        Raises:
+            NotSupportedError: 总是抛出此异常
+        """
+        raise NotSupportedError("Supabase使用REST API，请使用insert/update/delete/select方法")
+    
+    def insert(self, table: str, data: Dict[str, Any]) -> Any:
+        """插入数据到Supabase"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            result = self.connection.table(table).insert(data).execute()
+            logger.debug(f"插入数据成功: {result.data}")
+            return result.data
+            
+        except Exception as e:
+            logger.error(f"插入数据失败: {e}")
+            raise QueryError(f"插入数据失败: {e}")
+    
+    def insert_many(self, table: str, data_list: List[Dict[str, Any]]) -> List[Dict]:
+        """
+        批量插入数据
+        
+        Args:
+            table: 表名
+            data_list: 数据列表
+            
+        Returns:
+            List[Dict]: 插入的数据
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            result = self.connection.table(table).insert(data_list).execute()
+            logger.debug(f"批量插入 {len(result.data)} 条数据")
+            return result.data
+            
+        except Exception as e:
+            logger.error(f"批量插入数据失败: {e}")
+            raise QueryError(f"批量插入数据失败: {e}")
+    
+    def update(self, table: str, data: Dict[str, Any], 
+               condition: Dict[str, Any]) -> int:
+        """更新Supabase数据"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            query = self.connection.table(table).update(data)
+            
+            # 添加条件
+            for key, value in condition.items():
+                query = query.eq(key, value)
+            
+            result = query.execute()
+            count = len(result.data)
+            logger.debug(f"更新了 {count} 条记录")
+            return count
+            
+        except Exception as e:
+            logger.error(f"更新数据失败: {e}")
+            raise QueryError(f"更新数据失败: {e}")
+    
+    def delete(self, table: str, condition: Dict[str, Any]) -> int:
+        """删除Supabase数据"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            query = self.connection.table(table).delete()
+            
+            # 添加条件
+            for key, value in condition.items():
+                query = query.eq(key, value)
+            
+            result = query.execute()
+            count = len(result.data)
+            logger.debug(f"删除了 {count} 条记录")
+            return count
+            
+        except Exception as e:
+            logger.error(f"删除数据失败: {e}")
+            raise QueryError(f"删除数据失败: {e}")
+    
+    def select(self, table: str,
+               fields: Optional[List[str]] = None,
+               condition: Optional[Dict[str, Any]] = None,
+               limit: Optional[int] = None,
+               offset: Optional[int] = None,
+               order_by: Optional[List[tuple]] = None) -> List[Dict]:
+        """查询Supabase数据"""
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            # 构建字段选择
+            fields_str = ','.join(fields) if fields else '*'
+            query = self.connection.table(table).select(fields_str)
+            
+            # 添加条件
+            if condition:
+                for key, value in condition.items():
+                    query = query.eq(key, value)
+            
+            # 排序
+            if order_by:
+                for field, direction in order_by:
+                    desc = direction.upper() == 'DESC'
+                    query = query.order(field, desc=desc)
+            
+            # 分页
+            if offset is not None:
+                query = query.range(offset, offset + (limit or 999999))
+            elif limit is not None:
+                query = query.limit(limit)
+            
+            result = query.execute()
+            logger.debug(f"查询到 {len(result.data)} 条记录")
+            return result.data
+            
+        except Exception as e:
+            logger.error(f"查询数据失败: {e}")
+            raise QueryError(f"查询数据失败: {e}")
+    
+    def upsert(self, table: str, data: Union[Dict[str, Any], List[Dict[str, Any]]]) -> Any:
+        """
+        插入或更新数据（如果存在则更新）
+        
+        Args:
+            table: 表名
+            data: 单条或多条数据
+            
+        Returns:
+            插入或更新的数据
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            result = self.connection.table(table).upsert(data).execute()
+            logger.debug(f"Upsert操作成功: {result.data}")
+            return result.data
+            
+        except Exception as e:
+            logger.error(f"Upsert操作失败: {e}")
+            raise QueryError(f"Upsert操作失败: {e}")
+    
+    def rpc(self, function_name: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        """
+        调用Supabase存储过程
+        
+        Args:
+            function_name: 函数名
+            params: 参数
+            
+        Returns:
+            函数返回结果
+        """
+        if not self.is_connected():
+            raise ConnectionError("数据库未连接")
+        
+        try:
+            result = self.connection.rpc(function_name, params or {}).execute()
+            logger.debug(f"调用RPC函数成功: {function_name}")
+            return result.data
+            
+        except Exception as e:
+            logger.error(f"调用RPC函数失败: {e}")
+            raise QueryError(f"调用RPC函数失败: {e}")