368 lines
11 KiB
Markdown
368 lines
11 KiB
Markdown
# Управление источниками данных
|
||
|
||
## Обзор
|
||
|
||
Новая архитектура позволяет управлять источниками данных динамически через 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) новые миграции не могут его использовать
|
||
- Существующие миграции продолжат работать но будут ошибаться если источник неактивен
|