{"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":"en","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,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}