Laravel Bigquery Laravel Package

Product Decisions This Supports

• Build vs. buy for analytics surface area. If the organization already runs BigQuery and the application is Laravel, this package is the cheapest possible bridge between the two: one composer require, one connection block in config/database.php, one service-account key. It converts "we need an admin dashboard over warehouse data" from a multi-sprint integration project into days of work. The decision it informs is narrow but real: do we duplicate analytics data into the OLTP database, or read the warehouse directly? This package makes the second option cheap enough to actually evaluate.
• Roadmap sequencing for internal reporting. The package's fit is read-heavy, authenticated, internal surfaces — usage dashboards, cohort/retention views, back-office aggregation, support tooling. That is exactly the class of feature that usually sits at the bottom of a roadmap because the integration cost is disproportionate to the customer value. Lowering that cost is a scheduling decision: internal reporting can move up a quarter without competing for platform engineering time.
• Deferring the data-warehouse platform team. It lets a product team ship warehouse-backed features without waiting on an internal "analytics API" service. That is a genuine velocity unlock, but it is also a fragmentation decision — it creates a second path to BigQuery that a future platform team will have to consolidate. Worth naming explicitly when the roadmap is set rather than discovering it later.
• Not a decision this supports: replacing the primary database, powering end-user-facing transactional features, satisfying read-after-write consistency, or any feature with a sub-second latency SLO. If a proposal looks like any of those, the tool has been misread.
• Feature-level go/no-go that should be gated on a spike, not a README. Three questions decide whether any given feature is viable: do the actual queries (joins, aggregates, partition-filtered WHEREs) translate cleanly; do the Eloquent casts round-trip NUMERIC/BIGNUMERIC/TIMESTAMP losslessly; and do we have cost guardrails outside this package. The cast question is the one most likely to kill a feature quietly rather than loudly.

When to Consider This Package

Adopt when all of these hold:

• Laravel 11 or 12 application, already on google/cloud-bigquery-provisioned infrastructure with dataset governance and billing in place.
• The use case is read-mostly and analytical — dashboards, reporting, aggregations — sitting behind an authenticated internal surface where a few seconds of latency is acceptable.
• The team is small and Laravel-fluent; the query surface is already familiar and nobody wants to learn a second query DSL for four queries.
• You can afford to treat this as adopt-with-a-fork-plan: a named second connection, all package-specific code isolated behind a query-object or repository boundary, and a documented trigger for replacing it with a thin wrapper over the official SDK.
• Credential handling can be made deliberate — key sourced from a secrets manager at deploy, a rotation runbook, never committed.

Look elsewhere when any of these hold:

• The feature is customer-facing or on a request path. No cost estimation, no dry-run, no job monitoring, no cancellation, no BigQuery-tuned pagination, no retry semantics. Those gaps are what separate a demo from a production surface.
• Query cost is material. BigQuery bills on bytes scanned. A query builder with no default LIMIT and no maximum_bytes_billed makes SELECT * feel free. If a single unbounded query is a real invoice, that guardrail has to live outside the package — or the query shouldn't run from PHP at all.
• Data correctness is load-bearing. NUMERIC/BIGNUMERIC precision and TIMESTAMP timezone handling are the highest-severity failure mode here: a wrong cast doesn't throw, it produces plausible numbers that are off by cents or hours, and it surfaces in an invoice or a board deck. Release history includes escaping fixes (1.5.1, 1.5.2) — a query builder with recent string-escaping bugs is a security signal, and any user-supplied value reaching a where clause needs independent review.
• Provenance matters. Four stars, zero dependents, single maintainer, one-line release notes. You will be the first serious adopter, which makes your team the de facto QA function.
• Your Laravel upgrade calendar is tight. Releases track Laravel majors, not your schedule — v2.0.0 exists solely to add Laravel 12. If the maintainer goes quiet, your framework upgrade blocks on a fork you now own.
• A scheduled job writing to a cache table would do. Often the honest answer is that the query doesn't belong in the PHP request cycle at all.

How to Pitch It (Stakeholders)

To executives: We can ship internal analytics features — usage dashboards, cohort reporting, back-office aggregation — on top of the warehouse we already pay for, without a new service and without duplicating data into the application database. It's a small, MIT-licensed, drop-in connection driver: days of work rather than a multi-sprint integration. The ask is a scoped pilot behind an internal, authenticated surface, with three guardrails: all warehouse code isolated behind one boundary so it's replaceable, a project-level billing quota we control independently, and a verified round-trip test on money and timestamp fields before anything ships. I'm not proposing this for customer-facing features or for anything that replaces the primary database — the risk profile doesn't support that, and I'd flag anyone who suggested it.

To engineering: It registers as a Laravel database driver, which is the right seam — DB::connection('bigquery'), Model::on('bigquery'), and the whole query surface come for free, no new SDK, no new auth model. The genuinely valuable part is the cast layer for BigQuery types including repeated and struct fields; hand-rolling that is where precision and timezone bugs live. The tradeoff is that Eloquent's OLTP assumptions — transactions, incrementing keys, timestamps, save() round-trips — don't hold, so the README's own example model disables them. Our answer is: use the Query Builder for reporting, reserve models for genuine read models, and put every package-specific line behind app/Queries/BigQuery/* so "replace the package" is a swap and not a refactor. Two things to price in honestly: we're the first serious adopter of a four-star package, so we own QA; and there's no dry-run or cost estimation, so the byte-scan guardrail has to be configured outside this package before the first query runs.