- How do I install and configure phpclickhouse-laravel in a Laravel application?
- Install it with Composer, then publish the package config and add a ClickHouse connection to config/database.php using environment variables for host, port, database, and credentials. Once the service provider is registered, you can resolve the connection through the container or use the provided facade. Because the package is a thin adapter over smi2/phpClickHouse, most connection settings map directly to that client's options. Keep the published config in version control and review changes like any other production configuration.
- Which Laravel and PHP versions does this package support?
- There is no broad compatibility matrix published, so check the composer.json constraints in the repository against your Laravel and PHP versions before adopting. The package is a small service-provider adapter, which means its constraints are mostly driven by the Laravel components it references and by smi2/phpClickHouse. Treat version support as something to verify in a short spike rather than something to assume, especially if you are on an older Laravel release or a very new PHP version.
- Does phpclickhouse-laravel support Eloquent models and relationships?
- It provides Eloquent-style models for working with ClickHouse tables, but it is not a full ORM replacement. ClickHouse is a columnar analytical store, so you should not expect per-row updates and deletes, relationship loading, casts, or model events the way you get them on MySQL or Postgres. Use these models for read-heavy analytics and keep your transactional, relational data in your primary Laravel database.
- How do I run raw SQL or use the query builder against ClickHouse?
- You can run raw SQL through the connection and use the query builder against ClickHouse tables. Parameter bindings are supported, but you should still review any dynamically composed SQL carefully, since ClickHouse queries often involve large scans and expensive aggregations. Set expectations around timeouts and result sizes up front, because a careless unbounded SELECT can pull far more rows than a typical Laravel query would. Put a gateway class in front of these calls so raw SQL does not leak into domain code.
- Can I use Laravel migrations to manage ClickHouse table schemas?
- The package adds schema support so you can create and alter ClickHouse tables from Laravel, but do not assume you get the full migration versioning workflow you are used to with relational databases. ClickHouse DDL is different, and schema evolution should be an owned, reviewed process rather than something that runs automatically on every deploy. Validate the exact DDL behavior your package version supports in a test environment before relying on it.
- How do I insert large datasets efficiently into ClickHouse from Laravel?
- ClickHouse is designed for batched inserts, so avoid inserting one row at a time and instead send data in reasonably sized chunks. The underlying smi2/phpClickHouse client handles the actual insert mechanics, and the Laravel adapter simply exposes it through the container and connection layer. Plan batching, error handling, and retry behavior explicitly, because a failed bulk insert needs to be observable and recoverable. Pair ingestion with a dedicated write connection and credentials rather than reusing a read-only reporting connection.
- Is this package safe to use with Laravel Octane and long-running queue workers?
- That is one of the main unknowns you should test rather than assume. Long-lived workers and Octane keep connections alive across requests, so you need to verify connection reuse, stale socket handling, and reconnection behavior against your ClickHouse topology. Run a timeboxed spike that exercises sustained traffic and idle periods, then add a health check and monitoring before putting it behind production reporting.
- Can I configure multiple ClickHouse connections or separate read and write credentials?
- The package sits on top of Laravel's database connection configuration, so defining multiple named connections is the natural approach. A common pattern is a read-only reporting connection plus a separate write connection used only by your ingestion code. Whether TLS, native TCP, or cluster-specific auth modes are fully covered depends on smi2/phpClickHouse rather than this adapter, so confirm protocol and auth support against your ClickHouse server version during evaluation.
- How do I test code that queries ClickHouse in a Laravel test suite?
- There is no built-in fake for ClickHouse, so the practical approach is to hide the package behind an interface such as an AnalyticsRepository or ClickHouseGateway and swap in an in-memory implementation for unit tests. For integration tests, run a real ClickHouse instance in CI and assert against known fixture data. Testing the gateway boundary rather than mocking the facade keeps your domain code testable and makes replacing the underlying client a contained change.
- How does phpclickhouse-laravel compare to using smi2/phpClickHouse directly, and is it actively maintained?
- This package is a thin Laravel adapter, so using smi2/phpClickHouse directly costs you mainly the config, container binding, and facade convenience it provides. Maintenance signals are modest, with a small star count and effectively a single maintainer, so verify release cadence and responsiveness directly on the repository rather than trusting index metadata. The upside is that the code surface is small and MIT licensed, which makes forking realistic if you need to patch it, though forking is a real ongoing cost rather than a free safety net.