Laravel Clickhouse Laravel Package

Technical Evaluation

Architecture fit. oralunal/laravel-clickhouse bridges Laravel's Eloquent/query builder/schema builder to a ClickHouse (columnar OLAP) backend. The correct architectural placement is an analytics/reporting sidecar alongside the primary OLTP database — not as a system of record. v4.2.0 is almost entirely a developer-experience and static-analysis release, which is a positive maturity signal: the maintainer is investing in typed schema correctness and code generation rather than surface area.

Integration feasibility. Low-friction. Composer install, register the service provider, add a clickhouse connection. The new make:clickhouse-model and make:clickhouse-migration generators remove the main onboarding pain point (hand-writing ClickHouse DDL by hand). The PHPStan/Larastan extension is opt-in and can be scoped.

Technical risk. No runtime or API breaking changes are apparent. The real risk is CI-visible:

• Static-analysis semantics changed in a minor bump. Float32/Float64 columns on read-only connections, and MATERIALIZED/ALIAS columns, are now correctly inferred as nullable. Any consumer code that previously passed PHPStan at a given level may now fail. This is functionally a breaking change for teams gating merges on PHPStan — budget triage time.
• Deprecation of PHPStan\ConnectionConfig::isReadOnly() in favor of hasReadOnlyClickHouseConnection(). Blast radius is limited to teams that extend or wrap the PHPStan extension, but it should be tracked against a removal deadline.
• PHPStan extension now disables Larastan's migration cache. Correctness improves; CI wall-clock time may increase measurably on large schemas.
• Single-maintainer project. Bus factor is the dominant long-term risk, not this release.

Key questions.

• Which ClickHouse server versions are tested in CI, and does that match our cluster?
• Is our PHPStan/Larastan baseline currently clean, and who owns triaging the new nullable inferences?
• Do we have MATERIALIZED or ALIAS columns in production schema? If so, do our models attempt inserts into them?
• Do we extend ConnectionConfig anywhere, or only consume the shipped extension?
• Does the read-only-connection support map to our intended replica topology (write primary, analytics reads from replica)?
• What is the maintainer's issue response SLA and release cadence?

Integration Approach

Stack fit. Requires confirmation of PHP, Laravel, PHPStan, and Larastan version constraints against our current pins — the release notes do not state them. Teams not using PHPStan/Larastan get the generators and bug fixes with essentially zero risk; teams using them get the bulk of the value and the bulk of the upgrade effort.

Migration path. composer require --with-all-dependencies from 4.1.x to 4.2.0 in a branch. The lc-upgrade-3x-to-4x command is irrelevant unless we are coming from 3.x, and its refinement (suggesting schema:dump only for tables lacking a migration) is a minor correctness improvement to that path.

Compatibility. Two touchpoints to verify before merge: (1) whether the extension's cache-disabling behavior conflicts with our existing Larastan configuration, and (2) whether new nullable inferences collide with hand-written model docblocks or @property annotations we maintain.

Sequencing.

1. Branch, bump, run the existing test suite — expect green.
2. Run PHPStan against the current baseline and diff the new errors. Classify each as real latent bug (nullable column dereferenced) vs. annotation drift (needs @property update).
3. Fix annotation drift; file tickets for real bugs rather than fixing inline, to keep the upgrade PR reviewable.
4. If ConnectionConfig::isReadOnly() appears in our code, migrate to hasReadOnlyClickHouseConnection() in the same PR.
5. Pilot the two generators on one new table only — do not retrofit existing models.
6. Merge with an updated PHPStan baseline committed, and note the change in the team changelog.

Operational Impact

Maintenance. Low steady-state effort, but do not auto-merge minor bumps. This release demonstrates that minors can change static-analysis outcomes; treat each bump as requiring a CI diff review. Pin to minor versions and upgrade deliberately.

Support. GitHub issues only, no commercial backing. Nominate an internal owner — realistically the data/analytics platform team, not general application support — so ClickHouse-specific questions have a routing destination.

Scaling. The package is a thin adapter; scaling is a ClickHouse cluster concern (sharding, replicas, MergeTree design). Read-only connection support is the operationally interesting capability: it lets analytics reads target a replica while writes go to the primary, which is the pattern most teams will want. Parallel::get()/getRows() allow query fan-out, and the v4.2.0 fix removing the single-model restriction makes them usable for mixed result sets.

Failure modes to watch.

• Silent CI breakage after the nullable-inference change — caught only if the upgrade PR runs full static analysis.
• Schema drift between Laravel migrations and actual ClickHouse DDL. The migration-reading PHPStan extension and the schema:dump guidance mitigate but do not eliminate this; it remains the classic failure for this class of package.
• Insert failures on MATERIALIZED/ALIAS columns — these are not insertable, and generated models may include them. Verify generated models before using them on a write path.
• CI slowdown from the disabled Larastan migration cache; measure before and after on the largest schema in the repo.

Ramp-up. A Laravel developer can produce a working model and migration in under a day with the new generators. The real learning curve is ClickHouse semantics — MergeTree engines, ordering keys, granularity() index definitions, asynchronous mutations, and eventual consistency. Budget a short internal primer; the generators remove syntax friction but not conceptual friction.

Recommendation. Adopt. This is a low-risk minor release with meaningful DX gains. Gate the rollout on a static-analysis diff rather than on the test suite alone, and track the ConnectionConfig::isReadOnly() deprecation for removal in v5.