Phpclickhouse Laravel Laravel Package

Technical Evaluation

oralunal/laravel-clickhouse is a Laravel database driver/package that surfaces ClickHouse (the columnar OLAP engine) through Laravel's Eloquent/query-builder conventions. v4.2.0 is a tooling-and-DX release: it is dominated by static-analysis precision (PHPStan/Larastan extension) and developer scaffolding (make:clickhouse-model, make:clickhouse-migration), plus a small correction to the read-only connection model.

Architecture fit. The package sits at the persistence boundary of a Laravel app. It is a good fit only where the access pattern is analytical rather than transactional: event/telemetry ingestion, reporting, aggregations, large append-only fact tables. It is a poor fit as a general-purpose second database behind normal CRUD flows, because ClickHouse semantics (eventual consistency on replicated setups, no real row-level UPDATE/DELETE semantics, no traditional transactions, ORDER BY/primary-key-driven access) leak into application design. The v4.2.0 additions reinforce this: the new MATERIALIZED/ALIAS nullability handling and read-only-connection awareness exist precisely because ClickHouse schemas diverge from what a standard Laravel mental model assumes.

Integration feasibility. Low friction on the Laravel side: Composer install, publish config, register the connection in config/database.php, and models extend or use the package's base model. The new make:clickhouse-model / make:clickhouse-migration generators materially reduce the "write it by hand" tax and are the strongest argument in this release for adoption by a team unfamiliar with ClickHouse DDL. The PHPStan extension is the real differentiator — it means column-level types flow into static analysis, which is unusual and valuable for a multi-store Laravel app.

Technical risk.

• Package-maturity risk. This is a community package with a single-maintainer profile and a rapid minor-release cadence. v4.2.0 contains a public-API deprecation (PHPStan\ConnectionConfig::isReadOnly()), which tells you internals are still settling.
• Static-analysis coupling risk. A meaningful share of this release's value depends on Larastan/PHPStan being wired into CI. Teams without static analysis get the generators but lose most of the correctness story.
• Correctness risk on read-only topologies. The changed behaviour — Float32/Float64 become nullable under a read-only connection, and MATERIALIZED/ALIAS columns are treated as nullable — is more accurate typing, but it silently widens types downstream. Code that assumed non-null floats on read-only connections may now fail static analysis (which is the point) or, if the extension isn't loaded, misbehave at runtime.
• Cache-invalidation risk. Disabling Larastan's migration cache (#24) trades correctness for CI runtime; expect slower analysis on large schemas, and expect cache-key surprises if you fork the ruleset.
• Upgrade-tooling risk. lc-upgrade-3x-to-4x now only suggests schema:dump for tables without a creating migration. This is a safer heuristic, but teams mid-upgrade must re-verify their dump set — an incorrect schema:dump silently drops tables from the migration baseline.

Key questions.

1. What ClickHouse server versions are supported and tested? Cluster/ON CLUSTER and Replicated engine support?
2. Is there a versioning/compatibility policy (Laravel 10/11/12, PHP 8.2/8.3) with a CI matrix we can inspect?
3. Does the PHPStan extension require a live ClickHouse connection in CI, or can it read migration files offline? (The release notes imply it can read migrations, which is a big win for hermetic CI — worth confirming.)
4. Who owns hasReadOnlyClickHouseConnection() upstream, and is the old method slated for removal in 5.0 or sooner?
5. What is the maintainer's bus-factor and response time on issues?
6. Are write paths tested against a real ClickHouse instance, or mocked?

Bottom line: v4.2.0 raises the package's engineering quality (static-analysis fidelity, generators, upgrade tooling) without introducing a breaking change. It does not change the fundamental risk profile — a niche, community-maintained OLAP driver — but it does lower the cost of a safe pilot.

Integration Approach

Stack fit. Laravel 10/11 application, PHP 8.2+, ClickHouse 22.x+. The package is an add-on to the existing database configuration and does not require replacing the primary relational store. Recommended topology is a two-connection setup: MySQL/Postgres for transactional/OLTP concerns, ClickHouse for analytics and event storage. The read-only-connection work in this release explicitly anticipates that split (writer connection vs. read replica).

Migration path.

• Greenfield: install, publish config, add the clickhouse connection, generate models/migrations with the new commands. This is the lowest-risk entry and where v4.2.0 pays off most.
• Existing 3.x users: run lc-upgrade-3x-to-4x, then re-review the generated schema:dump set under the new heuristic — tables created by a migration are no longer dumped, which is correct but changes the baseline. Verify against a fresh database before merging.
• No prior ClickHouse use: do not attempt to mirror the OLTP schema into ClickHouse. Model the analytical tables explicitly with ORDER BY chosen for query patterns.

Compatibility.

• Static analysis: require PHPStan + Larastan in CI and enable the package's extension. Expect the first run to surface nullability errors on read-only connections and on MATERIALIZED/ALIAS columns — treat these as findings, not noise.
• Cache: accept the Larastan migration-cache disable. Budget CI time accordingly; if analysis becomes slow, scope the analysis path to models rather than reintroducing a cache the extension disables.
• PHPStan API: migrate ConnectionConfig::isReadOnly() → hasReadOnlyClickHouseConnection() now, in any custom rules, before it is removed.

Sequencing.

1. Wire PHPStan/Larastan + the package extension in CI (cheap, no runtime change, and it validates the whole thesis).
2. Pilot one non-critical analytical consumer — a reporting or telemetry table — with the new generators to establish conventions.
3. Establish schema-management rules: which tables live in migrations vs. schema:dump, and how read-only replicas are declared.
4. Only then expand to higher-value datasets; revisit at that point with load and failure-mode evidence.

Operational Impact

Maintenance. The package tracks ClickHouse's own evolution, so maintenance is continuous rather than one-off: ClickHouse releases quarterly-ish, and the driver will lag or lead. Assign explicit internal ownership; do not assume the maintainer's cadence matches your upgrade cadence. Public-API churn in the PHPStan namespace (as seen here) suggests pinning to exact minor versions rather than floating ^4, and reviewing changelogs on every bump. The deprecation of isReadOnly() is a low-cost fix now and a build-breaker later — schedule it.

Support. Community-supported only. There is no vendor SLA. Practical consequence: your team must be able to read the driver source for query-builder and grammar behaviour when something diverges from Laravel expectations. Budget for that expertise; it is not a "drop-in and forget" dependency.

Scaling. The package itself is not the scaling constraint — ClickHouse is. The driver adds negligible per-query overhead. Real scaling concerns are architectural: replicated clusters, ON CLUSTER DDL propagation, insert batching (single-row inserts are pathological on ClickHouse and Eloquent's default save path will happily emit them), and part-count/merge pressure from high insert rates. The read-only connection typing work in v4.2.0 is directly relevant here — teams routing reads to replicas get accurate static types instead of false confidence.

Failure modes.

• Connection/topology drift — a connection configured as read-only when the server is not (or vice versa) now changes inferred types. Misconfiguration produces static-analysis passes and runtime surprises. Assert the flag in a health check.
• Insert-path contention — Eloquent save() per row will collapse under ClickHouse load; enforce batched insert conventions in code review.
• Migration-baseline loss — the revised schema:dump heuristic can omit tables from the baseline if migrations are ambiguous. Add a CI step that diffs schema:dump output against a clean migrate.
• Static-analysis blind spots — any model or raw query outside the extension's reach gets no type checking. Prefer the model/generator path over raw DB::connection('clickhouse')->select().
• Parallel query typing — #25 fixed Parallel::get()/getRows() accepting any model's query; previously-incorrect code will now surface as errors. Expect a one-time cleanup on upgrade.

Ramp-up. Two distinct skill curves, and both are required:

• Laravel-side: trivial — Composer, config, artisan generators. A mid-level Laravel engineer is productive in under a day, and v4.2.0's generators cut that further.
• ClickHouse-side: non-trivial — MergeTree family selection, ORDER BY/primary key design, materialized views and columns, ALIAS semantics, eventual consistency on replicated setups, and the absence of transactions. Realistically 1–2 weeks to competence for an engineer and ongoing review for schema changes.

Plan for a designated owner with ClickHouse knowledge. The package's DX improvements in v4.2.0 make the Laravel half of onboarding nearly free, which raises the risk of under-investing in the ClickHouse half — the more common failure mode for teams adopting this stack.