{"id":6652,"library":"gcloud-aio-datastore","title":"Asynchronous Google Cloud Datastore Client","description":"gcloud-aio-datastore is an asynchronous Python client for interacting with Google Cloud Datastore. It's part of the `gcloud-aio` monorepo, which provides async interfaces for various Google Cloud services (Datastore, Storage, Pub/Sub, Auth, etc.). This library wraps the official `google-cloud-datastore` client with an `asyncio` interface. The project is actively maintained, with components releasing independently but frequently.","status":"active","version":"9.1.0","language":"python","source_language":"en","source_url":"https://github.com/talkiq/gcloud-aio","tags":["google cloud","datastore","asyncio","gcp","database","nosql"],"install":[{"cmd":"pip install gcloud-aio-datastore","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Handles authentication for all gcloud-aio clients.","package":"gcloud-aio-auth","optional":false},{"reason":"Provides core utilities and base classes for gcloud-aio clients.","package":"gcloud-aio-core","optional":false},{"reason":"Underlying synchronous Google Cloud Datastore client, which gcloud-aio-datastore wraps.","package":"google-cloud-datastore","optional":false}],"imports":[{"symbol":"Datastore","correct":"from gcloud.aio.datastore import Datastore"},{"symbol":"Key","correct":"from gcloud.aio.datastore import Key"},{"symbol":"Query","correct":"from gcloud.aio.datastore import Query"}],"quickstart":{"code":"import asyncio\nimport os\nfrom gcloud.aio.auth import build_from_service_account\nfrom gcloud.aio.datastore import Datastore, Key, Query\n\nasync def main():\n    project = os.environ.get('GCP_PROJECT', 'your-gcp-project-id')\n    service_account_info = os.environ.get('GCP_SERVICE_KEY') # or path via GCP_SERVICE_KEY_PATH\n\n    if not project or not service_account_info:\n        print(\"Please set GCP_PROJECT and GCP_SERVICE_KEY environment variables.\")\n        return\n\n    # Credentials can also be built from a path using build_from_service_account_path()\n    creds = build_from_service_account(service_account_info)\n    \n    async with Datastore(project=project, credentials=creds) as client:\n        # 1. Create an entity\n        kind = 'MyEntity'\n        name = 'my-unique-entity-name'\n        key = Key([kind, name], project=project)\n        \n        entity_data = {\n            'property1': 'value1',\n            'property2': 123\n        }\n        await client.put_entity(key, entity_data)\n        print(f\"Created/updated entity: {key.path[0]['id']}\")\n\n        # 2. Get an entity\n        retrieved_entity = await client.get_entity(key)\n        if retrieved_entity:\n            print(f\"Retrieved entity: {retrieved_entity.properties}\")\n        else:\n            print(f\"Entity {key.path[0]['id']} not found.\")\n\n        # 3. Run a query\n        query = Query(kind=kind, project=project)\n        results = await client.run_query(query)\n        print(\"Query results:\")\n        for entity in results:\n            print(f\"  Kind: {entity.kind}, ID: {entity.id}, Properties: {entity.properties}\")\n\n        # 4. Delete an entity (optional cleanup)\n        # await client.delete_entity(key)\n        # print(f\"Deleted entity: {key.path[0]['id']}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to initialize the Datastore client using service account credentials, create, retrieve, and query entities. Ensure `GCP_PROJECT` is set to your Google Cloud project ID and `GCP_SERVICE_KEY` is set to your service account key JSON string (or path via `GCP_SERVICE_KEY_PATH`) in the environment. The client uses `async with` for proper resource management."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer. If you must use Python 3.9, pin `gcloud-aio-auth` to `<5.4.4` (e.g., `gcloud-aio-auth<5.4.4,>=5.0.0`) in your requirements, although this might prevent future security updates for `gcloud-aio-auth`.","message":"Python 3.9 support was dropped by `gcloud-aio-auth` in version `5.4.4`. While `gcloud-aio-datastore 9.1.0` lists `Python >= 3.9` as compatible, installing `gcloud-aio-auth >= 5.4.4` (which is within `gcloud-aio-datastore`'s dependency range `<6.0.0,>=5.0.0`) will lead to compatibility issues for Python 3.9 users.","severity":"breaking","affected_versions":"gcloud-aio-datastore >= 9.1.0 (when combined with gcloud-aio-auth >= 5.4.4)"},{"fix":"Migrate your authentication setup to use `gcloud.aio.auth.build_from_service_account()` and pass the resulting credentials object directly to the `Datastore` constructor. Refer to the quickstart example for the updated pattern.","message":"Version 9.0.0 of `gcloud-aio-datastore` removed the `Datastore.from_service_account()` and `Datastore.from_dict()` convenience constructors. Authentication should now be handled explicitly by building credentials via `gcloud.aio.auth.build_from_service_account()` and passing them to the `Datastore` client constructor.","severity":"breaking","affected_versions":"gcloud-aio-datastore >= 9.0.0"},{"fix":"Ensure your code uses `async def` functions and `await` for all `gcloud-aio-datastore` calls. Run your main `async` function using `asyncio.run()`.","message":"This library is entirely asynchronous (`aio`). All client methods are `await`able coroutines and must be called within an `asyncio` event loop. Attempting to call them synchronously will result in `RuntimeError: 'coroutine' object is not awaited`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check the `requires_dist` for specific `gcloud-aio-*` packages on PyPI to understand their compatible version ranges for dependencies. Use a dependency manager like `pip-tools` or `Poetry` to ensure a consistent environment.","message":"The `gcloud-aio` project is a monorepo, meaning individual client libraries like `gcloud-aio-datastore`, `gcloud-aio-storage`, and `gcloud-aio-auth` have independent versioning. Upgrading one component does not automatically upgrade others, and you must manage dependencies for each sub-package carefully to avoid version conflicts or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify your environment variables or direct arguments for authentication. Debug authentication issues by ensuring `build_from_service_account` successfully returns credentials before initializing the Datastore client.","message":"Authentication relies on `gcloud-aio-auth`. It primarily supports service account keys (JSON string or path). Ensure `GCP_PROJECT` and `GCP_SERVICE_KEY` (or `GCP_SERVICE_KEY_PATH`) environment variables are correctly configured or explicitly passed to `build_from_service_account`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'activ':61 'aio':8,28 'async':32 'asynchron':1,12 'asyncio':56,72 'auth':42 'client':5,14,53 'cloud':3,19,37,51,70 'compon':64 'databas':74 'datastor':4,9,20,39,52,71 'etc':43 'frequent':68 'gcloud':7,27 'gcloud-aio':26 'gcloud-aio-datastor':6 'gcp':73 'googl':2,18,36,50,69 'google-cloud-datastor':49 'independ':66 'interact':16 'interfac':33,57 'librari':45 'maintain':62 'monorepo':29 'nosql':75 'offici':48 'part':23 'project':59 'provid':31 'pub/sub':41 'python':13 'releas':65 'servic':38 'storag':40 'various':35 'wrap':46","created_at":"2026-04-15T18:37:06.981965+00:00","updated_at":"2026-04-16T15:13:23.346624+00:00","problems":[{"fix":"Ensure the library is correctly installed using pip: `pip install gcloud-aio-datastore` or if using `gcloud-rest-datastore`, `pip install gcloud-rest-datastore`.","cause":"This error occurs when the `gcloud-aio-datastore` package is not installed or is not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'gcloud.aio.datastore'"},{"fix":"Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file (e.g., `export GOOGLE_APPLICATION_CREDENTIALS=\"/path/to/key.json\"`), or authenticate via the gcloud CLI by running `gcloud auth application-default login`.","cause":"This error indicates that your application cannot find the necessary Google Cloud credentials to authenticate with Datastore, often due to missing `GOOGLE_APPLICATION_CREDENTIALS` environment variable or not having run `gcloud auth application-default login`.","error":"google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials."},{"fix":"Prepend the call to the asynchronous function with `await`. For example, instead of `client.get(key)`, use `await client.get(key)`. Ensure your code runs within an `async` function and an `asyncio` event loop.","cause":"This error happens when you call an asynchronous function (coroutine) from `gcloud-aio-datastore` without using the `await` keyword, which is required for `asyncio` operations.","error":"TypeError: object ... is not awaitable"},{"fix":"Pin `google-api-core` to a compatible version (e.g., `google-api-core==1.17.0`) and/or ensure `grpcio` and `google-cloud-datastore` are updated to their latest compatible versions by running `pip install --upgrade google-cloud-datastore grpcio` and checking the project's dependencies for specific requirements.","cause":"This `AttributeError` typically arises from a version incompatibility between the `google-cloud-datastore` library (which `gcloud-aio-datastore` wraps) and its `grpcio` dependency. It suggests that a newer version of `google-cloud-datastore` expects a `grpcio` feature that an older `grpcio` version does not provide.","error":"AttributeError: module 'grpc.experimental.aio' has no attribute 'StreamUnaryCall'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"9.1.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/talkiq/gcloud-aio","docs":null,"changelog":null,"pypi":"https://pypi.org/project/gcloud-aio-datastore/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp","database","http-networking","observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}