# 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密码，并提供完整的数据库操作功能。