Cloud Bigquery Reservation Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require google/cloud-bigquery-reservation
   

   Ensure your Laravel project uses PHP 8.1+ (package requirement).

2. Authentication: Configure Google Cloud credentials via:

   • Environment variable (GOOGLE_APPLICATION_CREDENTIALS pointing to a service account JSON file)
   • Laravel's .env:

     GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
     

   Or use the Laravel Google Cloud SDK for centralized auth.

3. First Use Case: Fetch a reservation by name (e.g., projects/{project}/locations/{location}/reservations/{reservation}):

   use Google\Cloud\BigQuery\Reservation\V1\Client\ReservationServiceClient;
   
   $client = new ReservationServiceClient();
   $reservation = $client->getReservation(
       (new \Google\Cloud\BigQuery\Reservation\V1\GetReservationRequest())
           ->setName('projects/my-project/locations/us/reservations/my-reservation')
   );
   

Key Entry Points

• Client: ReservationServiceClient (primary interface)
• Models: Reservation, Assignment, CapacityCommitment, Autoscale
• Async Methods: All methods have async variants (e.g., getReservationAsync())

Implementation Patterns

Common Workflows

1. Reservation Management

• Create/Update:

  $reservation = (new \Google\Cloud\BigQuery\Reservation\V1\Reservation())
      ->setDisplayName('Production Slot Pool')
      ->setSlotCapacity(1000)
      ->setAutoscale((new \Google\Cloud\BigQuery\Reservation\V1\Autoscale())
          ->setMaxSlots(5000)
          ->setMinSlots(100));
  
  $client->createReservation(
      (new \Google\Cloud\BigQuery\Reservation\V1\CreateReservationRequest())
          ->setParent('projects/my-project/locations/us')
          ->setReservation($reservation)
  );
  

• List Reservations:

  $reservations = $client->listReservations(
      (new \Google\Cloud\BigQuery\Reservation\V1\ListReservationsRequest())
          ->setParent('projects/my-project/locations/us')
  );
  

2. Assignment Management

• Assign a Dataset to a Reservation:

  $assignment = (new \Google\Cloud\BigQuery\Reservation\V1\Assignment())
      ->setAssignmentType('SPECIFIC_QUERY')
      ->setProjectId('my-project')
      ->setDatasetId('analytics');
  
  $client->createAssignment(
      (new \Google\Cloud\BigQuery\Reservation\V1\CreateAssignmentRequest())
          ->setParent('projects/my-project/locations/us/reservations/my-reservation')
          ->setAssignment($assignment)
  );
  

3. Capacity Commitments

• Commit Slots:

  $commitment = (new \Google\Cloud\BigQuery\Reservation\V1\CapacityCommitment())
      ->setSlotCapacity(5000)
      ->setCommitmentStartTime('2023-01-01T00:00:00Z')
      ->setCommitmentEndTime('2024-01-01T00:00:00Z');
  
  $client->createCapacityCommitment(
      (new \Google\Cloud\BigQuery\Reservation\V1\CreateCapacityCommitmentRequest())
          ->setParent('projects/my-project/locations/us/reservations/my-reservation')
          ->setCapacityCommitment($commitment)
  );
  

4. IAM Integration

• Get/Set Policies:

  $policy = $client->getIamPolicy(
      (new \Google\Cloud\BigQuery\Reservation\V1\GetIamPolicyRequest())
          ->setResource('projects/my-project/locations/us/reservations/my-reservation')
  );
  
  $updatedPolicy = $policy->addBinding(
      (new \Google\Cloud\Iam\V1\Binding())
          ->setRole('roles/bigquery.reservationAdmin')
          ->setMembers(['user:admin@example.com'])
  );
  
  $client->setIamPolicy(
      (new \Google\Cloud\BigQuery\Reservation\V1\SetIamPolicyRequest())
          ->setResource('projects/my-project/locations/us/reservations/my-reservation')
          ->setPolicy($updatedPolicy)
  );
  

5. Disaster Recovery

• Replication Status:

  $reservation = $client->getReservation(
      (new \Google\Cloud\BigQuery\Reservation\V1\GetReservationRequest())
          ->setName('projects/my-project/locations/us/reservations/my-reservation')
  );
  $replicationStatus = $reservation->getReplicationStatus();
  

Laravel Integration Tips

1. Service Provider: Bind the client to Laravel's container in AppServiceProvider:

   public function register()
   {
       $this->app->singleton(ReservationServiceClient::class, function () {
           return new ReservationServiceClient();
       });
   }
   

2. Facade (Optional): Create a facade for cleaner syntax:

   // app/Facades/BigQueryReservation.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   use Google\Cloud\BigQuery\Reservation\V1\Client\ReservationServiceClient;
   
   class BigQueryReservation extends Facade
   {
       protected static function getFacadeAccessor()
       {
           return ReservationServiceClient::class;
       }
   }
   

3. Job Queues: Offload long-running operations (e.g., reservation creation) to queues:

   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   use Illuminate\Foundation\Bus\Dispatchable;
   
   class CreateBigQueryReservation implements ShouldQueue
   {
       use Dispatchable, Queueable;
   
       public function handle()
       {
           $client = app(ReservationServiceClient::class);
           // ... reservation logic
       }
   }
   

4. Event Listeners: Trigger actions on reservation changes (e.g., notify team when slots are low):

   // app/Listeners/MonitorReservationSlots.php
   public function handle()
   {
       $reservation = $client->getReservation(...);
       if ($reservation->getAutoscale()->getCurrentSlots() > $reservation->getAutoscale()->getMaxSlots() * 0.9) {
           // Send alert
       }
   }
   

Gotchas and Tips

Pitfalls

1. Authentication:

   • Gotcha: Forgetting to set GOOGLE_APPLICATION_CREDENTIALS or using invalid credentials will throw Google\Auth\Exception\GoogleAuthException.
   • Fix: Validate credentials early in your application's bootstrap (e.g., bootstrap/app.php):

     if (!file_exists($credentialsPath = env('GOOGLE_APPLICATION_CREDENTIALS'))) {
         throw new \RuntimeException("Google Cloud credentials not found at {$credentialsPath}");
     }
     

2. Resource Names:

   • Gotcha: Incorrectly formatted resource names (e.g., missing locations/ or projects/).
     • Correct: projects/my-project/locations/us/reservations/my-reservation
     • Incorrect: my-project/us/my-reservation
   • Fix: Use the formatReservationName() helper from the client:

     $formattedName = ReservationServiceClient::formatReservationName(
         'my-project',
         'us',
         'my-reservation'
     );
     

3. Slot Capacity:

   • Gotcha: Autoscale.currentSlots can temporarily exceed Autoscale.maxSlots if maxSlots is reduced. This is expected behavior but may cause unexpected billing.
   • Tip: Monitor currentSlots vs. maxSlots in your application logic:

     $autoscale = $reservation->getAutoscale();
     if ($autoscale->getCurrentSlots() > $autoscale->getMaxSlots()) {
         logger()->warning('Autoscale slots exceeded max capacity');
     }
     

4. IAM Permissions:

   • Gotcha: Missing permissions (e.g., bigquery.reservationAdmin) will result in PERMISSION_DENIED errors.
   • Fix: Grant roles via Google Cloud Console or programmatically:

     $client->setIamPolicy((new \Google\Cloud\BigQuery\Reservation\V1\SetIamPolicyRequest())
         ->setResource($reservationName)
         ->setPolicy($policy->addBinding((new \Google\Cloud\Iam\V1\Binding())
             ->setRole('roles/bigquery.reservationAdmin')
             ->setMembers(['serviceAccount: