Выбрать ветку (тег)
Найти файл
Клонировать
README.md

Chyo - CLI-приложение для управления миграциями ClickHouse

Chyo предоставляет простой и надёжный способ управления SQL-миграциями базы данных ClickHouse с поддержкой одиночного сервера и кластера.

Концепция

Простые миграции для clickhouse, вдохновленные yoyo-migrations (PostgreSQL)

Возможности

  • 🚀 Простая инициализация проекта одной командой
  • 📝 Создание SQL и Python миграций
  • ⬆️ Применение миграций с отслеживанием состояния
  • ⬇️ Откат миграций с поддержкой down-секций
  • 📊 Мониторинг состояния миграций
  • 🌐 Поддержка кластера ClickHouse с автоматической генерацией Distributed таблиц
  • 🔒 Безопасное хранение секретов в переменных окружения
  • 📋 Поддержка CI/CD с JSON выводом и кодами завершения

Требования

  • Python 3.9+
  • ClickHouse 21.8+

Установка из исходников

git clone https://hub.mos.ru/albatros.tan/chyo.git
cd chyo
pip install -e ".[dev]"

Быстрый старт

1. Инициализация проекта

chyo init

Эта команда создаст:

  • chyo.toml - конфигурационный файл
  • migrations/ - директория для миграций
  • Служебную базу данных chyo_migrations

2. Проверка подключения

chyo check

3. Создание миграции

chyo new "create users table"

Будет создан файл миграции 0001_create_users_table.sql с шаблоном:

-- migrate: up
CREATE TABLE users (
    id UInt64,
    name String
) ENGINE = MergeTree()
ORDER BY id;

-- migrate: down
DROP TABLE users;

4. Применение миграций

chyo apply

5. Проверка статуса

chyo status

Конфигурация

Файл конфигурации (chyo.toml)

[database]
host = "localhost"
port = 9000
user = "default"
password = ""
database = "default"

[chyo_db]
database = "chyo_migrations"

[migrations]
dir = "migrations"

[cluster]
name = ""  # Оставьте пустым для одиночного сервера

Переменные окружения

Переменные окружения имеют приоритет над значениями в chyo.toml:

export CLICK_HOST=localhost
export CLICK_PORT=9000
export CLICK_USER=default
export CLICK_PASSWORD=secret
export CLICK_DATABASE=default
export CHYO_DATABASE=chyo_migrations
export MIGRATIONS_DIR=migrations
export CLUSTER_NAME=my_cluster

Команды

chyo init

Инициализирует проект Chyo.

chyo init

chyo check

Проверяет конфигурацию и подключение к ClickHouse.

chyo check

chyo new <description>

Создаёт новую миграцию.

chyo new "create users table"
chyo new "add email column" --no-open  # Не открывать редактор

chyo apply

Применяет новые миграции.

chyo apply
chyo apply --dry-run  # Симуляция без выполнения
chyo apply --target 0005  # Применить до миграции 0005
chyo apply --fake  # Пометить как применённые без выполнения

chyo rollback

Откатывает последнюю миграцию.

chyo rollback
chyo rollback --target 0003  # Откатить до миграции 0003
chyo rollback --yes  # Пропустить подтверждение
chyo rollback --dry-run  # Симуляция без выполнения

chyo status

Показывает статус всех миграций.

chyo status
chyo status --output json  # Вывод в формате JSON
chyo status --output table  # Табличный формат

chyo history

Показывает историю операций.

chyo history
chyo history --since 2024-01-01  # С даты
chyo history --limit 10  # Последние 10 записей

Поддержка кластера

Для работы с кластером ClickHouse укажите имя кластера в конфигурации:

[cluster]
name = "my_cluster"

Chyo автоматически:

  • Добавит ON CLUSTER my_cluster к DDL запросам
  • Создаст локальные таблицы с движком ReplicatedMergeTree
  • Сгенерирует Distributed таблицы для локальных таблиц

CI/CD

Для использования в CI/CD:

# Установите переменные окружения
export CLICK_HOST=$CLICKHOUSE_HOST
export CLICK_PASSWORD=$CLICKHOUSE_PASSWORD

# Примените миграции
chyo apply --output json

# Проверьте код завершения
if [ $? -eq 0 ]; then
    echo "Migrations applied successfully"
else
    echo "Migration failed"
    exit 1
fi

Тестирование

# Запуск всех тестов
pytest

# Запуск с покрытием
pytest --cov=chyo --cov-report=html

# Запуск только unit тестов
pytest -m unit

# Запуск только интеграционных тестов
pytest -m integration

Разработка

Установка зависимостей для разработки

pip install -e ".[dev]"

Настройка pre-commit hooks

pre-commit install

Запуск линтинга

black chyo tests
flake8 chyo tests
mypy chyo

Документация

Архитектура

Chyo следует принципам SOLID и использует следующие паттерны:

  • Strategy Pattern: Абстрактный ClickHouseBackend с реализациями SingleServerBackend и ClusterBackend
  • Factory Pattern: BackendFactory для создания backend на основе конфигурации
  • Lazy Loading: Содержимое миграций загружается только при необходимости через генераторы

Безопасность

  • Пароли маскируются в логах
  • Секреты хранятся в переменных окружения
  • Предупреждения о небезопасных подключениях (без пароля не на localhost)
  • Параметризованные SQL запросы для защиты от инъекций

Производительность

  • Ленивая загрузка содержимого миграций для оптимизации памяти
  • Поддержка 1000+ миграций
  • Время применения миграций <5 секунд

Лицензия

MIT License - см. файл LICENSE

Поддержка

По вопросам и предложениям создавайте issues на MosHub.