feature/design

.docker/ClickHouse/Dockerfile

@@ -0,0 +1,3 @@
+FROM clickhouse/clickhouse-server:26.3-alpine
+
+COPY init.sh /docker-entrypoint-initdb.d/

.docker/ClickHouse/init.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+clickhouse-client --user "$CLICKHOUSE_USER" --password "$CLICKHOUSE_PASSWORD" --query "CREATE DATABASE IF NOT EXISTS main;"

.github/workflows/tests.yml

@@ -7,6 +7,22 @@ jobs:
     name: unit tests
     runs-on: ubuntu-latest
 
+    services:
+      clickhouse:
+        image: clickhouse/clickhouse-server:26.3-alpine
+        ports:
+          - 8123:8123
+        env:
+          CLICKHOUSE_DB: main
+          CLICKHOUSE_USER: default
+          CLICKHOUSE_PASSWORD: ""
+          CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
+        options: >-
+          --health-cmd "wget --no-verbose --tries=1 --spider http://127.0.0.1:8123/ping || exit 1"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+
     strategy:
       fail-fast: false
       matrix:
@@ -23,7 +39,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-          extensions: pdo xdebug
+          extensions: curl xdebug
           coverage: xdebug
         env:
           fail-fast: true
@@ -39,3 +55,8 @@ jobs:
         run: vendor/bin/testo
         env:
           XDEBUG_MODE: coverage
+          CLICKHOUSE_HOST: 127.0.0.1
+          CLICKHOUSE_PORT: "8123"
+          CLICKHOUSE_DB: main
+          CLICKHOUSE_USER: default
+          CLICKHOUSE_PASSWORD: ""

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- ClickHouse migration driver with two version-table strategies selectable via
+  `Mode` (`Mutation`, `AppendOnly`).
+- Native `Driver(host, port, database, mode, username?, password?, options?)`
+  configuration over `smi2/phpclickhouse`.
+- End-to-end Migrator workflow tests against a real ClickHouse (local docker
+  compose + CI service).

Makefile

@@ -3,6 +3,7 @@ VERSION ?= $$(git rev-parse --verify HEAD)
 USER = $$(id -u)
 ARGS = $(filter-out $@,$(MAKECMDGOALS))
 DOCKER_RUN = docker run --init -it --rm -u ${USER} -v "$$(pwd):/app" -w /app
+DOCKER_COMPOSE = UID=$(USER) PHP_VERSION=$(PHP_VERSION) docker compose
 
 # https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
 .PHONY: help tests fix check
@@ -70,45 +71,25 @@ check: ## run analysis tools
 	make psalm
 	make phpstan
 
+## Tests
+
 infection:
-	docker build \
-		--build-arg PHP_VERSION=$(PHP_VERSION) \
-		--build-arg USER=$(USER) \
-		--build-arg WORKDIR=/app \
-		--target tests \
-		-t app_cli .docker/php/cli
-	- docker run --init -it --rm \
-		-u $(USER) \
-		-v "$$(pwd):/app" \
-		-w /app \
-		app_cli ./vendor/bin/infection \
-			--coverage=/app/runtime/coverage \
-			--threads=max \
-			--skip-initial-tests
-	docker image rm -f app_cli
+	$(DOCKER_COMPOSE) up -d --build --wait clickhouse
+	- $(DOCKER_COMPOSE) run --rm cli ./vendor/bin/infection \
+		--coverage=/app/runtime/coverage \
+		--threads=max \
+		--skip-initial-tests
+	$(DOCKER_COMPOSE) down -v
 
 tests:
-	docker build \
-		--build-arg PHP_VERSION=$(PHP_VERSION) \
-		--build-arg USER=$(USER) \
-		--build-arg WORKDIR=/app \
-		--target tests \
-		-t app_cli .docker/php/cli
-	- docker run --init -it --rm \
-		-u $(USER) \
-		-v "$$(pwd):/app" \
-		-w /app \
-		app_cli ./vendor/bin/testo \
-			--coverage --log-junit=/app/runtime/coverage/junit.xml
-	- docker run --init -it --rm \
-		-u $(USER) \
-		-v "$$(pwd):/app" \
-		-w /app \
-		app_cli ./vendor/bin/infection \
-			--coverage=/app/runtime/coverage \
-			--threads=max \
-			--skip-initial-tests
-	docker image rm -f app_cli
+	$(DOCKER_COMPOSE) up -d --build --wait clickhouse
+	- $(DOCKER_COMPOSE) run --rm cli ./vendor/bin/testo \
+		--coverage --log-junit=/app/runtime/coverage/junit.xml
+	- $(DOCKER_COMPOSE) run --rm cli ./vendor/bin/infection \
+		--coverage=/app/runtime/coverage \
+		--threads=max \
+		--skip-initial-tests
+	$(DOCKER_COMPOSE) down -v
 
 ## Application
 

README.md

@@ -1,5 +1,46 @@
 # Database Migrator: ClickHouse
 
+A [dbschemix](https://dbschemix.github.io/) migration driver for ClickHouse,
+built on [smi2/phpclickhouse](https://github.com/smi2/phpClickHouse).
+
+## Usage
+
+```php
+use dbschemix\clickhouse\Driver;
+use dbschemix\clickhouse\Mode;
+use dbschemix\core\Config;
+use dbschemix\core\Migration;
+use dbschemix\core\Migrator;
+
+$driver = new Driver(
+    host: '127.0.0.1',
+    port: 8123,
+    database: 'main',
+    mode: Mode::Mutation,   // or Mode::AppendOnly
+    username: 'default',
+    password: '',
+    // options: ['settings' => [...], 'https' => true, ...] // phpClickHouse passthrough
+);
+
+$migrator = new Migrator([
+    new Migration(path: __DIR__ . '/migration/main', driver: $driver, config: new Config()),
+]);
+
+$migrator->init(); // creates the version table
+$migrator->up();   // applies pending migrations
+```
+
+### Modes
+
+- `Mode::Mutation` — version table is a `ReplacingMergeTree`; reads use `FINAL`,
+  rollback removes the row via a synchronous `ALTER TABLE ... DELETE`.
+- `Mode::AppendOnly` — append-only journal; every `up`/`down` appends a row and
+  the current state is derived with `argMax`. Nothing is physically deleted.
+
+> ClickHouse has no transactions: `up`/`down` run the migration and the version
+> bookkeeping as separate statements, so a failure between them cannot be rolled
+> back. The target database must already exist.
+
 ### Static analysis
 
 To run static analysis:
@@ -21,7 +62,7 @@ make fix
 ### Testing
 
 The package is tested with 
-- [PHPUnit](https://phpunit.de/)
+- [testo](https://php-testo.github.io/)
 - [Infection](https://github.com/infection/infection)
 
 To run tests:

compose.yaml

@@ -0,0 +1,53 @@
+x-default-logging: &default-logging
+  driver: local
+  options:
+    max-size: "5m"
+    max-file: "3"
+
+name: dbschemix
+services:
+  clickhouse:
+    container_name: dbschemix_clickhouse
+    build: .docker/ClickHouse
+    deploy:
+      resources:
+        limits:
+          cpus: '1.0'
+          memory: 512M
+        reservations:
+          cpus: '0.2'
+          memory: 256M
+    environment:
+      CLICKHOUSE_DB: main
+      CLICKHOUSE_USER: default
+      CLICKHOUSE_PASSWORD: ""
+      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:8123/ping"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+    logging: *default-logging
+
+  cli:
+    container_name: dbschemix_clickhouse_cli
+    build:
+      context: .docker/php/cli
+      target: tests
+      args:
+        PHP_VERSION: "${PHP_VERSION:-8.3}"
+        UID: "${UID:-10001}"
+        WORKDIR: /app
+    volumes:
+      - ".:/app"
+    working_dir: /app
+    environment:
+      CLICKHOUSE_HOST: clickhouse
+      CLICKHOUSE_PORT: "8123"
+      CLICKHOUSE_DB: main
+      CLICKHOUSE_USER: default
+      CLICKHOUSE_PASSWORD: ""
+    depends_on:
+      clickhouse:
+        condition: service_healthy
+    logging: *default-logging

composer.json

@@ -1,6 +1,6 @@
 {
   "name": "dbschemix/clickhouse",
-  "description": "dbschemix: database migration clickhouse",
+  "description": "dbschemix: clickhouse database migration driver",
   "type": "library",
   "license": "MIT",
   "authors": [