Add insert_tools project

Author: Кирилл Горелов

insert_tools/.gitignore

@@ -0,0 +1,41 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.pyc
+*.so
+
+# Logs
+*.log
+insert.log
+
+# Virtual environment
+.env
+.env.*
+.venv/
+venv/
+
+# Test & coverage
+htmlcov/
+.tox/
+.coverage
+coverage.xml
+pytest_cache/
+
+# Packaging
+dist/
+build/
+*.egg-info/
+
+# Docker volumes / data
+clickhouse_data/
+
+# IDE/editor configs
+*.idea/
+.vscode/
+*.swp
+
+# System files
+.DS_Store
+Thumbs.db

insert_tools/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

insert_tools/Makefile

@@ -0,0 +1,28 @@
+.PHONY: up down logs test format lint typecheck check
+
+# Docker
+up:
+	docker-compose up -d
+
+down:
+	docker-compose down
+
+logs:
+	docker-compose logs -f clickhouse
+
+# Тесты
+test:
+	pytest -v --tb=short tests/
+
+# Линтеры и типизация
+lint:
+	flake8 clickhouse_insert
+
+format:
+	black clickhouse_insert
+
+typecheck:
+	mypy clickhouse_insert
+
+# Быстрая проверка всего
+check: lint typecheck test

insert_tools/README.md

@@ -0,0 +1,97 @@
+# 🚀 Insert Tools
+
+**Проблема:**
+
+Вы сталкивались с проблемами при вставке данных в базы данных? Постоянные ошибки соответствия схем, неправильные типы данных, потеря времени на ручные проверки и риск случайного повреждения данных — всё это знакомо каждому, кто регулярно работает с большими ETL-процессами и базами данных.
+
+**Решение:**
+
+Insert Tools — это мощный и гибко настраиваемый инструмент, специально разработанный для безопасной и быстрой вставки данных в различные базы данных, начиная с ClickHouse. Он автоматически проверяет соответствие схем по названиям столбцов, выполняет приведение типов данных и позволяет проводить предварительную проверку в режиме dry-run, полностью исключая ошибки перед реальной вставкой данных. Особенно полезен инструмент для крупных ETL-процессов, где важно, чтобы обновления схемы целевой таблицы не приводили к падениям системы.
+
+## 🔥 Почему это стоит попробовать:
+
+- ✅ **Безопасность данных:** Автоматическая проверка схемы данных по именам столбцов перед вставкой.
+- ⚙️ **Автоприведение типов:** Легко преобразует данные к нужному типу без вашего вмешательства.
+- 🚧 **Dry-run режим:** Тестируйте вставку без рисков.
+- 🐳 **Docker-ready:** Простое развертывание и интеграционные тесты в Docker.
+- 🔧 **Гибкая настройка:** Полностью контролируемый процесс вставки под ваши задачи.
+- 🔥 **Экономия времени:** Забудьте о ручных проверках и ускорьте ваш рабочий процесс.
+
+## 🎯 Ключевые возможности:
+
+- 🖥️ Удобный CLI и Python API.
+- 🛡️ Поддержка строгого режима (strict mode) для полного контроля.
+- 📌 Детализированные логи и расширенный вывод для диагностики.
+- 🔄 Поддержка интеграции с CI/CD процессами.
+
+## 📦 Быстрая установка:
+
+```bash
+pip install insert-tools
+```
+
+или для разработки:
+
+```bash
+pip install -e .[dev]
+```
+
+## 🚀 Запуск и примеры:
+
+Использование через CLI:
+
+```bash
+insert-tools \
+  --host localhost \
+  --port 8123 \
+  --user default \
+  --password admin123 \
+  --database default \
+  --target_table my_table \
+  --select_sql "SELECT * FROM source_table" \
+  --allow_type_cast \
+  --strict \
+  --dry-run \
+  --verbose
+```
+
+Использование через Python:
+
+```python
+from insert_tools.runner import InsertConfig, run_insert
+
+config = InsertConfig(
+    host="localhost",
+    database="default",
+    target_table="my_table",
+    select_sql="SELECT * FROM source_table",
+    user="default",
+    password="admin123",
+    allow_type_cast=True,
+    strict_column_match=True
+)
+
+run_insert(config)
+```
+
+## 🧪 Тестирование и интеграция:
+
+```bash
+pytest -v --cov=insert_tools tests/
+```
+
+Поддержка интеграционных тестов через Docker (см. `docker-compose.yml`).
+
+## 📈 Планы на развитие:
+
+В ближайших планах — поддержка дополнительных популярных баз данных, что сделает Insert Tools универсальным решением для управления ETL-процессами в вашей организации.
+
+## 🤝 Вклад и поддержка проекта:
+
+Ваши идеи, баг-репорты и pull-реквесты всегда приветствуются! Присоединяйтесь к сообществу и помогите сделать инструмент лучше.
+
+> С Insert Tools вставка данных становится простой, быстрой и безопасной. Экономьте время и нервы уже сегодня!
+
+---
+
+**Готовы начать? Установите инструмент прямо сейчас и почувствуйте разницу!**

insert_tools/clickhouse_insert/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: |
+          twine upload dist/*

insert_tools/clickhouse_insert/.github/workflows/python-ci.yml

@@ -0,0 +1,30 @@
+
+name: Python CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[dev]
+        pip install pytest clickhouse-connect pydantic python-dotenv pyyaml
+
+    - name: Run tests
+      run: |
+        pytest tests/

insert_tools/clickhouse_insert/__init__.py

@@ -0,0 +1,9 @@
+from .runner import InsertConfig, run_insert, SchemaMismatchError
+
+__all__ = [
+    "InsertConfig",
+    "run_insert",
+    "SchemaMismatchError",
+]
+
+__version__ = "0.1.0"

insert_tools/clickhouse_insert/cast_rewriter.py

@@ -0,0 +1,25 @@
+
+import re
+from typing import Dict, Tuple
+
+def rewrite_select_with_cast(select_sql: str,
+                              source_schema: Dict[str, Tuple[str, bool]],
+                              target_schema: Dict[str, Tuple[str, bool]]) -> str:
+    """
+    Переписывает SELECT-запрос с добавлением CAST(...) там, где типы отличаются и безопасное приведение допустимо.
+    """
+    columns = []
+    for col, (src_type, _) in source_schema.items():
+        tgt_type, _ = target_schema.get(col, (src_type, False))
+        if src_type != tgt_type:
+            columns.append(f"CAST({col} AS {tgt_type}) AS {col}")
+        else:
+            columns.append(col)
+
+    # Пытаемся заменить только список колонок в SELECT (не FROM, не WHERE)
+    match = re.match(r"\s*SELECT\s+(.+?)\s+FROM\s+(.+)", select_sql, re.IGNORECASE | re.DOTALL)
+    if not match:
+        raise ValueError("Не удалось разобрать SELECT-запрос")
+
+    col_part, from_part = match.groups()
+    return f"SELECT {', '.join(columns)} FROM {from_part.strip()}"

insert_tools/clickhouse_insert/cli.py

@@ -0,0 +1,84 @@
+import argparse
+import logging
+from clickhouse_insert.runner import InsertConfig, run_insert, SchemaMismatchError
+
+def main():
+    # Создаем парсер командной строки
+    parser = argparse.ArgumentParser(description="ClickHouse Insert CLI Tool")
+
+    from clickhouse_insert import __version__
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+    parser.add_argument("--host", type=str, help="Host of the ClickHouse server", required=False)
+    parser.add_argument("--port", type=int, default=8123, help="Port of the ClickHouse server", required=False)
+    parser.add_argument("--user", type=str, help="User for ClickHouse authentication", required=False)
+    parser.add_argument("--password", type=str, help="Password for ClickHouse authentication", required=False)
+    parser.add_argument("--database", type=str, help="Target database in ClickHouse", required=False)
+    parser.add_argument("--target_table", type=str, help="Target table in ClickHouse", required=False)
+    parser.add_argument("--select_sql", type=str, help="SELECT query to fetch data", required=False)
+    parser.add_argument("--allow_type_cast", action="store_true", help="Allow type casting if needed", required=False)
+
+    # Убираем обязательный параметр config для использования параметров CLI напрямую
+    # parser.add_argument("--config", required=True, help="Path to config file (.json/.yaml/.env)")
+
+    parser.add_argument("--dry-run", action="store_true", help="Только проверить схему, не вставлять данные")
+    parser.add_argument("--strict", action="store_true", help="Ошибка при наличии лишних колонок в SELECT")
+    parser.add_argument("--verbose", action="store_true", help="Подробный лог (DEBUG)")
+    parser.add_argument("--insert-columns", type=str, help="Список колонок для INSERT через запятую (в порядке)")
+
+    # Получаем аргументы
+    args = parser.parse_args()
+
+    # Включаем подробные логи, если нужно
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+        print("[VERBOSE] Включён режим DEBUG")
+
+    try:
+        # Формируем словарь конфигурации
+        config_params = {
+            "host": args.host,
+            "port": args.port,
+            "user": args.user,
+            "password": args.password,
+            "database": args.database,
+            "target_table": args.target_table,
+            "select_sql": args.select_sql,
+            "allow_type_cast": args.allow_type_cast
+        }
+
+        # Пропускаем пустые параметры
+        config_params = {key: value for key, value in config_params.items() if value is not None}
+
+        # Создаем объект конфигурации
+        config = InsertConfig(**config_params)
+
+        # Обрабатываем dry-run
+        if args.dry_run:
+            print("[DRY-RUN] Проверка схемы без вставки")
+            config._dry_run = True
+
+        # Включаем строгую проверку колонок, если требуется
+        if args.strict:
+            print("[STRICT] Проверка: лишние поля вызовут ошибку")
+            config.strict_column_match = True
+
+        # Обрабатываем аргумент insert-columns
+        if args.insert_columns:
+            config.insert_columns = [col.strip() for col in args.insert_columns.split(",")]
+            print(f"[COLUMNS] Вставка только в колонки: {config.insert_columns}")
+
+        # Выполняем вставку данных
+        run_insert(config)
+
+        if args.verbose or args.dry_run:
+            logging.debug(f"Итоговый SQL: {config.select_sql}")
+
+    except SchemaMismatchError as e:
+        print(e)
+        exit(1)
+    except Exception as e:
+        print(f"Произошла ошибка: {e}")
+        exit(2)
+
+if __name__ == "__main__":
+    main()