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