Clickhouse Builder Laravel Package

Technical Evaluation

Architecture fit

• The package is a query-construction layer, not a full ORM or connection manager. That matches the dominant Laravel pattern: MySQL/Postgres for OLTP, ClickHouse as an append-only analytics sink. It does not try to be Eloquent, which is the right scope.
• The fluent API deliberately mirrors Laravel's DB::table() idiom, so it slots into an existing service layer without introducing a new mental model for the team. Cognitive adoption cost is near zero.
• It is a good fit for the read path (dashboards, aggregations, cohort/reporting queries) and bulk append writes. It is a poor fit for anything transactional, schema-migration-driven, or requiring relational integrity — which is correct for ClickHouse anyway.
• The Laravel/Lumen integration is a service provider + facade + config block. Integration surface is small enough that the package can be fully contained inside one adapter class, which is the decisive architectural property here.

Integration feasibility

• Wiring is composer require plus config publish. Low effort, low blast radius.
• The real question is not "does it install" but "does it bind parameters safely and expose the ClickHouse features we need." Both must be verified in a spike, not assumed.
• No evidence of a schema builder or migration system, so DDL will likely be raw SQL managed outside the package. Acceptable, but it means schema ownership sits with us.

Technical risk

• Adoption risk is the headline. 2 stars, 0 dependents, and effectively a single maintainer means there is no external validation of production use. This is an unproven dependency regardless of code quality.
• Bus factor of one. If the maintainer stops, we fork or replace. Mitigate by keeping the fluent API behind an internal interface so replacement is a one-class change.
• Drift risk. ClickHouse moves fast (new data types, async_insert, lightweight deletes, settings profiles, cluster DDL). Small packages fall behind server releases.
• Injection surface. A string-building fluent layer is a classic injection footgun. Parameter binding / prepared-statement behavior must be proven, not inferred. Same for HTTP-interface auth and TLS handling.
• Supply chain. Few maintainers, low scrutiny. Pin exact versions and review lockfile diffs.
• Positive signal: last release dated 2026-04-19 is recent, suggesting the maintainer is active. Recency does not offset the absence of adoption, but it lowers abandonment probability in the near term.
• The opportunity score (60.14) is a market signal, not a package signal: it suggests a genuine gap for a well-maintained Laravel ClickHouse client. That is an argument for a thin adapter and an exit ramp, not for deep coupling.

Key questions for the spike

1. Which transport — HTTP interface or native TCP? Is the connection reused or per-query?
2. Are values bound as parameters, or interpolated into SQL?
3. Which ClickHouse server versions are tested in CI? Which PHP and Laravel versions?
4. What is the insert path — single-row, batch, async_insert? Any deduplication support?
5. What are the timeout, retry, and error-classification semantics on failure?
6. Is Lumen genuinely supported, or only Laravel (facade/config bootstrapping differs)?
7. License and forkability — can we vendor it if abandoned?
8. Test coverage and CI configuration; is there any integration test against a real ClickHouse?

Integration Approach

Stack fit

• Target PHP 8.x / Laravel 10–11, Composer-managed. Introduce an AnalyticsQueryGateway interface in the domain layer with a ClickhouseBuilderAdapter implementation. The fluent API never leaks past that boundary; callers see intent-shaped methods (eventsByDay, funnelSteps), not builder chains.
• This is the single most important decision: it converts a low-adoption dependency into a swappable detail.

Migration path

• Run a timeboxed spike against a containerized ClickHouse, porting the 5–10 queries that actually matter. If they pass — including parameter binding and type fidelity — adopt for the read path only.
• Keep the write path on the existing driver (or raw SQL) until batch-insert semantics and retry/idempotency behavior are proven. Write-path mistakes are silent and corrupting.
• Maintain a documented fallback to smi2/clickhouse-php or the official client behind the same interface. The adapter pattern makes this a half-day swap.

Compatibility

• Pin an exact package version and pin the ClickHouse server version in CI. Run contract tests against that pinned server on every upgrade.
• Verify Lumen separately if Lumen is in scope; do not assume Laravel parity.
• Treat every ClickHouse server upgrade as a package compatibility event, not a routine infrastructure change.

Sequencing

1. Spike + contract-test harness (one ClickHouse container, parameterized against the real query set).
2. Read-path adapter behind a feature flag, shadow-compared against existing query results.
3. Observability layer: query logging, timing histograms, error classification, slow-query thresholds.
4. Write path, only if the batch/async-insert story holds up.
5. Retire direct SQL from application code; adapter becomes the only entry point.

Operational Impact

Maintenance

• Assume we own this. Budget for vendoring or forking if the maintainer goes quiet; keep the adapter diff small so a fork stays mergeable.
• Maintenance load is dominated by the ClickHouse upgrade treadmill, not by the package's own code. Every server upgrade is a joint test.

Support

• Self-support. No vendor, no SLA, no advisory process for defects. Document a runbook: how to identify the package in a stack trace, how to bypass it with raw SQL in an incident, who owns the fork.
• Security patching is on us to notice. Add the repo to dependency monitoring.

Scaling

• HTTP transport is stateless, so it scales horizontally with PHP workers — no connection pool to exhaust, which is an operational advantage over native TCP here.
• Per-query latency includes connection overhead; measure p95/p99 rather than averages, and keep aggregations server-side. PHP should dispatch heavy queries, not post-process results.
• Enforce max_execution_time, max_memory_usage, and result limits at the config layer, not per call site.

Failure modes

• Query timeout or memory-limit exceeded → dashboards must degrade gracefully rather than throw 500s into the UI.
• Truncated results if LIMIT is misconfigured or silently injected.
• Duplicate rows on insert retry — there is likely no idempotency/dedup token support. Use ReplacingMergeTree or insert tokens if the write path is used.
• Silent type coercion between PHP scalars and ClickHouse types (DateTime64, Decimal, Nullable, LowCardinality). Test these explicitly; they fail quietly.
• Credential exposure via cached config or verbose query logging that captures bound values.
• Error classification is likely coarse — a connection failure and a syntax error may surface identically. Wrap and classify in the adapter.

Ramp-up

• Low for any Laravel developer: the fluent API is familiar within an hour. The real cost is not learning the API but hardening the edges — binding, types, timeouts, retries — roughly one sprint including the adapter and contract tests.
• Onboarding risk concentrates in one or two people who understand ClickHouse semantics; plan for that to be documented rather than tribal.

Recommendation: Conditional adopt. Acceptable as a read-path query builder behind a mandatory adapter and pinned versions; not acceptable as an unmediated, codebase-wide dependency given single-maintainer status and zero dependents.