project-carrier/replication_service/DATA_SOURCES.md

Управление источниками данных

Обзор

Новая архитектура позволяет управлять источниками данных динамически через REST API без перезагрузки сервиса. Конфигурация хранится в базе данных PostgreSQL, что обеспечивает:

• Динамическое управление: Добавляйте, обновляйте и удаляйте источники во время работы сервиса
• Кеширование подключений: 5-минутный TTL для оптимизации производительности
• Поддержка множественных источников: MSSQL и PostgreSQL одновременно
• Безопасность: Пароли сохраняются в БД (TODO: добавить шифрование)

Структура данных

Таблица data_sources

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

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. Создать источник данных

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"
}

Ответ:

{
  "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. Получить список источников

GET /api/v1/data-sources
GET /api/v1/data-sources?active_only=true  # Только активные

Ответ:

[
  {
    "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

GET /api/v1/data-sources/{source_id}

4. Обновить источник данных

PUT /api/v1/data-sources/{source_id}
Content-Type: application/json

{
  "host": "new-mssql-server.example.com",
  "port": 1433,
  "is_active": true
}

5. Удалить источник (мягкое удаление)

DELETE /api/v1/data-sources/{source_id}

Ответ:

{
  "message": "DataSource 1 deactivated"
}

6. Проверить подключение к источнику

POST /api/v1/data-sources/{source_id}/test

Ответ:

{
  "source_id": 1,
  "connection_ok": true
}

Управление таблицами миграции

1. Создать миграцию таблицы

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"
}

Ответ:

{
  "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. Получить список миграций

GET /api/v1/migration-tables
GET /api/v1/migration-tables?active_only=true  # Только активные

3. Обновить миграцию

PUT /api/v1/migration-tables/{table_id}
Content-Type: application/json

{
  "cron_schedule": "0 3 * * *",  # Изменить время на 3:00 AM
  "source_schema": "dbo"
}

4. Удалить миграцию

DELETE /api/v1/migration-tables/{table_id}

Примеры использования

Пример 1: Добавить MSSQL источник и начать репликацию

# 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 источник

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: Переключиться на другой источник для существующей таблицы

# Обновить миграцию чтобы использовать другой источник
curl -X PUT http://localhost:8000/api/v1/migration-tables/1 \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": 2  # Переключиться на источник ID 2
  }'

Пример 4: Получить статус здоровья сервиса

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 для оптимизации

Мониторинг

Статус репликации

GET /api/v1/replication-jobs
GET /api/v1/replication-jobs/{job_id}

Статус планировщика

GET /api/v1/health

Миграция из старой системы

Если вы используете старую систему с environment variables:

1. Создайте источники через API:

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) новые миграции не могут его использовать
• Существующие миграции продолжат работать но будут ошибаться если источник неактивен