Cloud Bigquery Connection Laravel Package

Product Decisions This Supports

• Federated-query / external-data strategy: This package is the control plane for BigQuery connections — the objects that let BigQuery read Cloud SQL, Spanner, BigLake, and (allowlisted) Salesforce or Spark sources. If the roadmap includes "join our Postgres data with warehouse data without an ETL copy," connections are a prerequisite, and this is the SDK that provisions them.
• Build vs. buy on integration glue: The alternative is hand-rolling REST calls to the BigQuery Connection API or driving it through the gcloud/Terraform CLIs from application code. This package is a Google-generated, GA-versioned client under Apache-2.0 — adopting it removes custom auth, retry, and transport code from our maintenance surface.
• Self-service provisioning: If customers or internal teams should create their own warehouse connections from our Laravel admin UI rather than filing a ticket to the data team, this package is what makes that a product feature instead of a runbook.
• Multi-tenant credential lifecycle: Per-tenant service accounts, Cloud SQL credentials, and connection rotation become automatable app workflows (create → validate → rotate → delete) instead of manual console operations. That is a support-cost and security-posture decision as much as a technical one.
• IaC boundary decision: Where does infrastructure end and product begin? If connections are tenant-scoped and created at runtime, they belong in the app and this package is justified. If connections are static per environment, Terraform owns them and this package is dead weight.
• Roadmap sequencing: Treat it as a dependency, not a feature. It should appear in planning as an enabler under an analytics/connectors epic, never as a standalone deliverable — there is no user-visible outcome from "we integrated a client library."

Important scoping note for planning: this package manages connections; it does not run queries. Query execution lives in google/cloud-bigquery. Any roadmap item pitched as "query external data from BigQuery" requires both, plus a decision about where the SQL is authored. Internal write-ups that describe this library as enabling federated queries or streaming result sets overstate it — correct that before it reaches a steering deck.

When to Consider This Package

Adopt it when all of the following hold:

• The backend is PHP/Laravel and GCP-native, with BigQuery already an approved platform.
• Connections must be created, inspected, updated, or deleted by the application at runtime — provisioning during onboarding, per-tenant isolation, or automated rotation.
• The team accepts Google Cloud IAM/service-account auth and can store credentials in Secret Manager or an equivalent, not in .env on a shared box.
• Something downstream will actually consume the connection (a query job, a scheduled transfer, a data team's dbt run). A connection nobody queries is pure overhead.
• Engineering can absorb protobuf-shaped responses — or is willing to wrap them in DTOs — rather than expecting Eloquent-like ergonomics.

Look elsewhere when:

• You only need to query BigQuery. Use google/cloud-bigquery; this package adds nothing.
• Connections are static per environment. A Terraform module or a one-time console setup is cheaper, reviewable, and auditable. Do not put infrastructure in a request cycle just because an SDK exists.
• You need scheduled queries, data transfers, or dataset/table DDL. Those are different APIs (bigquerydatatransfer, bigquery) this package does not cover.
• The platform isn't GCP, or the data platform team is standardized on Python/dbt/Airflow. Fighting that with a PHP admin client creates two sources of truth.
• You need streaming or sub-second latency. Connection management is a low-frequency admin operation with no meaningful performance dimension — but if you were hoping gRPC support here buys you fast data reads, it does not.
• gRPC is a hard dependency you can't meet. REST works, but verify the PHP gRPC extension can be installed in your runtime before designing around streaming claims.

Adoption risk to price in: 3 GitHub stars and 0 dependents. This is not a signal of poor quality — it is a generated component inside the googleapis/google-cloud-php monorepo, where issues and releases are centralized, and it has been GA since v1.0.0 with a major v2 line. It is a signal that you will find no community answers, no third-party tutorials, and no Stack Overflow safety net. Your team's only support channel is Google's own docs and issue tracker. Budget for that: assume one engineer owns this integration and writes the internal usage note, because nobody outside will have done it before.

How to Pitch It (Stakeholders)

To executives: We can let customers and internal teams connect their own operational databases to BigQuery from inside our product, instead of routing every request through the data team. The package itself is free, Apache-2.0 licensed, Google-maintained, and marked generally available — so we are not betting on a hobby project, and the license carries no commercial exposure. It is a small piece of plumbing that unlocks a larger capability: external data becomes addressable by our application. The business case is not the library, it is the ticket queue and the manual credential rotation we stop doing.

To engineering: It is a generated ConnectionServiceClient with typed request/response objects, REST or gRPC, and a constructor that drops cleanly into Laravel's service container. Auth is standard Google service-account flow. Plan to wrap it behind our own interface — one adapter class returning our DTOs — so protobuf types don't leak into controllers, and so we are insulated if the API surface shifts. Two concrete cautions: it manages connections and does nothing else (queries are a separate package), and there is effectively no community usage, so read the official reference docs rather than searching.

To security and platform: This package writes credentials-bearing resources through a network call, so it forces us to answer questions we should answer anyway — where service account keys live, whether connection creation is logged and attributable, and how rotation happens when a credential is compromised. Framing it as "the thing that makes rotation a scheduled job instead of a calendar reminder" is usually the argument that lands.

Decision requested: approve it as an internal dependency for the connectors epic, scoped to runtime connection management only, with the explicit understanding that query execution is a separate adoption and a separate conversation.