Metadata-Version: 2.4
Name: django-sync-db
Version: 0.1.0
Summary: A Django application for database synchronization with multiple database support
Project-URL: Homepage, https://github.com/li2810081/django-sync-db
Project-URL: Documentation, https://github.com/li2810081/django-sync-db#readme
Project-URL: Repository, https://github.com/li2810081/django-sync-db.git
Project-URL: Bug Tracker, https://github.com/li2810081/django-sync-db/issues
Author-email: li2810081 <276069869@qq.com>
Maintainer-email: li2810081 <276069869@qq.com>
License: MIT
License-File: LICENSE
Keywords: async,database,django,migration,synchronization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: celery>=5.5.3
Requires-Dist: django-redis>=5.4.0
Requires-Dist: django>=4.2.0
Requires-Dist: mysqlclient>=2.2.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: pymongo>=4.0.0
Requires-Dist: pymysql>=1.1.2
Requires-Dist: pyodbc>=5.2.0
Requires-Dist: redis>=5.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: django-stubs>=4.2.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-django>=4.5.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: mssql
Requires-Dist: django-mssql-backend>=2.8.1; extra == 'mssql'
Description-Content-Type: text/markdown

# Django数据库同步系统

一个功能完整的Django应用，用于将外部数据库数据同步到本项目。支持多种数据库类型、字段映射、异步任务队列和详细的日志记录。

## 功能特性

### 核心功能
- **多数据库支持**: MySQL、PostgreSQL、MongoDB、SQLite、Microsoft SQL Server (2008+)
- **灵活的字段映射**: 可配置外部字段到本地字段的映射关系
- **SQL筛选**: 支持自定义SQL条件筛选数据
- **异步任务队列**: 基于Celery的可靠任务执行
- **详细日志记录**: 记录每次同步的详细状态和执行信息
- **Admin后台管理**: 完整的Django Admin管理界面
- **Web管理界面**: 现代化的Bootstrap界面

### 高级功能
- **每日任务拆分**: 自动将大时间范围的同步任务拆分为每日任务
- **任务重试机制**: 支持失败任务的自动重试
- **实时进度监控**: 实时显示同步任务进度
- **统计报表**: 提供任务执行统计和成功率分析
- **连接测试**: 支持数据库连接和表映射配置测试

## 系统架构

```
Django同步系统
├── 外部数据库连接层
│   ├── MySQL连接器
│   ├── PostgreSQL连接器
│   ├── MongoDB连接器
│   └── SQLite连接器
├── 数据映射层
│   ├── 字段映射配置
│   ├── SQL条件筛选
│   └── 数据转换
├── 任务调度层
│   ├── Celery任务队列
│   ├── 每日任务拆分
│   └── 重试机制
└── 监控管理层
    ├── Admin后台
    ├── Web界面
    ├── 日志系统
    └── 统计报表
```

## 安装部署

### 1. 环境要求
- Python 3.8+
- Redis (用于Celery消息队列)
- 数据库 (SQLite/MySQL/PostgreSQL)

### 2. 安装依赖
```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
```

### 2.1. MSSQL支持 (可选)
如果需要连接Microsoft SQL Server，请确保安装了ODBC驱动：

**Windows:**
```bash
# 下载并安装 Microsoft ODBC Driver for SQL Server
# https://docs.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server
```

**Linux (Ubuntu/Debian):**
```bash
# 添加微软仓库
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
sudo apt-add-repository "$(curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list)"
sudo apt-get update

# 安装ODBC驱动
sudo apt-get install -y unixodbc-dev
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql17
```

### 3. 配置数据库
编辑 `src/project/settings.py` 文件，配置数据库连接：

```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}
```

### 4. 配置Redis
确保Redis服务运行，并更新settings.py中的Celery配置：

```python
CELERY_BROKER_URL = 'redis://localhost:6379/0'
CELERY_RESULT_BACKEND = 'redis://localhost:6379/0'
```

### 5. 数据库迁移
```bash
cd src
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
```

### 6. 启动服务

#### 启动Django开发服务器
```bash
cd src
python manage.py runserver
```

#### 启动Celery Worker
```bash
cd src
celery -A project worker -l info
```

#### 启动Celery Beat (定时任务)
```bash
cd src
celery -A project beat -l info
```

#### 启动Flower (监控界面，可选)
```bash
cd src
celery -A project flower
```

## 使用指南

### 1. 配置外部数据库
1. 访问Admin后台: http://localhost:8000/admin/
2. 进入"外部数据库"管理页面
3. 添加数据库连接配置：
   - 数据库名称
   - 数据库类型 (MySQL/PostgreSQL/MongoDB/SQLite)
   - 连接信息 (主机、端口、用户名、密码等)

### 2. 创建表映射
1. 进入"表映射"管理页面
2. 创建新的映射配置：
   - 选择外部数据库
   - 输入外部表名
   - 输入本地模型名
   - 配置字段映射 (JSON格式: {"外部字段": "本地字段"})
   - 设置筛选SQL条件 (可选)

### 3. 启动同步任务
#### 方式一: 通过Web界面
1. 访问同步任务页面
2. 点击"启动同步"
3. 设置时间范围
4. 选择是否创建每日任务

#### 方式二: 通过Admin后台
1. 进入表映射管理
2. 选择要同步的表
3. 执行"启动选中表同步"操作

### 4. 监控任务执行
- **仪表板**: 查看总体统计信息
- **任务列表**: 查看所有同步任务状态
- **任务详情**: 查看具体任务的执行日志和进度
- **同步日志**: 查看详细的执行日志

## 配置示例

### 外部数据库配置示例

**MySQL示例:**
```json
{
    "name": "生产数据库",
    "db_type": "mysql",
    "host": "192.168.1.100",
    "port": 3306,
    "database_name": "production",
    "username": "sync_user",
    "password": "password123",
    "extra_params": {
        "charset": "utf8mb4",
        "connect_timeout": 30
    }
}
```

**MSSQL示例:**
```json
{
    "name": "MSSQL数据库",
    "db_type": "mssql",
    "host": "192.168.1.100",
    "port": 1433,
    "database_name": "production",
    "username": "sa",
    "password": "password123",
    "extra_params": {
        "driver": "ODBC Driver 17 for SQL Server",
        "timeout": 30,
        "encrypt": "no",
        "connection_timeout": 30
    }
}
```

**MSSQL 2008特殊配置:**
```json
{
    "name": "MSSQL 2008数据库",
    "db_type": "mssql",
    "host": "192.168.1.100",
    "port": 1433,
    "database_name": "production",
    "username": "sa",
    "password": "password123",
    "extra_params": {
        "driver": "SQL Server Native Client 10.0",
        "timeout": 30,
        "encrypt": "no"
    }
}
```

### 字段映射配置示例
```json
{
    "external_table": "orders",
    "local_model": "Order",
    "field_mapping": {
        "order_id": "id",
        "order_no": "order_number",
        "create_time": "created_at",
        "update_time": "updated_at",
        "customer_name": "customer.name",
        "total_amount": "amount"
    },
    "filter_sql": "status = 'completed' AND create_time >= '2024-01-01'"
}
```

## API接口

### 测试数据库连接
```http
POST /sync/databases/{db_id}/test/
```

### 获取表字段信息
```http
GET /sync/databases/{db_id}/columns/?table_name=table_name
```

### 启动同步任务
```http
POST /sync/tasks/start/
Content-Type: application/json

{
    "mapping_id": 1,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
}
```

### 获取任务状态
```http
GET /sync/api/task/{task_id}/status/
```

### 获取统计信息
```http
GET /sync/api/statistics/
```

## 任务队列管理

### Celery任务类型
1. **test_connection**: 测试数据库连接
2. **start_sync_task**: 启动同步任务
3. **create_daily_sync_tasks**: 创建每日同步任务
4. **execute_daily_sync**: 执行每日同步任务
5. **cleanup_old_logs**: 清理旧日志
6. **retry_failed_daily_tasks**: 重试失败任务

### 定时任务配置
```python
CELERY_BEAT_SCHEDULE = {
    'daily-cleanup': {
        'task': 'django_sync_db.tasks.schedule_daily_cleanup',
        'schedule': 60.0 * 60.0 * 24.0,  # 每天执行一次
    },
    'daily-retry': {
        'task': 'django_sync_db.tasks.schedule_daily_retry',
        'schedule': 60.0 * 60.0 * 2.0,  # 每2小时执行一次
    },
}
```

## 日志管理

### 日志级别
- **INFO**: 一般信息
- **WARNING**: 警告信息
- **ERROR**: 错误信息
- **DEBUG**: 调试信息

### 日志存储
- 数据库存储: 通过SyncLog模型
- 文件存储: 配置在`logs/django_sync_db.log`

## 性能优化

### 建议配置
1. **批量处理**: 默认每批处理1000条记录
2. **并发控制**: Celery worker并发数根据服务器配置调整
3. **内存管理**: 大数据量同步建议分时段执行
4. **索引优化**: 确保外部表查询字段有适当索引

### 监控指标
- 任务执行时间
- 成功率
- 错误率
- 数据处理量

## 故障排除

### 常见问题
1. **连接失败**: 检查网络连接和数据库权限
2. **字段映射错误**: 验证字段名和类型匹配
3. **任务卡住**: 检查Celery worker状态
4. **内存不足**: 调整批量处理大小
5. **MSSQL连接问题**: 
   - 确保安装了正确的ODBC驱动
   - 检查SQL Server Browser服务是否运行
   - 验证防火墙设置（1433端口）
   - 对于MSSQL 2008，使用"SQL Server Native Client 10.0"驱动

### 调试方法
1. 查看Django日志: `logs/django_sync_db.log`
2. 查看Celery日志: 启动时添加`-l debug`
3. 使用Flower监控任务状态
4. 检查数据库连接和权限

## 安全考虑

1. **密码安全**: 数据库密码加密存储
2. **网络访问**: 限制数据库访问IP
3. **权限控制**: 最小权限原则
4. **日志脱敏**: 避免敏感信息记录到日志

## 扩展开发

### 添加新数据库类型
1. 在`services.py`中添加连接逻辑
2. 更新模型中的DB_TYPE_CHOICES
3. 添加相应的查询和字段获取方法

### 自定义任务处理
1. 继承DataSyncService类
2. 重写数据转换方法
3. 添加自定义验证逻辑

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 联系方式

如有问题，请通过以下方式联系：
- 邮箱: 276069869@qq.com
- GitHub: [项目地址]