cloud-sql-python-connector 1.9.2__py2.py3-none-any.whl → 1.11.0__py2.py3-none-any.whl

{cloud_sql_python_connector-1.9.2.dist-info → cloud_sql_python_connector-1.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloud-sql-python-connector
-Version: 1.9.2
+Version: 1.11.0
 Summary: The Cloud SQL Python Connector is a library that can be used alongside a database driver to allow users with sufficient permissions to connect to a Cloud SQL database without having to manually allowlist IPs or manage SSL certificates.
 Home-page: https://github.com/GoogleCloudPlatform/cloud-sql-python-connector
 Author: Google LLC
@@ -207,9 +207,10 @@ To close the `Connector` object's background resources, call its `close()` metho
 connector.close()
 ```
 
-**Note**: For more examples of using SQLAlchemy to manage connection pooling with the connector, please see [Cloud SQL SQLAlchemy Samples](https://cloud.google.com/sql/docs/postgres/connect-connectors#python_1).
-
-**Note for SQL Server users**: If your SQL Server instance requires SSL, you need to download the CA certificate for your instance and include `cafile={path to downloaded certificate}` and `validate_host=False`. This is a workaround for a [known issue](https://issuetracker.google.com/184867147).
+> [!NOTE]
+>
+> For more examples of using SQLAlchemy to manage connection pooling with the connector,
+> please see [Cloud SQL SQLAlchemy Samples](https://cloud.google.com/sql/docs/postgres/connect-connectors#python_1).
 
 ### Configuring the Connector
 
@@ -218,14 +219,15 @@ defaults for each connection to make, you can initialize a
 `Connector` object as follows:
 
 ```python
-from google.cloud.sql.connector import Connector, IPTypes
+from google.cloud.sql.connector import Connector
 
 # Note: all parameters below are optional
 connector = Connector(
     ip_type="public",  # can also be "private" or "psc"
     enable_iam_auth=False,
     timeout=30,
-    credentials=custom_creds # google.auth.credentials.Credentials
+    credentials=custom_creds, # google.auth.credentials.Credentials
+    refresh_strategy="lazy",  # can be "lazy" or "background"
 )
 ```
 
@@ -287,6 +289,21 @@ with Connector() as connector:
             print(row)
 ```
 
+### Configuring a Lazy Refresh (Cloud Run, Cloud Functions etc.)
+
+The Connector's `refresh_strategy` argument can be set to `"lazy"` to configure
+the Python Connector to retrieve connection info lazily and as-needed.
+Otherwise, a background refresh cycle runs to retrive the connection info
+periodically. This setting is useful in environments where the CPU may be
+throttled outside of a request context, e.g., Cloud Run, Cloud Functions, etc.
+
+To set the refresh strategy, set the `refresh_strategy` keyword argument when
+initializing a `Connector`:
+
+```python
+connector = Connector(refresh_strategy="lazy")
+```
+
 ### Specifying IP Address Type
 
 The Cloud SQL Python Connector can be used to connect to Cloud SQL instances
@@ -309,9 +326,11 @@ conn = connector.connect(
 )
 ```
 
-Note: If specifying Private IP or Private Service Connect, your application must be
-attached to the proper VPC network to connect to your Cloud SQL instance. For most
-applications this will require the use of a [VPC Connector][vpc-connector].
+> [!IMPORTANT]
+>
+> If specifying Private IP or Private Service Connect (PSC), your application must be
+> attached to the proper VPC network to connect to your Cloud SQL instance. For most
+> applications this will require the use of a [VPC Connector][vpc-connector].
 
 [psc]: https://cloud.google.com/vpc/docs/private-service-connect
 [vpc-connector]: https://cloud.google.com/vpc/docs/configure-serverless-vpc-access#create-connector
@@ -340,9 +359,20 @@ conn = connector.connect(
  )
 ```
 
-### SQL Server Active Directory Authentication
+### SQL Server (MSSQL)
+
+> [!IMPORTANT]
+>
+> If your SQL Server instance is set to [enforce SSL connections](https://cloud.google.com/sql/docs/sqlserver/configure-ssl-instance#enforcing-ssl),
+> you need to download the CA certificate for your instance and include `cafile={path to downloaded certificate}`
+> and `validate_host=False`. This is a workaround for a [known issue](https://issuetracker.google.com/184867147).
+
+#### Active Directory Authentication
 
-Active Directory authentication for SQL Server instances is currently only supported on Windows. First, make sure to follow [these steps](https://cloud.google.com/blog/topics/developers-practitioners/creating-sql-server-instance-integrated-active-directory-using-google-cloud-sql) to set up a Managed AD domain and join your Cloud SQL instance to the domain. [See here for more info on Cloud SQL Active Directory integration](https://cloud.google.com/sql/docs/sqlserver/ad).
+Active Directory authentication for SQL Server instances is currently only supported on Windows.
+First, make sure to follow [these steps](https://cloud.google.com/blog/topics/developers-practitioners/creating-sql-server-instance-integrated-active-directory-using-google-cloud-sql)
+to set up a Managed AD domain and join your Cloud SQL instance to the domain.
+[See here for more info on Cloud SQL Active Directory integration](https://cloud.google.com/sql/docs/sqlserver/ad).
 
 Once you have followed the steps linked above, you can run the following code to return a connection object:
 
@@ -375,6 +405,14 @@ The Python Connector can be used alongside popular Python web frameworks such
 as Flask, FastAPI, etc, to integrate Cloud SQL databases within your
 web applications.
 
+> [!NOTE]
+>
+> For serverless environments such as Cloud Functions, Cloud Run, etc, it may be
+> beneficial to initialize the `Connector` with the lazy refresh strategy.
+> i.e. `Connector(refresh_strategy="lazy")`
+>
+> See [Configuring a Lazy Refresh](#configuring-a-lazy-refresh-cloud-run-cloud-functions-etc)
+
 #### Flask-SQLAlchemy
 
 [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/en/2.x/)
@@ -555,8 +593,10 @@ An alternative to using the `create_async_connector` function is initializing
 a `Connector` as an async context manager, removing the need for explicit
 calls to `connector.close_async()` to cleanup resources.
 
-**Note:** This alternative requires that the running event loop be
-passed in as the `loop` argument to `Connector()`.
+> [!NOTE]
+>
+> This alternative requires that the running event loop be
+> passed in as the `loop` argument to `Connector()`.
 
 ```python
 import asyncio
@@ -603,6 +643,28 @@ async def main():
         await pool.dispose()
 ```
 
+### Debug Logging
+
+The Cloud SQL Python Connector uses the standard [Python logging module][python-logging]
+for debug logging support.
+
+Add the below code to your application to enable debug logging with the Cloud SQL
+Python Connector:
+
+```python
+import logging
+
+logging.basicConfig(format="%(asctime)s [%(levelname)s]: %(message)s")
+logger = logging.getLogger(name="google.cloud.sql.connector")
+logger.setLevel(logging.DEBUG)
+```
+
+For more details on configuring logging, please refer to the
+[Python logging docs][configure-logging].
+
+[python-logging]: https://docs.python.org/3/library/logging.html
+[configure-logging]: https://docs.python.org/3/howto/logging.html#configuring-logging
+
 ## Support policy
 
 ### Major version lifecycle

cloud_sql_python_connector-1.11.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+google/cloud/sql/connector/__init__.py,sha256=x8ui7u3gMlMI-LLJkKTtUU9yvzZvQkTJ-yzr2FH4VTU,983
+google/cloud/sql/connector/asyncpg.py,sha256=c4lAlvEgGf_eBq0G8MVNPRAJQQvo6DcwybiXDW36qkU,1838
+google/cloud/sql/connector/client.py,sha256=wGO6ESxWWYT5qZ-Utg_qh-Rtl_4k5tIjoD-ILcP4REQ,11481
+google/cloud/sql/connector/connection_info.py,sha256=3nFuPtGPLUEZRy3Zx9Z2DvTdh6TJqmhOOoE6yKmSGBQ,4308
+google/cloud/sql/connector/connector.py,sha256=NTubTmsT8rPpGYuhxXgKDW3MX7KUi4WSalKCHJkHFY8,21417
+google/cloud/sql/connector/enums.py,sha256=44tfMm8D_t0ls6GfKwiQ6YkslWM21PZR40RhJPWntkc,2882
+google/cloud/sql/connector/exceptions.py,sha256=OVenqBkkn98xFeytHuOXFTWa9R5bCmemBtbSIm8caoM,1665
+google/cloud/sql/connector/instance.py,sha256=EySszNNHMFjAFskf6-G6Upikvb-tYjEwXx9A_OJBl14,10136
+google/cloud/sql/connector/lazy.py,sha256=og4UPiJxeuLgN7tyqrFAnQF3895Yqdf6kkd4HZSzVJA,5093
+google/cloud/sql/connector/pg8000.py,sha256=EZuO7XgCkG_Y79NQlh3Vv8Ff2w85BFJyFVO237hx1GM,1814
+google/cloud/sql/connector/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+google/cloud/sql/connector/pymysql.py,sha256=wldUgwDPlPa8Nj5F3JaipuP8hJyvzlgOAJbRnOoaB1U,2105
+google/cloud/sql/connector/pytds.py,sha256=vKJoE7E2P0GrhZojg8bGZkqCMLc8dgKAcXE4ee7vEVc,2452
+google/cloud/sql/connector/rate_limiter.py,sha256=bPTupfM4f5QRSCmCAWMqjQylEB7bUM-50plVBU3W2CA,2993
+google/cloud/sql/connector/refresh_utils.py,sha256=CajL-MOcQBBRUkywowdHB3GNOr0WpQn37DXG7dRpkMk,5069
+google/cloud/sql/connector/utils.py,sha256=FQs7RgoViJLIFgJIynVT-_DwAVWnpyXIKu5WZ4m10Ts,3448
+google/cloud/sql/connector/version.py,sha256=l5iWT7w_8JLh0wHTJOCrcxkaD1xxBwPGJDzeSMQLXTI,598
+cloud_sql_python_connector-1.11.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cloud_sql_python_connector-1.11.0.dist-info/METADATA,sha256=4NukfHGYVymtt0NbBrH6bFW3BM544K072H-_f8gx6KM,25925
+cloud_sql_python_connector-1.11.0.dist-info/WHEEL,sha256=bb2Ot9scclHKMOLDEHY6B2sicWOgugjFKaJsT7vwMQo,110
+cloud_sql_python_connector-1.11.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
+cloud_sql_python_connector-1.11.0.dist-info/RECORD,,

google/cloud/sql/connector/__init__.py

@@ -16,7 +16,14 @@ limitations under the License.
 
 from google.cloud.sql.connector.connector import Connector
 from google.cloud.sql.connector.connector import create_async_connector
-from google.cloud.sql.connector.instance import IPTypes
+from google.cloud.sql.connector.enums import IPTypes
+from google.cloud.sql.connector.enums import RefreshStrategy
 from google.cloud.sql.connector.version import __version__
 
-__all__ = ["__version__", "create_async_connector", "Connector", "IPTypes"]
+__all__ = [
+    "__version__",
+    "create_async_connector",
+    "Connector",
+    "IPTypes",
+    "RefreshStrategy",
+]

google/cloud/sql/connector/client.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import datetime
 import logging
 from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
@@ -21,9 +22,13 @@ from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
 import aiohttp
 from cryptography.hazmat.backends import default_backend
 from cryptography.x509 import load_pem_x509_certificate
-import google.auth.transport.requests
+from google.auth.credentials import TokenState
+from google.auth.transport import requests
 
+from google.cloud.sql.connector.connection_info import ConnectionInfo
+from google.cloud.sql.connector.exceptions import AutoIAMAuthNotSupported
 from google.cloud.sql.connector.refresh_utils import _downscope_credentials
+from google.cloud.sql.connector.refresh_utils import retry_50x
 from google.cloud.sql.connector.version import __version__ as version
 
 if TYPE_CHECKING:
@@ -113,9 +118,6 @@ class CloudSQLClient:
             addresses and their type and a string representing the
             certificate authority.
         """
-        if not self._credentials.valid:
-            request = google.auth.transport.requests.Request()
-            self._credentials.refresh(request)
 
         headers = {
             "Authorization": f"Bearer {self._credentials.token}",
@@ -123,9 +125,10 @@ class CloudSQLClient:
 
         url = f"{self._sqladmin_api_endpoint}/sql/{API_VERSION}/projects/{project}/instances/{instance}/connectSettings"
 
-        logger.debug(f"['{instance}']: Requesting metadata")
-
-        resp = await self._client.get(url, headers=headers, raise_for_status=True)
+        resp = await self._client.get(url, headers=headers)
+        if resp.status >= 500:
+            resp = await retry_50x(self._client.get, url, headers=headers)
+        resp.raise_for_status()
         ret_dict = await resp.json()
 
         if ret_dict["region"] != region:
@@ -138,8 +141,10 @@ class CloudSQLClient:
             if "ipAddresses" in ret_dict
             else {}
         )
-        if "dnsName" in ret_dict:
-            ip_addresses["PSC"] = ret_dict["dnsName"]
+        # Remove trailing period from PSC DNS name.
+        psc_dns = ret_dict.get("dnsName")
+        if psc_dns:
+            ip_addresses["PSC"] = psc_dns.rstrip(".")
 
         return {
             "ip_addresses": ip_addresses,
@@ -174,13 +179,6 @@ class CloudSQLClient:
         :returns: An ephemeral certificate from the Cloud SQL instance that allows
             authorized connections to the instance.
         """
-
-        logger.debug(f"['{instance}']: Requesting ephemeral certificate")
-
-        if not self._credentials.valid:
-            request = google.auth.transport.requests.Request()
-            self._credentials.refresh(request)
-
         headers = {
             "Authorization": f"Bearer {self._credentials.token}",
         }
@@ -194,10 +192,10 @@ class CloudSQLClient:
             login_creds = _downscope_credentials(self._credentials)
             data["access_token"] = login_creds.token
 
-        resp = await self._client.post(
-            url, headers=headers, json=data, raise_for_status=True
-        )
-
+        resp = await self._client.post(url, headers=headers, json=data)
+        if resp.status >= 500:
+            resp = await retry_50x(self._client.post, url, headers=headers, json=data)
+        resp.raise_for_status()
         ret_dict = await resp.json()
 
         ephemeral_cert: str = ret_dict["ephemeralCert"]["cert"]
@@ -220,6 +218,84 @@ class CloudSQLClient:
                 expiration = token_expiration
         return ephemeral_cert, expiration
 
+    async def get_connection_info(
+        self,
+        project: str,
+        region: str,
+        instance: str,
+        keys: asyncio.Future,
+        enable_iam_auth: bool,
+    ) -> ConnectionInfo:
+        """Immediately performs a full refresh operation using the Cloud SQL
+        Admin API.
+
+        Args:
+            project (str): The name of the project the Cloud SQL instance is
+                located in.
+            region (str): The region the Cloud SQL instance is located in.
+            instance (str): Name of the Cloud SQL instance.
+            keys (asyncio.Future): A future to the client's public-private key
+                pair.
+            enable_iam_auth (bool): Whether an automatic IAM database
+                authentication connection is being requested (Postgres and MySQL).
+
+        Returns:
+            ConnectionInfo: All the information required to connect securely to
+                the Cloud SQL instance.
+        Raises:
+            AutoIAMAuthNotSupported: Database engine does not support automatic
+                IAM authentication.
+        """
+        priv_key, pub_key = await keys
+        # before making Cloud SQL Admin API calls, refresh creds if required
+        if not self._credentials.token_state == TokenState.FRESH:
+            self._credentials.refresh(requests.Request())
+
+        metadata_task = asyncio.create_task(
+            self._get_metadata(
+                project,
+                region,
+                instance,
+            )
+        )
+
+        ephemeral_task = asyncio.create_task(
+            self._get_ephemeral(
+                project,
+                instance,
+                pub_key,
+                enable_iam_auth,
+            )
+        )
+        try:
+            metadata = await metadata_task
+            # check if automatic IAM database authn is supported for database engine
+            if enable_iam_auth and not metadata["database_version"].startswith(
+                ("POSTGRES", "MYSQL")
+            ):
+                raise AutoIAMAuthNotSupported(
+                    f"'{metadata['database_version']}' does not support "
+                    "automatic IAM authentication. It is only supported with "
+                    "Cloud SQL Postgres or MySQL instances."
+                )
+        except Exception:
+            # cancel ephemeral cert task if exception occurs before it is awaited
+            ephemeral_task.cancel()
+            raise
+
+        ephemeral_cert, expiration = await ephemeral_task
+
+        return ConnectionInfo(
+            ephemeral_cert,
+            metadata["server_ca_cert"],
+            priv_key,
+            metadata["ip_addresses"],
+            metadata["database_version"],
+            expiration,
+        )
+
     async def close(self) -> None:
         """Close CloudSQLClient gracefully."""
+        logger.debug("Waiting for Connector's http client to close")
         await self._client.close()
+        logger.debug("Closed Connector's http client")

google/cloud/sql/connector/connection_info.py

@@ -0,0 +1,105 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+import ssl
+from tempfile import TemporaryDirectory
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+from google.cloud.sql.connector.exceptions import CloudSQLIPTypeError
+from google.cloud.sql.connector.exceptions import TLSVersionError
+from google.cloud.sql.connector.utils import write_to_file
+
+if TYPE_CHECKING:
+    import datetime
+
+    from google.cloud.sql.connector.enums import IPTypes
+
+logger = logging.getLogger(name=__name__)
+
+
+@dataclass
+class ConnectionInfo:
+    """Contains all necessary information to connect securely to the
+    server-side Proxy running on a Cloud SQL instance."""
+
+    client_cert: str
+    server_ca_cert: str
+    private_key: bytes
+    ip_addrs: Dict[str, Any]
+    database_version: str
+    expiration: datetime.datetime
+    context: Optional[ssl.SSLContext] = None
+
+    def create_ssl_context(self, enable_iam_auth: bool = False) -> ssl.SSLContext:
+        """Constructs a SSL/TLS context for the given connection info.
+
+        Cache the SSL context to ensure we don't read from disk repeatedly when
+        configuring a secure connection.
+        """
+        # if SSL context is cached, use it
+        if self.context is not None:
+            return self.context
+        context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+
+        # update ssl.PROTOCOL_TLS_CLIENT default
+        context.check_hostname = False
+
+        # TODO: remove if/else when Python 3.10 is min version. PEP 644 has been
+        # implemented. The ssl module requires OpenSSL 1.1.1 or newer.
+        # verify OpenSSL version supports TLSv1.3
+        if ssl.HAS_TLSv1_3:
+            # force TLSv1.3 if supported by client
+            context.minimum_version = ssl.TLSVersion.TLSv1_3
+        # fallback to TLSv1.2 for older versions of OpenSSL
+        else:
+            if enable_iam_auth:
+                raise TLSVersionError(
+                    f"Your current version of OpenSSL ({ssl.OPENSSL_VERSION}) does not "
+                    "support TLSv1.3, which is required to use IAM Authentication.\n"
+                    "Upgrade your OpenSSL version to 1.1.1 for TLSv1.3 support."
+                )
+            logger.warning(
+                "TLSv1.3 is not supported with your version of OpenSSL "
+                f"({ssl.OPENSSL_VERSION}), falling back to TLSv1.2\n"
+                "Upgrade your OpenSSL version to 1.1.1 for TLSv1.3 support."
+            )
+            context.minimum_version = ssl.TLSVersion.TLSv1_2
+
+        # tmpdir and its contents are automatically deleted after the CA cert
+        # and ephemeral cert are loaded into the SSLcontext. The values
+        # need to be written to files in order to be loaded by the SSLContext
+        with TemporaryDirectory() as tmpdir:
+            ca_filename, cert_filename, key_filename = write_to_file(
+                tmpdir, self.server_ca_cert, self.client_cert, self.private_key
+            )
+            context.load_cert_chain(cert_filename, keyfile=key_filename)
+            context.load_verify_locations(cafile=ca_filename)
+        # set class attribute to cache context for subsequent calls
+        self.context = context
+        return context
+
+    def get_preferred_ip(self, ip_type: IPTypes) -> str:
+        """Returns the first IP address for the instance, according to the preference
+        supplied by ip_type. If no IP addressess with the given preference are found,
+        an error is raised."""
+        if ip_type.value in self.ip_addrs:
+            return self.ip_addrs[ip_type.value]
+        raise CloudSQLIPTypeError(
+            "Cloud SQL instance does not have any IP addresses matching "
+            f"preference: {ip_type.value}"
+        )