chore: merge main

Author: jackwotherspoon

.github/workflows/codeql.yaml

@@ -55,16 +55,16 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@012739e5082ff0c22ca6d6ab32e07c36df03c4a4 # v3.22.12
+      uses: github/codeql-action/init@e5f05b81d5b6ff8cfa111c80c22c5fd02a384118 # v3.23.0
       with:
         languages: ${{ matrix.language }}
 
     # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
     # If this step fails, then you should remove it and run the build manually
     - name: Autobuild
-      uses: github/codeql-action/autobuild@012739e5082ff0c22ca6d6ab32e07c36df03c4a4 # v3.22.12
+      uses: github/codeql-action/autobuild@e5f05b81d5b6ff8cfa111c80c22c5fd02a384118 # v3.23.0
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@012739e5082ff0c22ca6d6ab32e07c36df03c4a4 # v3.22.12
+      uses: github/codeql-action/analyze@e5f05b81d5b6ff8cfa111c80c22c5fd02a384118 # v3.23.0
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/scorecard.yaml

@@ -65,6 +65,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@012739e5082ff0c22ca6d6ab32e07c36df03c4a4 # v3.22.12
+        uses: github/codeql-action/upload-sarif@e5f05b81d5b6ff8cfa111c80c22c5fd02a384118 # v3.23.0
         with:
           sarif_file: resultsFiltered.sarif

.github/workflows/tests.yaml

@@ -76,7 +76,7 @@ jobs:
 
       - id: 'auth'
         name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@67e9c72af6e0492df856527b474995862b7b6591 # v2.0.0
+        uses: google-github-actions/auth@f6de81663f7788d05bd15bcce18f0e57f23f0846 # v2.0.1
         with:
           workload_identity_provider: ${{ secrets.PROVIDER_NAME }}
           service_account: ${{ secrets.SERVICE_ACCOUNT }}
@@ -154,7 +154,7 @@ jobs:
 
       - id: 'auth'
         name: 'Authenticate to Google Cloud'
-        uses: google-github-actions/auth@67e9c72af6e0492df856527b474995862b7b6591 # v2.0.0
+        uses: google-github-actions/auth@f6de81663f7788d05bd15bcce18f0e57f23f0846 # v2.0.1
         with:
           workload_identity_provider: ${{ secrets.PROVIDER_NAME }}
           service_account: ${{ secrets.SERVICE_ACCOUNT }}

.kokoro/requirements.txt

@@ -281,9 +281,9 @@ jeepney==0.8.0 \
     # via
     #   keyring
     #   secretstorage
-jinja2==3.1.2 \
-    --hash=sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852 \
-    --hash=sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61
+jinja2==3.1.3 \
+    --hash=sha256:7d6d50dd97d52cbc355597bd845fabfbac3f551e1f99619e39a35ce8c370b5fa \
+    --hash=sha256:ac8bd6544d4bb2c9792bf3a159e80bba8fda7f07e81bc3aed565432d5925ba90
     # via gcp-releasetool
 keyring==23.11.0 \
     --hash=sha256:3dd30011d555f1345dec2c262f0153f2f0ca6bca041fb1dc4588349bb4c0ac1e \

README.md

@@ -34,10 +34,22 @@ Currently supported drivers are:
 
 You can install this library with `pip install`:
 
+### pg8000
+
 ```sh
 pip install "google-cloud-alloydb-connector[pg8000]"
 ```
 
+See [Synchronous Driver Usage](#synchronous-driver-usage) for details.
+
+### asyncpg
+
+```sh
+pip install "google-cloud-alloydb-connector[asyncpg]"
+```
+
+See [Async Driver Usage](#async-driver-usage) for details.
+
 ### APIs and Services
 
 This package requires the following to connect successfully:
@@ -70,7 +82,7 @@ This package provides several functions for authorizing and encrypting
 connections. These functions are used with your database driver to connect to
 your AlloyDB instance.
 
-AlloyDB supports network connectivity through private, internal IP addresses only. 
+AlloyDB supports network connectivity through private, internal IP addresses only.
 This package must be run in an environment that is connected to the
 [VPC Network][vpc] that hosts your AlloyDB private IP address.
 
@@ -79,7 +91,7 @@ Please see [Configuring AlloyDB Connectivity][alloydb-connectivity] for more det
 [vpc]: https://cloud.google.com/vpc/docs/vpc
 [alloydb-connectivity]: https://cloud.google.com/alloydb/docs/configure-connectivity
 
-### How to use this Connector
+### Synchronous Driver Usage
 
 To connect to AlloyDB using the connector, inititalize a `Connector`
 object and call it's `connect` method with the proper input parameters.
@@ -151,7 +163,7 @@ To close the `Connector` object's background resources, call it's `close()` meth
 connector.close()
 ```
 
-### Using Connector as a Context Manager
+### Synchronous Context Manager
 
 The `Connector` object can also be used as a context manager in order to
 automatically close and cleanup resources, removing the need for explicit
@@ -202,6 +214,118 @@ with pool.connect() as db_conn:
         print(row)
 ```
 
+### Async Driver Usage
+
+The AlloyDB Connector is compatible with [asyncio][] to improve the speed and
+efficiency of database connections through concurrency. The `AsyncConnector`
+currently supports the following asyncio database drivers:
+
+- [asyncpg](https://magicstack.github.io/asyncpg)
+
+[asyncio]: https://docs.python.org/3/library/asyncio.html
+
+```python
+import asyncpg
+
+import sqlalchemy
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from google.cloud.alloydb.connector import AsyncConnector
+
+async def init_connection_pool(connector: AsyncConnector) -> AsyncEngine:
+    # initialize Connector object for connections to AlloyDB
+    async def getconn() -> asyncpg.Connection:
+        conn: asyncpg.Connection = await connector.connect(
+            "projects/<YOUR_PROJECT>/locations/<YOUR_REGION>/clusters/<YOUR_CLUSTER>/instances/<YOUR_INSTANCE>",
+            "asyncpg",
+            user="my-user",
+            password="my-password",
+            db="my-db-name"
+            # ... additional database driver args
+        )
+        return conn
+
+    # The AlloyDB Python Connector can be used along with SQLAlchemy using the
+    # 'async_creator' argument to 'create_async_engine'
+    pool = create_async_engine(
+        "postgresql+asyncpg://",
+        async_creator=getconn,
+    )
+    return pool
+
+async def main():
+    connector = AsyncConnector()
+
+    # initialize connection pool
+    pool = await init_connection_pool(connector)
+
+    # example query
+    async with pool.connect() as conn:
+        await conn.execute(sqlalchemy.text("SELECT NOW()"))
+
+    # dispose of connection pool
+    await pool.dispose()
+
+    # close Connector
+    await connector.close()
+
+```
+
+For more details on additional arguments with an `asyncpg.Connection`, please
+visit the [official documentation][asyncpg-docs].
+
+
+[asyncpg-docs]: https://magicstack.github.io/asyncpg/current/api/index.html
+
+### Async Context Manager
+
+The `AsyncConnector` also may be used as an async context manager, removing the
+need for explicit calls to `connector.close()` to cleanup resources.
+
+```python
+import asyncio
+import asyncpg
+
+import sqlalchemy
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from google.cloud.alloydb.connector import AsyncConnector
+
+async def init_connection_pool(connector: AsyncConnector) -> AsyncEngine:
+    # initialize Connector object for connections to AlloyDB
+    async def getconn() -> asyncpg.Connection:
+            conn: asyncpg.Connection = await connector.connect(
+                "projects/<YOUR_PROJECT>/locations/<YOUR_REGION>/clusters/<YOUR_CLUSTER>/instances/<YOUR_INSTANCE>",
+                "asyncpg",
+                user="my-user",
+                password="my-password",
+                db="my-db-name"
+                # ... additional database driver args
+            )
+            return conn
+
+    # The AlloyDB Python Connector can be used along with SQLAlchemy using the
+    # 'async_creator' argument to 'create_async_engine'
+    pool = create_async_engine(
+        "postgresql+asyncpg://",
+        async_creator=getconn,
+    )
+    return pool
+
+async def main():
+    # initialize Connector object for connections to AlloyDB
+    async with AsyncConnector() as connector:
+        # initialize connection pool
+        pool = await init_connection_pool(connector)
+
+        # example query
+        async with pool.connect() as conn:
+            await conn.execute(sqlalchemy.text("SELECT NOW()"))
+
+        # dispose of connection pool
+        await pool.dispose()
+```
+
 ## Support policy
 
 ### Major version lifecycle

google/api/field_behavior_pb2.py

@@ -16,6 +16,7 @@
 # -*- coding: utf-8 -*-
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # source: google/api/field_behavior.proto
+# isort: skip_file
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool

google/cloud/alloydb/connector/__init__.py

@@ -11,8 +11,8 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+from google.cloud.alloydb.connector.async_connector import AsyncConnector
 from google.cloud.alloydb.connector.connector import Connector
 from google.cloud.alloydb.connector.version import __version__
 
-
-__all__ = ["__version__", "Connector"]
+__all__ = ["__version__", "Connector", "AsyncConnector"]