Clickhouse Migrations Laravel Package

Product Decisions This Supports

• Build vs. buy for OLAP schema change management. This package is a candidate answer to "how do we version-control ClickHouse DDL?" — the buy side of the decision. It gives file-based, ordered migration tracking so schema changes to the analytics store stop being tribal knowledge or manual clickhouse-client sessions. Weigh it against a ~1–2 engineer-day in-house artisan command or an established generic tool.

• Roadmap: standardizing or splitting migration tooling. If ClickHouse is entering the stack, this forces the decision of whether one migration discipline covers both OLTP (MySQL/Postgres) and OLAP (ClickHouse), or whether analytics gets its own pipeline. That's an architecture-standard decision with long-tail cost, not a library choice.

• Release-process and CI gating decisions. A migration runner implies a gate: schema changes ship as reviewed files, applied by pipeline, not by hand. That supports decisions about who approves DDL, how staging is promoted, and whether schema drift is detected before deploy.

• Use cases it plausibly serves: adding/altering columns on event tables, creating materialized views and their targets, TTL and partitioning changes, backfill-adjacent schema work in an analytics warehouse where the table set is small and churn is low.

• Non-decision it does not support: anything requiring rollback guarantees. ClickHouse has no transactional DDL and mutations are asynchronous; any tool here bookkeeps versions, it does not make a destructive change reversible. Do not let this package imply safety it cannot provide.

When to Consider This Package

Consider it when:

• You are a PHP shop already running Symfony — the package is described as a Symfony bundle, so a Laravel codebase needs glue (service provider, artisan commands) written and owned by you.
• ClickHouse schema is small and low-churn (single digits of tables, a handful of migrations per quarter) and a single-node or simply-managed cluster is in play.
• MIT licensing, self-hosting, and vendoring/forking are acceptable — which they must be, given the maintenance signals below.
• You can pin a ClickHouse version and verify the generated DDL against it in a spike before committing.
• The alternative on the table is "no process at all," which is the realistic baseline for most analytics stores.

Look elsewhere when:

• Maintenance risk is disqualifying. Last release 2023-02-15, 9 stars, 0 dependents, effectively a single maintainer. Treat it as unmaintained source code you adopt, not a dependency you consume. Bus factor is 1.
• You need cluster-aware DDL (ON CLUSTER, replicated/distributed table pairs, sharded topologies). This is where ClickHouse migration tooling actually gets hard, and a thin wrapper will not carry you.
• You need audit trails, approvals, drift detection, or multi-environment orchestration — that's Atlas, Liquibase, or a managed platform, not a bundle.
• You need rollback semantics. No tool solves this on ClickHouse; pick a workflow (expand/contract, additive-only) instead of a library.
• You are Laravel-first and want zero custom integration work — the ecosystem-native path (a small artisan command around the ClickHouse client, or an existing Laravel ClickHouse package) is less total cost than adopting and patching a Symfony bundle.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed utility for versioning ClickHouse schema changes. It is cheap to try and cheap to abandon. It is not a strategic dependency — 9 stars, no dependents, no release since early 2023, one maintainer. Recommendation: fund a timeboxed spike (1–2 engineer-days) to prove the workflow on our actual cluster, and pre-commit to the fallback (in-house artisan command or an established generic migration tool) so a failed spike costs days, not a quarter. Do not put this on a roadmap slide as a solved problem; put "ClickHouse schema change process" on the roadmap and treat this as one implementation option.

To engineering: The value is narrow and honest — ordered, versioned migration files plus a tracking table, with a Symfony integration we'd have to adapt for Laravel. The hard parts of ClickHouse migrations (no transactional DDL, async mutations, ON CLUSTER for distributed DDL, no real rollback) remain ours regardless of the tool. So the real decision is our DDL workflow — additive-first, expand/contract, reviewed files, applied by CI — and the library is a convenience wrapper around it. Adopt only with a fork we control and a pinned ClickHouse version in CI.