ClickMigrate 1.0.0__py3-none-any.whl

clickmigrate/__init__.py

@@ -0,0 +1,6 @@
+"""ClickMigrate - A database migration framework for ClickHouse."""
+
+from clickmigrate.manager import MigrationManager
+from clickmigrate.config import Config
+
+__all__ = ["MigrationManager", "Config"]

clickmigrate/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m clickmigrate."""
+
+from clickmigrate.cli import app
+
+if __name__ == "__main__":
+    app()

clickmigrate/cli.py

@@ -0,0 +1,84 @@
+"""Command Line Interface for ClickMigrate."""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from clickmigrate.config import load_config
+from clickmigrate.manager import MigrationManager
+from clickmigrate.exceptions import ClickMigrateError
+
+app = typer.Typer(help="ClickMigrate: A modern ClickHouse migration framework.")
+console = Console()
+
+def get_manager() -> MigrationManager:
+    try:
+        config = load_config()
+        return MigrationManager(config)
+    except Exception as e:
+        console.print(f"[bold red]Initialization Error:[/bold red] {e}")
+        raise typer.Exit(code=1)
+
+@app.command()
+def init() -> None:
+    """Initialize a new ClickMigrate environment."""
+    config = load_config()
+    import os
+    os.makedirs(config.migration_directory, exist_ok=True)
+    console.print(f"[green]Initialized ClickMigrate in ./{config.migration_directory}/[/green]")
+
+@app.command()
+def revision(message: str = typer.Option(..., "-m", "--message", help="Migration description")) -> None:
+    """Create a new migration file."""
+    manager = get_manager()
+    filepath = manager.create_revision(message)
+    console.print(f"[green]Created revision:[/green] {filepath}")
+
+@app.command()
+def migrate(dry_run: bool = typer.Option(False, "--dry-run", help="Simulate migration without applying")) -> None:
+    """Apply all pending migrations."""
+    console.print("\n[bold]ClickMigrate[/bold]\n")
+    manager = get_manager()
+    
+    try:
+        applied_count, pending_count = manager.status()
+        if pending_count == 0:
+            console.print("No pending migrations.\n")
+            return
+            
+        console.print(f"Applying [yellow]{pending_count}[/yellow] migrations...\n")
+        
+        if dry_run:
+            console.print("[yellow]DRY RUN: No changes will be made to the database.[/yellow]\n")
+            
+        applied, duration = manager.migrate(dry_run=dry_run)
+        
+        console.print("\n[bold green]SUCCESS[/bold green]\n")
+        console.print(f"Applied migrations : {applied}")
+        console.print(f"Pending migrations : {pending_count - applied}")
+        console.print(f"Execution time     : {duration:.2f} seconds\n")
+        
+    except ClickMigrateError as e:
+        console.print(f"\n[bold red]FAILED[/bold red]\n{e}")
+        raise typer.Exit(code=1)
+
+@app.command()
+def status() -> None:
+    """Show current migration status."""
+    manager = get_manager()
+    applied, pending = manager.status()
+    console.print(f"Applied migrations : [green]{applied}[/green]")
+    console.print(f"Pending migrations : [yellow]{pending}[/yellow]")
+
+@app.command()
+def validate() -> None:
+    """Validate checksums of applied migrations against local files."""
+    manager = get_manager()
+    try:
+        manager.validate()
+        console.print("[green]All migrations are valid. No checksum mismatches.[/green]")
+    except ClickMigrateError as e:
+        console.print(f"[bold red]Validation Failed:[/bold red] {e}")
+        raise typer.Exit(code=1)
+
+if __name__ == "__main__":
+    app()

clickmigrate/config.py

@@ -0,0 +1,58 @@
+"""Configuration management for ClickMigrate."""
+
+import os
+import json
+import tomllib
+from dataclasses import dataclass
+from typing import Any, Dict
+import yaml
+from clickmigrate.exceptions import ConfigurationError
+
+@dataclass
+class Config:
+    """Stores the ClickMigrate configuration."""
+    host: str = "localhost"
+    port: int = 8123
+    database: str = "default"
+    username: str = "default"
+    password: str = ""
+    migration_directory: str = "migrations"
+    migration_table: str = "clickmigrate_history"
+
+def load_config() -> Config:
+    """Loads configuration from environment variables or files."""
+    config_data: Dict[str, Any] = {}
+
+    # 1. Try pyproject.toml
+    if os.path.exists("pyproject.toml"):
+        with open("pyproject.toml", "rb") as f:
+            toml_data = tomllib.load(f)
+            config_data.update(toml_data.get("tool", {}).get("clickmigrate", {}))
+
+    # 2. Try clickmigrate.json
+    elif os.path.exists("clickmigrate.json"):
+        with open("clickmigrate.json", "r") as f:
+            config_data.update(json.load(f))
+
+    # 3. Try clickmigrate.yaml
+    elif os.path.exists("clickmigrate.yaml"):
+        with open("clickmigrate.yaml", "r") as f:
+            config_data.update(yaml.safe_load(f) or {})
+
+    # 4. Override with Environment Variables
+    env_mapping = {
+        "CLICKMIGRATE_HOST": "host",
+        "CLICKMIGRATE_PORT": "port",
+        "CLICKMIGRATE_DATABASE": "database",
+        "CLICKMIGRATE_USERNAME": "username",
+        "CLICKMIGRATE_PASSWORD": "password",
+        "CLICKMIGRATE_DIRECTORY": "migration_directory",
+        "CLICKMIGRATE_TABLE": "migration_table",
+    }
+    
+    for env_var, key in env_mapping.items():
+        if env_var in os.environ:
+            val = os.environ[env_var]
+            config_data[key] = int(val) if key == "port" else val
+
+    return Config(**config_data)

clickmigrate/database.py

@@ -0,0 +1,66 @@
+"""Database interaction layer."""
+
+import clickhouse_connect
+from clickhouse_connect.driver.client import Client
+from typing import List, Dict, Any
+from clickmigrate.config import Config
+from clickmigrate.exceptions import MigrationError
+
+class Database:
+    """Handles ClickHouse connections and queries."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self.client: Client = self._connect()
+
+    def _connect(self) -> Client:
+        """Establishes a connection to ClickHouse."""
+        try:
+            return clickhouse_connect.get_client(
+                host=self.config.host,
+                port=self.config.port,
+                username=self.config.username,
+                password=self.config.password,
+                database=self.config.database,
+            )
+        except Exception as e:
+            raise MigrationError(f"Failed to connect to ClickHouse: {e}")
+
+    def ensure_history_table(self) -> None:
+        """Creates the migration history table if it doesn't exist."""
+        query = f"""
+        CREATE TABLE IF NOT EXISTS {self.config.migration_table} (
+            version String,
+            name String,
+            checksum String,
+            applied_at DateTime DEFAULT now()
+        ) ENGINE = MergeTree()
+        ORDER BY version
+        """
+        self.client.command(query)
+
+    def get_applied_migrations(self) -> Dict[str, str]:
+        """Retrieves applied migrations and their checksums.
+        
+        Returns:
+            Dict mapping version to checksum.
+        """
+        self.ensure_history_table()
+        query = f"SELECT version, checksum FROM {self.config.migration_table}"
+        result = self.client.query(query)
+        return {row[0]: row[1] for row in result.result_rows}
+
+    def apply_migration(self, version: str, name: str, checksum: str, sql: str) -> None:
+        """Executes a migration script and records it in the history table."""
+        try:
+            # Execute the actual migration
+            self.client.command(sql)
+            
+            # Record in history
+            record_query = f"""
+            INSERT INTO {self.config.migration_table} (version, name, checksum)
+            VALUES ('{version}', '{name}', '{checksum}')
+            """
+            self.client.command(record_query)
+        except Exception as e:
+            raise MigrationError(f"Failed to apply migration {version}_{name}: {e}")

clickmigrate/exceptions.py

@@ -0,0 +1,17 @@
+"""Custom exceptions for ClickMigrate."""
+
+class ClickMigrateError(Exception):
+    """Base exception for all ClickMigrate errors."""
+    pass
+
+class ConfigurationError(ClickMigrateError):
+    """Raised when configuration is invalid or missing."""
+    pass
+
+class MigrationError(ClickMigrateError):
+    """Raised when a migration fails to apply."""
+    pass
+
+class ChecksumError(ClickMigrateError):
+    """Raised when an applied migration's checksum differs from the file."""
+    pass

clickmigrate/manager.py

@@ -0,0 +1,116 @@
+"""Core migration management logic."""
+
+import os
+import hashlib
+import time
+from typing import List, Tuple
+from dataclasses import dataclass
+from clickmigrate.config import Config
+from clickmigrate.database import Database
+from clickmigrate.exceptions import ChecksumError, ClickMigrateError
+
+@dataclass
+class Migration:
+    """Represents a single SQL migration."""
+    version: str
+    name: str
+    filepath: str
+    content: str
+    checksum: str
+
+class MigrationManager:
+    """API for managing ClickHouse migrations."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self.db = Database(config)
+
+    def _calculate_checksum(self, content: str) -> str:
+        """Calculates SHA-256 checksum for migration content."""
+        return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+    def _get_local_migrations(self) -> List[Migration]:
+        """Discovers and parses local .sql migration files."""
+        migrations = []
+        if not os.path.exists(self.config.migration_directory):
+            return migrations
+
+        for filename in sorted(os.listdir(self.config.migration_directory)):
+            if filename.endswith(".sql"):
+                parts = filename.replace(".sql", "").split("_", 1)
+                if len(parts) != 2:
+                    continue
+                
+                version, name = parts
+                filepath = os.path.join(self.config.migration_directory, filename)
+                
+                with open(filepath, "r", encoding="utf-8") as f:
+                    content = f.read()
+                
+                checksum = self._calculate_checksum(content)
+                migrations.append(Migration(version, name, filepath, content, checksum))
+                
+        return migrations
+
+    def validate(self) -> None:
+        """Validates that local checksums match applied checksums."""
+        applied = self.db.get_applied_migrations()
+        local = self._get_local_migrations()
+
+        for loc in local:
+            if loc.version in applied:
+                if applied[loc.version] != loc.checksum:
+                    raise ChecksumError(
+                        f"Checksum mismatch for {loc.version}_{loc.name}. "
+                        "The local file has been modified since it was applied."
+                    )
+
+    def status(self) -> Tuple[int, int]:
+        """Returns the count of (applied, pending) migrations."""
+        applied = self.db.get_applied_migrations()
+        local = self._get_local_migrations()
+        pending_count = sum(1 for m in local if m.version not in applied)
+        return len(applied), pending_count
+
+    def migrate(self, dry_run: bool = False) -> Tuple[int, float]:
+        """Applies all pending migrations.
+        
+        Returns:
+            Tuple containing (number of migrations applied, execution time in seconds).
+        """
+        self.validate()
+        applied_map = self.db.get_applied_migrations()
+        local = self._get_local_migrations()
+        
+        pending = [m for m in local if m.version not in applied_map]
+        
+        if dry_run or not pending:
+            return len(pending), 0.0
+
+        start_time = time.time()
+        for migration in pending:
+            self.db.apply_migration(
+                version=migration.version,
+                name=migration.name,
+                checksum=migration.checksum,
+                sql=migration.content
+            )
+            
+        return len(pending), time.time() - start_time
+
+    def create_revision(self, message: str) -> str:
+        """Creates a new empty migration file."""
+        os.makedirs(self.config.migration_directory, exist_ok=True)
+        local = self._get_local_migrations()
+        
+        next_version = 1 if not local else int(local[-1].version) + 1
+        version_str = f"{next_version:03d}"
+        
+        safe_name = message.lower().replace(" ", "_").replace("-", "_")
+        filename = f"{version_str}_{safe_name}.sql"
+        filepath = os.path.join(self.config.migration_directory, filename)
+        
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(f"-- Migration: {message}\n-- Version: {version_str}\n\n")
+            
+        return filepath

clickmigrate-1.0.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: ClickMigrate
+Version: 1.0.0
+Summary: A modern, simple database migration framework for ClickHouse.
+Author-email: Ivo Theis <ivo.theis@queueforge.dev>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: clickhouse-connect>=0.6.8
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# ClickMigrate
+
+A modern, simple, and reliable database migration framework for ClickHouse, inspired by Alembic.
+
+ClickMigrate is designed to be lightweight and easy to understand. It avoids over-engineered abstractions, offering a straightforward CLI and a clean Python API for managing your ClickHouse schema evolutions.
+
+---
+
+## Features
+
+- **SQL-based Migrations** – Write your migrations in plain `.sql` files.
+- **Automatic Ordering** – Lexicographical sorting ensures migrations run in the correct sequence.
+- **State Management** – Automatically creates and manages a migration history table in ClickHouse.
+- **Checksum Validation** – Validates SHA-256 checksums to detect modified applied migrations.
+- **Flexible Configuration** – Supports `pyproject.toml`, JSON, YAML, or environment variables.
+- **Dry-Run Mode** – Preview which migrations will be applied without altering the database.
+- **Python API & CLI** – Use ClickMigrate from your terminal or programmatically in Python.
+
+---
+
+# Installation
+
+ClickMigrate requires **Python 3.11+**.
+
+Install it using pip:
+
+```bash
+pip install ClickMigrate
+```
+
+---
+
+# Quick Start (CLI)
+
+ClickMigrate provides an Alembic-like CLI for managing your migration workflow.
+
+## 1. Initialize the Environment
+
+Create the migration directory (default: `migrations/`).
+
+```bash
+clickmigrate init
+```
+
+---
+
+## 2. Create a Revision
+
+Generate a new sequential SQL migration file.
+
+```bash
+clickmigrate revision -m "create users table"
+```
+
+Example output:
+
+```text
+migrations/
+└── 001_create_users_table.sql
+```
+
+Edit the generated file and add your ClickHouse SQL statements.
+
+---
+
+## 3. Check Status
+
+View how many migrations have been applied and how many are pending.
+
+```bash
+clickmigrate status
+```
+
+---
+
+## 4. Apply Migrations
+
+Run all pending migrations.
+
+```bash
+clickmigrate migrate
+```
+
+Preview the execution without applying changes:
+
+```bash
+clickmigrate migrate --dry-run
+```
+
+---
+
+## 5. Validate Migration Integrity
+
+Verify that previously applied migration files have not been modified.
+
+```bash
+clickmigrate validate
+```
+
+---
+
+# Configuration
+
+ClickMigrate automatically searches for configuration files in your project root.
+
+Supported formats (in priority order):
+
+1. `pyproject.toml` *(recommended)*
+2. `clickmigrate.json`
+3. `clickmigrate.yaml`
+4. Environment variables
+
+## Option A: `pyproject.toml` (Recommended)
+
+```toml
+[tool.clickmigrate]
+host = "localhost"
+port = 8123
+database = "default"
+username = "default"
+password = "your_secure_password"
+
+migration_directory = "migrations"
+migration_table = "clickmigrate_history"
+```
+
+## Option B: `clickmigrate.json`
+
+```json
+{
+  "host": "localhost",
+  "port": 8123,
+  "database": "default",
+  "username": "default",
+  "password": "your_secure_password",
+  "migration_directory": "migrations",
+  "migration_table": "clickmigrate_history"
+}
+```
+
+## Option C: `clickmigrate.yaml`
+
+```yaml
+host: localhost
+port: 8123
+database: default
+username: default
+password: your_secure_password
+
+migration_directory: migrations
+migration_table: clickmigrate_history
+```
+
+## Option D: Environment Variables
+
+```bash
+CLICKMIGRATE_HOST=localhost
+CLICKMIGRATE_PORT=8123
+CLICKMIGRATE_DATABASE=default
+CLICKMIGRATE_USERNAME=default
+CLICKMIGRATE_PASSWORD=your_secure_password
+
+CLICKMIGRATE_MIGRATION_DIRECTORY=migrations
+CLICKMIGRATE_MIGRATION_TABLE=clickmigrate_history
+```
+
+---
+
+# Migration Naming
+
+Migration files are executed in **lexicographical order**.
+
+Example:
+
+```text
+001_create_users.sql
+002_add_email.sql
+003_create_orders.sql
+004_add_indexes.sql
+```
+
+Each migration is executed only once and recorded in the migration history table.
+
+---
+
+# Commands
+
+| Command | Description |
+|---------|-------------|
+| `clickmigrate init` | Initialize a migration project |
+| `clickmigrate revision -m "message"` | Create a new migration |
+| `clickmigrate status` | Show migration status |
+| `clickmigrate migrate` | Apply pending migrations |
+| `clickmigrate migrate --dry-run` | Preview pending migrations |
+| `clickmigrate validate` | Validate migration checksums |
+
+---
+
+# Requirements
+
+- Python **3.11+**
+- A running ClickHouse server
+- HTTP interface enabled (default port `8123`)
+
+---
+
+# License
+
+MIT License.

clickmigrate-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+clickmigrate/__init__.py,sha256=W9L3vJ6QTpOKpaJ8vSI3kBn7yFFSyegPer-MmAGhHfQ,199
+clickmigrate/__main__.py,sha256=N5jHrekzEOTzsitMBC0HrRgFRj0m7QGhjWX3rob_Kt0,117
+clickmigrate/cli.py,sha256=XB7OujASlvfwysHbMtaJiNg9ljYf3_B4A09NCEs0j5o,3073
+clickmigrate/config.py,sha256=qetD53iDWE6OFy0k3_R1CsYF6VwFSxEUjQ1Uc94T6DY,1857
+clickmigrate/database.py,sha256=yyd0u62bG5-t2S74PU8RogJAjtNVayVdrim-w_ESRoU,2432
+clickmigrate/exceptions.py,sha256=euhT0gqSD7aTvNpRgZ3E0U3m-qi64bxSHHKvh--o8tA,483
+clickmigrate/manager.py,sha256=XMo8bspdAmg0zYzidaotiLJexy0iMbjDGWpsTTtBS9s,4247
+clickmigrate-1.0.0.dist-info/licenses/LICENSE,sha256=xPxPHPlyTJx-zJ4DrnQWVXHrgoIjA2hjqb4vhNFS2WQ,1067
+clickmigrate-1.0.0.dist-info/METADATA,sha256=YtXlOR6lDp7U_F3DEB07-Bv9UBHydrSEpJQfQIs07Ec,4937
+clickmigrate-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+clickmigrate-1.0.0.dist-info/entry_points.txt,sha256=W_2niTaw0eCwaUZPGOCsmOGM6xx3F7YgbunNeohUgzU,54
+clickmigrate-1.0.0.dist-info/top_level.txt,sha256=Oh2PkpdAo7vLsjoNm7AHbnmBAcSefTKRKLoijcyTm-Q,13
+clickmigrate-1.0.0.dist-info/RECORD,,

clickmigrate-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clickmigrate-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clickmigrate = clickmigrate.cli:app

clickmigrate-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QueueForge
+
+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.

clickmigrate-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clickmigrate