first commit
This commit is contained in:
brusnitsyn
367
replication_service/DATA_SOURCES.md
Normal file
367
replication_service/DATA_SOURCES.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# Управление источниками данных
|
||||
|
||||
## Обзор
|
||||
|
||||
Новая архитектура позволяет управлять источниками данных динамически через REST API **без перезагрузки сервиса**. Конфигурация хранится в базе данных PostgreSQL, что обеспечивает:
|
||||
|
||||
- **Динамическое управление**: Добавляйте, обновляйте и удаляйте источники во время работы сервиса
|
||||
- **Кеширование подключений**: 5-минутный TTL для оптимизации производительности
|
||||
- **Поддержка множественных источников**: MSSQL и PostgreSQL одновременно
|
||||
- **Безопасность**: Пароли сохраняются в БД (TODO: добавить шифрование)
|
||||
|
||||
## Структура данных
|
||||
|
||||
### Таблица `data_sources`
|
||||
|
||||
```sql
|
||||
data_sources:
|
||||
- id (int, PK) -- Уникальный ID источника
|
||||
- name (string, UNIQUE) -- Имя источника для идентификации
|
||||
- source_type (enum) -- mssql | pgsql
|
||||
- host (string) -- Хост/IP адрес
|
||||
- port (int) -- Порт подключения
|
||||
- database (string) -- Имя базы данных
|
||||
- username (string) -- Пользователь БД
|
||||
- password (string) -- Пароль БД (TODO: шифровать)
|
||||
- default_schema (string) -- Схема по умолчанию (dbo для MSSQL, public для PostgreSQL)
|
||||
- is_active (bool) -- Активен ли источник (False = мягкое удаление)
|
||||
- description (string) -- Описание источника
|
||||
- created_at (datetime) -- Время создания
|
||||
- updated_at (datetime) -- Время последнего изменения
|
||||
```
|
||||
|
||||
### Таблица `migration_tables`
|
||||
|
||||
```sql
|
||||
migration_tables:
|
||||
- id (int, PK)
|
||||
- table_name (string) -- Имя таблицы для репликации
|
||||
- source_id (int, FK) -- Связь на data_sources.id
|
||||
- source_schema (string) -- Явная схема (если NULL, используется default_schema из DataSource)
|
||||
- target_schema (string) -- Целевая схема в PostgreSQL
|
||||
- cron_schedule (string) -- Cron выражение для расписания
|
||||
- is_active (bool) -- Активна ли миграция
|
||||
- created_at (datetime)
|
||||
- updated_at (datetime)
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Управление источниками данных
|
||||
|
||||
#### 1. Создать источник данных
|
||||
```bash
|
||||
POST /api/v1/data-sources
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "MSSQL Production",
|
||||
"source_type": "mssql",
|
||||
"host": "mssql-server.example.com",
|
||||
"port": 1433,
|
||||
"database": "MyDatabase",
|
||||
"username": "sa",
|
||||
"password": "StrongPassword!",
|
||||
"default_schema": "dbo",
|
||||
"description": "Production MSSQL server"
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "MSSQL Production",
|
||||
"source_type": "mssql",
|
||||
"host": "mssql-server.example.com",
|
||||
"port": 1433,
|
||||
"database": "MyDatabase",
|
||||
"default_schema": "dbo",
|
||||
"is_active": true,
|
||||
"description": "Production MSSQL server",
|
||||
"created_at": "2024-01-15T10:30:00",
|
||||
"updated_at": "2024-01-15T10:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Получить список источников
|
||||
```bash
|
||||
GET /api/v1/data-sources
|
||||
GET /api/v1/data-sources?active_only=true # Только активные
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "MSSQL Production",
|
||||
"source_type": "mssql",
|
||||
"host": "mssql-server.example.com",
|
||||
"port": 1433,
|
||||
"database": "MyDatabase",
|
||||
"default_schema": "dbo",
|
||||
"is_active": true,
|
||||
"description": "Production MSSQL server",
|
||||
"created_at": "2024-01-15T10:30:00",
|
||||
"updated_at": "2024-01-15T10:30:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 3. Получить источник по ID
|
||||
```bash
|
||||
GET /api/v1/data-sources/{source_id}
|
||||
```
|
||||
|
||||
#### 4. Обновить источник данных
|
||||
```bash
|
||||
PUT /api/v1/data-sources/{source_id}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"host": "new-mssql-server.example.com",
|
||||
"port": 1433,
|
||||
"is_active": true
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. Удалить источник (мягкое удаление)
|
||||
```bash
|
||||
DELETE /api/v1/data-sources/{source_id}
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"message": "DataSource 1 deactivated"
|
||||
}
|
||||
```
|
||||
|
||||
#### 6. Проверить подключение к источнику
|
||||
```bash
|
||||
POST /api/v1/data-sources/{source_id}/test
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"source_id": 1,
|
||||
"connection_ok": true
|
||||
}
|
||||
```
|
||||
|
||||
### Управление таблицами миграции
|
||||
|
||||
#### 1. Создать миграцию таблицы
|
||||
```bash
|
||||
POST /api/v1/migration-tables
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"table_name": "Customers",
|
||||
"source_id": 1,
|
||||
"cron_schedule": "0 2 * * *", # Каждый день в 2:00 AM
|
||||
"source_schema": "dbo", # (опционально, если NULL, используется default_schema из DataSource)
|
||||
"target_schema": "public"
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"table_name": "Customers",
|
||||
"source_id": 1,
|
||||
"source_schema": "dbo",
|
||||
"target_schema": "public",
|
||||
"cron_schedule": "0 2 * * *",
|
||||
"is_active": true,
|
||||
"created_at": "2024-01-15T10:35:00",
|
||||
"updated_at": "2024-01-15T10:35:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Получить список миграций
|
||||
```bash
|
||||
GET /api/v1/migration-tables
|
||||
GET /api/v1/migration-tables?active_only=true # Только активные
|
||||
```
|
||||
|
||||
#### 3. Обновить миграцию
|
||||
```bash
|
||||
PUT /api/v1/migration-tables/{table_id}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"cron_schedule": "0 3 * * *", # Изменить время на 3:00 AM
|
||||
"source_schema": "dbo"
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Удалить миграцию
|
||||
```bash
|
||||
DELETE /api/v1/migration-tables/{table_id}
|
||||
```
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### Пример 1: Добавить MSSQL источник и начать репликацию
|
||||
|
||||
```bash
|
||||
# 1. Создать источник MSSQL
|
||||
curl -X POST http://localhost:8000/api/v1/data-sources \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "MSSQL Production",
|
||||
"source_type": "mssql",
|
||||
"host": "sqlserver.example.com",
|
||||
"port": 1433,
|
||||
"database": "SalesDB",
|
||||
"username": "sa",
|
||||
"password": "Password123!",
|
||||
"default_schema": "dbo"
|
||||
}'
|
||||
|
||||
# 2. Проверить подключение
|
||||
curl -X POST http://localhost:8000/api/v1/data-sources/1/test
|
||||
|
||||
# 3. Создать миграцию для таблицы Orders
|
||||
curl -X POST http://localhost:8000/api/v1/migration-tables \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"table_name": "Orders",
|
||||
"source_id": 1,
|
||||
"cron_schedule": "0 2 * * *",
|
||||
"source_schema": "dbo",
|
||||
"target_schema": "public"
|
||||
}'
|
||||
```
|
||||
|
||||
### Пример 2: Добавить PostgreSQL источник
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/data-sources \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Postgres Analytics DB",
|
||||
"source_type": "pgsql",
|
||||
"host": "analytics.example.com",
|
||||
"port": 5432,
|
||||
"database": "analytics",
|
||||
"username": "analyst",
|
||||
"password": "AnalystPass456!",
|
||||
"default_schema": "public",
|
||||
"description": "Analytics database for weekly reports"
|
||||
}'
|
||||
```
|
||||
|
||||
### Пример 3: Переключиться на другой источник для существующей таблицы
|
||||
|
||||
```bash
|
||||
# Обновить миграцию чтобы использовать другой источник
|
||||
curl -X PUT http://localhost:8000/api/v1/migration-tables/1 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"source_id": 2 # Переключиться на источник ID 2
|
||||
}'
|
||||
```
|
||||
|
||||
### Пример 4: Получить статус здоровья сервиса
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/api/v1/health
|
||||
|
||||
# Ответ:
|
||||
{
|
||||
"status": "healthy",
|
||||
"target_postgres": true,
|
||||
"data_sources": {
|
||||
"MSSQL Production (mssql)": true,
|
||||
"Postgres Analytics DB (pgsql)": true
|
||||
},
|
||||
"timestamp": "2024-01-15T10:45:00"
|
||||
}
|
||||
```
|
||||
|
||||
## Cron выражения
|
||||
|
||||
Формат: `minute hour day month weekday`
|
||||
|
||||
Примеры:
|
||||
- `0 2 * * *` - Каждый день в 2:00 AM
|
||||
- `0 */4 * * *` - Каждые 4 часа
|
||||
- `0 0 * * MON` - Каждый понедельник в полночь
|
||||
- `*/15 * * * *` - Каждые 15 минут
|
||||
- `0 8-17 * * MON-FRI` - Каждый час от 8 до 17 в рабочие дни
|
||||
|
||||
## Безопасность
|
||||
|
||||
### Текущее состояние
|
||||
⚠️ **Пароли хранятся в открытом виде в PostgreSQL**
|
||||
|
||||
### Рекомендации для production
|
||||
1. Добавить шифрование паролей (например, используя `cryptography` library)
|
||||
2. Использовать переменные окружения для admin credentials
|
||||
3. Ограничить доступ к API endpoints (HTTPS, authentication)
|
||||
4. Аудитировать изменения в data_sources
|
||||
5. Использовать connection pooling для оптимизации
|
||||
|
||||
## Мониторинг
|
||||
|
||||
### Статус репликации
|
||||
```bash
|
||||
GET /api/v1/replication-jobs
|
||||
GET /api/v1/replication-jobs/{job_id}
|
||||
```
|
||||
|
||||
### Статус планировщика
|
||||
```bash
|
||||
GET /api/v1/health
|
||||
```
|
||||
|
||||
## Миграция из старой системы
|
||||
|
||||
Если вы используете старую систему с environment variables:
|
||||
|
||||
1. Создайте источники через API:
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/data-sources \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "MSSQL from ENV",
|
||||
"source_type": "mssql",
|
||||
"host": "'$MSSQL_SERVER'",
|
||||
"port": '$MSSQL_PORT',
|
||||
"database": "'$MSSQL_DATABASE'",
|
||||
"username": "'$MSSQL_USERNAME'",
|
||||
"password": "'$MSSQL_PASSWORD'",
|
||||
"default_schema": "dbo"
|
||||
}'
|
||||
```
|
||||
|
||||
2. Обновите migration_tables с source_id вместо source_type
|
||||
3. Удалите переменные окружения из .env
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "DataSource not found"
|
||||
- Проверьте что ID источника существует: `GET /api/v1/data-sources`
|
||||
- Убедитесь что источник активен: `is_active: true`
|
||||
|
||||
### "Connection failed"
|
||||
- Проверьте подключение: `POST /api/v1/data-sources/{id}/test`
|
||||
- Проверьте учетные данные (хост, порт, пароль)
|
||||
- Убедитесь что firewall позволяет подключение
|
||||
|
||||
### "Replication not starting"
|
||||
- Проверьте что migration table активна: `is_active: true`
|
||||
- Проверьте cron выражение синтаксис
|
||||
- Проверьте логи: `docker logs replication-service`
|
||||
- Убедитесь что таблица существует в источнике
|
||||
|
||||
## Примечания
|
||||
|
||||
- При обновлении источника (хост, порт, credentials) кеш подключений автоматически очищается
|
||||
- При удалении источника (is_active=false) новые миграции не могут его использовать
|
||||
- Существующие миграции продолжат работать но будут ошибаться если источник неактивен
|
||||
Reference in New Issue
Block a user