- How do I install and configure oralunal/phpclickhouse-laravel in a Laravel app?
- Install the package with Composer using composer require oralunal/phpclickhouse-laravel. Publish its config, then add a ClickHouse connection in config/database.php with your host, port, database, username, and password. After that you can run analytical queries through Laravel's DB facade or use the package's Eloquent model support.
- Can I use Laravel Eloquent models and the DB facade with ClickHouse?
- Yes. The package is designed to expose ClickHouse through Laravel's query builder and Eloquent conventions, so you can query analytical data using familiar Laravel patterns. It also supports query features such as FINAL, PREWHERE, SAMPLE, ARRAY JOIN, and SETTINGS. Keep in mind that ClickHouse is an OLAP store, so it fits reporting and append-heavy workloads better than normal CRUD flows.
- What ClickHouse query features does this Laravel package support?
- The package supports Laravel query builder access to ClickHouse features including FINAL, PREWHERE, SAMPLE, ARRAY JOIN, and SETTINGS. It also covers migrations, sessions, parallel queries, and cluster support. These features are aimed at analytical queries rather than transactional application workloads.
- Is oralunal/phpclickhouse-laravel suitable for normal CRUD or transactional workloads?
- No, it is a poor fit as a general-purpose second database behind normal CRUD flows. ClickHouse does not offer traditional transactions or row-level UPDATE and DELETE semantics in the way Laravel developers expect. Use this package for analytics, reporting, telemetry ingestion, aggregations, and large append-only fact tables instead.
- Does the package support ClickHouse migrations and model generation?
- Yes. Version 4.2.0 adds make:clickhouse-model and make:clickhouse-migration generators, which reduce the need to hand-write ClickHouse DDL and model scaffolding. This is especially useful for teams that are unfamiliar with ClickHouse schema conventions. The package also includes upgrade tooling for moving from v3 to v4.
- How does the PHPStan and Larastan extension help with ClickHouse models?
- The PHPStan extension brings ClickHouse column-level types into static analysis, which is valuable when a Laravel app uses both a transactional database and an analytical store. It can help catch type mismatches before runtime. The release notes imply it can read migration files offline, which is good for hermetic CI, but confirm that behavior with the maintainer.
- Why are Float32, Float64, MATERIALIZED, and ALIAS columns treated as nullable under read-only connections?
- Version 4.2.0 improves typing for ClickHouse schemas that diverge from standard Laravel assumptions. On read-only connections, Float32 and Float64 become nullable, and MATERIALIZED and ALIAS columns are treated as nullable. That is more accurate for static analysis, but it can widen types downstream and surface new PHPStan errors in code that assumed non-null values.
- Does the package support ClickHouse clusters and replicated setups?
- The package advertises cluster support, sessions, and parallel queries, and v4.2.0 includes read-only connection awareness for replicated topologies. You should still confirm ON CLUSTER and Replicated engine support against your target ClickHouse server versions. Ask the maintainer which server versions are tested and whether write paths are tested against a real ClickHouse instance.
- What Laravel and PHP versions are supported by oralunal/phpclickhouse-laravel?
- Check the package's composer.json constraints and CI matrix for the exact Laravel and PHP versions supported. The release context raises Laravel 10, 11, and 12 along with PHP 8.2 and 8.3 as questions to verify, but the provided excerpt does not include a definitive compatibility table. Do not assume support for a specific Laravel or PHP version without confirming it in the repository.
- What production and maintenance risks should I know before adopting this package?
- This is a community package with a single-maintainer profile and a rapid minor-release cadence, so pin versions and review changelogs before upgrading. A meaningful part of its correctness story depends on PHPStan and Larastan being wired into CI; teams without static analysis lose much of that benefit. The v4.2.0 release also includes a public API deprecation, and the v3-to-v4 upgrade tool now only suggests schema:dump for tables without a creating migration, so re-verify your dump set. Test critical write paths against a real ClickHouse instance and check maintainer responsiveness on issues.