first commit

2026-03-04 12:17:52 +08:00
commit ecb3e1d9b2
42 changed files with 4081 additions and 0 deletions
--- a/SQLSERVER_SETUP_GUIDE.md
+++ b/SQLSERVER_SETUP_GUIDE.md
@@ -0,0 +1,250 @@
+# SQL Server 配置和初始化指南
+
+## 📋 概述
+
+本指南详细说明了SQL Server数据库在ETL系统中的配置、连接和示例数据初始化过程。
+
+## ⚙️ 配置文件
+
+### 1. 环境变量配置 (.env)
+
+```env
+# SQL Server 数据库配置
+SQLSERVER_HOST=192.168.11.200
+SQLSERVER_PORT=1433
+SQLSERVER_USERNAME=sa
+SQLSERVER_PASSWORD=sqlserver@7740
+SQLSERVER_DATABASE=test
+```
+
+### 2. 配置文件 (config.py)
+
+```python
+SQLSERVER_CONFIG = {
+    "host": os.getenv("SQLSERVER_HOST", "localhost"),
+    "port": int(os.getenv("SQLSERVER_PORT", "1433")),
+    "username": os.getenv("SQLSERVER_USERNAME", "sa"),
+    "password": os.getenv("SQLSERVER_PASSWORD", "password"),
+    "database": os.getenv("SQLSERVER_DATABASE", "master")
+}
+```
+
+## 🔧 技术实现
+
+### 1. 连接驱动
+
+- **驱动**: `pymssql` (已在 requirements.txt 中配置)
+- **连接URL格式**: `mssql+pymssql://username:password@host:port/database`
+- **SQLAlchemy引擎**: 支持连接池和自动重连
+- **URL编码**: 自动处理用户名和密码中的特殊字符（如@、#、&等）
+
+### 2. 连接管理 (database_manager.py)
+
+```python
+def _build_connection_url(self, db_type, host, port, username, password, database=None, **kwargs):
+    # URL编码处理特殊字符
+    encoded_username = quote_plus(username)
+    encoded_password = quote_plus(password)
+    
+    if db_type == "sqlserver":
+        db_part = f"/{database}" if database else ""
+        return f"mssql+pymssql://{encoded_username}:{encoded_password}@{host}:{port}{db_part}"
+```
+
+### 3. 特殊字符处理
+
+**问题**: 密码中包含特殊字符（如`@`符号）会导致URL解析错误
+
+**解决方案**: 使用`urllib.parse.quote_plus()`对用户名和密码进行URL编码
+
+**示例**:
+- 原始密码: `sqlserver@7740`
+- 编码后: `sqlserver%407740`
+- 避免了URL解析时将`@`误认为用户名密码分隔符
+
+## 📊 示例数据初始化
+
+### 1. 数据表结构
+
+#### customers 表
+```sql
+CREATE TABLE customers (
+    id INT IDENTITY(1,1) PRIMARY KEY,
+    name NVARCHAR(100) NOT NULL,
+    email NVARCHAR(100),
+    phone NVARCHAR(20),
+    created_at DATETIME DEFAULT GETDATE()
+)
+```
+
+#### orders 表
+```sql
+CREATE TABLE orders (
+    id INT IDENTITY(1,1) PRIMARY KEY,
+    customer_id INT,
+    product_name NVARCHAR(100) NOT NULL,
+    quantity INT DEFAULT 1,
+    price DECIMAL(10,2),
+    order_date DATETIME DEFAULT GETDATE(),
+    FOREIGN KEY (customer_id) REFERENCES customers(id)
+)
+```
+
+### 2. 示例数据
+
+#### customers 数据
+- 张三 (zhang.san@email.com, 13800138001)
+- 李四 (li.si@email.com, 13800138002)
+- 王五 (wang.wu@email.com, 13800138003)
+
+#### orders 数据
+- 笔记本电脑 (客户1, 数量1, 价格5999.99)
+- 无线鼠标 (客户2, 数量2, 价格199.99)
+- 机械键盘 (客户3, 数量1, 价格899.99)
+
+### 3. 初始化方法 (sample_data.py)
+
+```python
+def init_sqlserver_sample_data(self):
+    """初始化SQL Server示例数据"""
+    try:
+        config = DatabaseConfig.get_config("sqlserver")
+        
+        # 创建连接
+        connection_id = self.db_manager.create_connection(
+            db_type="sqlserver",
+            **config
+        )
+        
+        # 创建表和插入数据
+        # ... 详细实现见源码
+        
+        return True
+    except Exception as e:
+        logger.error(f"SQL Server示例数据初始化失败: {str(e)}")
+        return False
+```
+
+## 🚀 使用方法
+
+### 1. 自动初始化
+
+启动API服务时自动初始化:
+
+```bash
+python main.py
+```
+
+### 2. 手动测试连接
+
+使用测试脚本:
+
+```bash
+# URL编码测试
+python test_url_encoding.py
+
+# 完整连接测试
+python test_sqlserver_connection.py
+```
+
+### 3. API调用
+
+```bash
+# 获取连接列表
+curl http://localhost:8000/connections
+
+# 执行查询
+curl -X POST http://localhost:8000/query \
+  -H "Content-Type: application/json" \
+  -d '{"connection_id":"sqlserver_xxx", "query":"SELECT * FROM customers"}'
+```
+
+## 🔍 SQL Server 特性
+
+### 1. 数据类型支持
+- **字符串**: NVARCHAR (支持Unicode)
+- **数字**: INT, DECIMAL, FLOAT
+- **日期**: DATETIME, DATE, TIME
+- **自增**: IDENTITY(1,1)
+
+### 2. 连接特性
+- **端口**: 默认1433
+- **认证**: SQL Server认证和Windows认证
+- **数据库**: 支持多数据库实例
+- **编码**: UTF-8支持
+
+## ⚠️ 注意事项
+
+### 1. 密码特殊字符
+- 密码中包含`@`、`#`、`&`等特殊字符时会自动进行URL编码
+- 无需手动处理，系统会自动转换
+
+### 2. 连接配置
+- 确保SQL Server服务已启动
+- 检查防火墙设置允许1433端口
+- 验证用户名密码正确性
+- 确认目标数据库存在
+
+### 3. 权限要求
+- 用户需要有CREATE TABLE权限
+- 需要有INSERT、SELECT权限
+- 建议使用具有足够权限的数据库用户
+
+## 🛠️ 故障排除
+
+### 1. 连接失败
+
+**错误**: `Unable to connect: Adaptive Server is unavailable or does not exist`
+
+**可能原因**:
+- SQL Server服务未启动
+- 网络连接问题
+- 防火墙阻止连接
+- 主机地址或端口错误
+
+**解决方案**:
+1. 检查SQL Server服务状态
+2. 验证网络连接
+3. 检查防火墙设置
+4. 确认配置信息正确
+
+### 2. 认证失败
+
+**错误**: `Login failed for user`
+
+**解决方案**:
+1. 检查用户名密码
+2. 确认SQL Server认证模式
+3. 验证用户权限
+
+### 3. 数据库不存在
+
+**错误**: `Cannot open database`
+
+**解决方案**:
+1. 创建目标数据库
+2. 检查数据库名称拼写
+3. 验证用户访问权限
+
+## 📁 相关文件
+
+- `config.py` - 数据库配置定义
+- `database_manager.py` - 连接管理和URL构建
+- `sample_data.py` - 示例数据初始化
+- `test_sqlserver_connection.py` - 连接测试脚本
+- `test_url_encoding.py` - URL编码测试脚本
+- `.env` - 环境变量配置
+- `requirements.txt` - 依赖包配置
+
+## 📈 总结
+
+SQL Server已成功集成到数据库ETL系统中，支持:
+
+✅ **完整的连接管理** - 包含连接池和自动重连
+✅ **示例数据初始化** - 自动创建表和插入测试数据
+✅ **特殊字符处理** - 自动URL编码密码中的特殊字符
+✅ **错误处理和日志** - 详细的错误信息和调试日志
+✅ **测试工具** - 多个测试脚本验证功能
+✅ **API接口** - RESTful API支持查询和管理
+
+系统现在可以稳定地处理包含特殊字符的SQL Server密码，并提供完整的数据库操作功能。