Migrating Google Datastore from V1 to V2

How to upgrade

Update your google/cloud-datastore dependency to ^2.0:

{
    "require": {
        "google/cloud-datastore": "^2.0"
    }
}

Breaking Changes

EntityInterface changes

Types have been added to the methods in EntityInterface. This means that any classes implementing this interface will need to be updated to match the new method signatures:

 class Business implements EntityInterface
 {
     use EntityTrait;

-     public static function mappings()
+     public static function mappings(): array
     {
         return [
             'parent' => Business::class
         ];
     }
 }

Client Options changes

The following ClientOptions have been reorganized. This was done to ensure client options are consistent across all Google Cloud clients.

  • authCache -> Moved to credentialsConfig.authCache
  • authCacheOptions -> Moved to credentialsConfig.authCacheOptions
  • credentialsFetcher -> Moved to credentials
  • keyFile -> Moved to credentials
  • keyFilePath -> Moved to credentials
  • requestTimeout -> Removed from client options and moved to a call option timeoutMillis
  • scopes -> Moved to credentialsConfig.scopes
  • defaultScopes -> Moved to credentialsConfig.defaultScopes
  • quotaProject -> Moved to credentialsConfig.quotaProject
  • httpHandler -> Moved to transportConfig.rest.httpHandler
  • authHttpHandler -> Moved to credentialsConfig.authHttpHandler
  • asyncHttpHandler -> Removed in favor of a single httpHandler option.
  • restOptions -> Moved to transportConfig.rest
  • grpcOptions -> Moved to transportConfig.grpc
  • accessToken -> Removed - This option is no longer supported. Use the $credentialsFetcher option instead.
  • shouldSignRequest -> Removed - obsolete
  • preferNumericProjectId -> Removed - obsolete

Retry Options changes

The retry options have been moved to use RetrySettings in Client Options and in call options.

  • retries -> Renamed to retrySettings.maxRetries
  • restRetryFunction -> Renamed to retrySettings.retryFunction
  • grpcRetryFunction -> Renamed to retrySettings.retryFunction
  • delayFunc/calcDelayFunction -> Removed in favor of the properties retrySettings.initialRetryDelayMillis, retrySettings.retryDelayMultiplier and retrySettings.maxRetryDelayMillis.

Internal changes

We expect these changes to not break existing code, as they have been done in classes marked @internal or as part of refactoring, but to be safe, these changes have been released in a major version.

Types for properties, parameters, and return types.

Types have been added for all properties, parameters and return types. This means that any classes implementing interfaces in this library (specifically, EntityInterface as mentioned above), will need to be updated to match the new method signatures. Typing constraints may have other effects where the incorrect types had been previously applied.

Options array validation

Previously, if unrecognized array keys were passed into methods, these additional arguments would be ignored. Now, a LogicException will be thrown in the OptionsValidator class with the message "Unexpected option(s) provided: [OPTION-NAME]". If you see this exception, and you believe it to be an error, please file an issue in the google-cloud-php repo and let us know.

Connection classes are not used anymore.

The following classes are removed, and have been replaced with the generated GAPIC client Google\Cloud\Datastore\V1\Client\DatastoreClient:

  • Google\Cloud\Datastore\Connection\ConnectionInterface is removed
  • Google\Cloud\Datastore\Connection\Rest is removed
  • Google\Cloud\Datastore\Connection\Grpc is removed

Additionally, the previously generated GAPIC client (Google\Cloud\Datastore\V1\DatastoreClient, which has a similar name to Google\Cloud\Datastore\V1\Client\DatastoreClient, but without the Client namespace) has been removed. For more information, see Migrating to V2.

Constants in Query\Query have been changed from string to int

These constants are used internally, but if they are being used in any code, they will need to be updated:

  • Google\Cloud\Datastore\Query\Query::OP_DEFAULT changed from 'EQUAL' to 5
  • Google\Cloud\Datastore\Query\Query::OP_LESS_THAN changed from 'LESS_THAN' to 1
  • Google\Cloud\Datastore\Query\Query::OP_LESS_THAN_OR_EQUAL changed from 'LESS_THAN_OR_EQUAL' to 2
  • Google\Cloud\Datastore\Query\Query::OP_GREATER_THAN changed from 'GREATER_THAN' to 3
  • Google\Cloud\Datastore\Query\Query::OP_GREATER_THAN_OR_EQUAL changed from 'GREATER_THAN_OR_EQUAL' to 4
  • Google\Cloud\Datastore\Query\Query::OP_EQUALS changed from 'EQUAL' to 5
  • Google\Cloud\Datastore\Query\Query::OP_NOT_EQUALS changed from 'NOT_EQUAL' to 9
  • Google\Cloud\Datastore\Query\Query::OP_IN changed from 'IN' to 6
  • Google\Cloud\Datastore\Query\Query::OP_NOT_IN changed from 'NOT_IN' to 13
  • Google\Cloud\Datastore\Query\Query::OP_HAS_ANCESTOR changed from 'HAS_ANCESTOR' to 11
  • Google\Cloud\Datastore\Query\Query::ORDER_DEFAULT changed from 'ASCENDING' to 1
  • Google\Cloud\Datastore\Query\Query::ORDER_DESCENDING changed from 'DESCENDING' to 2
  • Google\Cloud\Datastore\Query\Query::ORDER_ASCENDING changed from 'ASCENDING' to 1

Protobuf backwards compatibility files have been removed

These class aliases have been deprecated for a very long time, and are finally being removed. Update to the namespaced version (replacing _ with \) to upgrade.

  • Google\Cloud\Datastore\V1\PropertyFilter_Operator has been removed
  • Google\Cloud\Datastore\V1\EntityResult_ResultType has been removed
  • Google\Cloud\Datastore\V1\CommitRequest_Mode has been removed
  • Google\Cloud\Datastore\V1\CompositeFilter_Operator has been removed
  • Google\Cloud\Datastore\V1\TransactionOptions_ReadWrite has been removed
  • Google\Cloud\Datastore\V1\QueryResultBatch_MoreResultsType has been removed
  • Google\Cloud\Datastore\V1\TransactionOptions_ReadOnly has been removed
  • Google\Cloud\Datastore\V1\PropertyOrder_Direction has been removed
  • Google\Cloud\Datastore\V1\AggregationQuery_Aggregation has been removed
  • Google\Cloud\Datastore\V1\ReadOptions_ReadConsistency has been removed
  • Google\Cloud\Datastore\V1\Key_PathElement has been removed
  • Google\Cloud\Datastore\V1\AggregationQuery_Aggregation_Count has been removed