cloud-sql-python-connector 1.13.0__py2.py3-none-any.whl → 1.15.0__py2.py3-none-any.whl

{cloud_sql_python_connector-1.13.0.dist-info → cloud_sql_python_connector-1.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloud-sql-python-connector
-Version: 1.13.0
+Version: 1.15.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
@@ -21,17 +21,18 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiofiles
 Requires-Dist: aiohttp
-Requires-Dist: cryptography (>=42.0.0)
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: dnspython>=2.0.0
 Requires-Dist: Requests
-Requires-Dist: google-auth (>=2.28.0)
+Requires-Dist: google-auth>=2.28.0
 Provides-Extra: asyncpg
-Requires-Dist: asyncpg (>=0.29.0) ; extra == 'asyncpg'
+Requires-Dist: asyncpg>=0.30.0; extra == "asyncpg"
 Provides-Extra: pg8000
-Requires-Dist: pg8000 (>=1.31.1) ; extra == 'pg8000'
+Requires-Dist: pg8000>=1.31.1; extra == "pg8000"
 Provides-Extra: pymysql
-Requires-Dist: PyMySQL (>=1.1.0) ; extra == 'pymysql'
+Requires-Dist: PyMySQL>=1.1.0; extra == "pymysql"
 Provides-Extra: pytds
-Requires-Dist: python-tds (>=1.15.0) ; extra == 'pytds'
+Requires-Dist: python-tds>=1.15.0; extra == "pytds"
 
 <p align="center">
     <a href="https://cloud.google.com/blog/topics/developers-practitioners/how-connect-cloud-sql-using-python-easy-way">
@@ -400,6 +401,69 @@ conn = connector.connect(
 )
 ```
 
+### Using DNS domain names to identify instances
+
+The connector can be configured to use DNS to look up an instance. This would
+allow you to configure your application to connect to a database instance, and
+centrally configure which instance in your DNS zone.
+
+#### Configure your DNS Records
+
+Add a DNS TXT record for the Cloud SQL instance to a **private** DNS server
+or a private Google Cloud DNS Zone used by your application.
+
+> [!NOTE]
+>
+> You are strongly discouraged from adding DNS records for your
+> Cloud SQL instances to a public DNS server. This would allow anyone on the
+> internet to discover the Cloud SQL instance name.
+
+For example: suppose you wanted to use the domain name
+`prod-db.mycompany.example.com` to connect to your database instance
+`my-project:region:my-instance`. You would create the following DNS record:
+
+* Record type: `TXT`
+* Name: `prod-db.mycompany.example.com` – This is the domain name used by the application
+* Value: `my-project:my-region:my-instance` – This is the Cloud SQL instance connection name
+
+#### Configure the connector
+
+Configure the connector to resolve DNS names by initializing it with
+`resolver=DnsResolver` and replacing the instance connection name with the DNS
+name in `connector.connect`:
+
+```python
+from google.cloud.sql.connector import Connector, DnsResolver
+import pymysql
+import sqlalchemy
+
+# helper function to return SQLAlchemy connection pool
+def init_connection_pool(connector: Connector) -> sqlalchemy.engine.Engine:
+    # function used to generate database connection
+    def getconn() -> pymysql.connections.Connection:
+        conn = connector.connect(
+            "prod-db.mycompany.example.com",  # using DNS name
+            "pymysql",
+            user="my-user",
+            password="my-password",
+            db="my-db-name"
+        )
+        return conn
+
+    # create connection pool
+    pool = sqlalchemy.create_engine(
+        "mysql+pymysql://",
+        creator=getconn,
+    )
+    return pool
+
+# initialize Cloud SQL Python Connector with `resolver=DnsResolver`
+with Connector(resolver=DnsResolver) as connector:
+    # initialize connection pool
+    pool = init_connection_pool(connector)
+    # ... use SQLAlchemy engine normally
+```
+
 ### Using the Python Connector with Python Web Frameworks
 
 The Python Connector can be used alongside popular Python web frameworks such
@@ -537,6 +601,42 @@ The `create_async_connector` allows all the same input arguments as the
 Once a `Connector` object is returned by `create_async_connector` you can call
 its `connect_async` method, just as you would the `connect` method:
 
+#### Asyncpg Connection Pool
+
+```python
+import asyncpg
+from google.cloud.sql.connector import Connector, create_async_connector
+
+async def main():
+    # initialize Connector object for connections to Cloud SQL
+    connector = create_async_connector()
+
+    # creation function to generate asyncpg connections as the 'connect' arg
+    async def getconn(instance_connection_name, **kwargs) -> asyncpg.Connection:
+        return await connector.connect_async(
+            instance_connection_name,
+            "asyncpg",
+            user="my-user",
+            password="my-password",
+            db="my-db",
+            **kwargs, # ... additional asyncpg args
+        )
+
+    # initialize connection pool
+    pool = await asyncpg.create_pool(
+        "my-project:my-region:my-instance", connect=getconn
+    )
+
+    # acquire connection and query Cloud SQL database
+    async with pool.acquire() as conn:
+        res = await conn.fetch("SELECT NOW()")
+    
+    # close Connector
+    await connector.close_async()
+```
+
+#### SQLAlchemy Async Engine
+
 ```python
 import asyncpg
 
@@ -546,7 +646,7 @@ from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 from google.cloud.sql.connector import Connector, create_async_connector
 
 async def init_connection_pool(connector: Connector) -> AsyncEngine:
-    # initialize Connector object for connections to Cloud SQL
+    # creation function to generate asyncpg connections as 'async_creator' arg
     async def getconn() -> asyncpg.Connection:
         conn: asyncpg.Connection = await connector.connect_async(
             "project:region:instance",  # Cloud SQL instance connection name
@@ -599,6 +699,40 @@ calls to `connector.close_async()` to cleanup resources.
 > This alternative requires that the running event loop be
 > passed in as the `loop` argument to `Connector()`.
 
+#### Asyncpg Connection Pool
+
+```python
+import asyncpg
+from google.cloud.sql.connector import Connector, create_async_connector
+
+async def main():
+    # initialize Connector object for connections to Cloud SQL
+    loop = asyncio.get_running_loop()
+    async with Connector(loop=loop) as connector:
+
+        # creation function to generate asyncpg connections as the 'connect' arg
+        async def getconn(instance_connection_name, **kwargs) -> asyncpg.Connection:
+            return await connector.connect_async(
+                instance_connection_name,
+                "asyncpg",
+                user="my-user",
+                password="my-password",
+                db="my-db",
+                **kwargs, # ... additional asyncpg args
+            )
+
+        # create connection pool
+        pool = await asyncpg.create_pool(
+            "my-project:my-region:my-instance", connect=getconn
+        )
+
+        # acquire connection and query Cloud SQL database
+        async with pool.acquire() as conn:
+            res = await conn.fetch("SELECT NOW()")
+```
+
+#### SQLAlchemy Async Engine
+
 ```python
 import asyncio
 import asyncpg
@@ -609,17 +743,17 @@ from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 from google.cloud.sql.connector import Connector
 
 async def init_connection_pool(connector: Connector) -> AsyncEngine:
-    # initialize Connector object for connections to Cloud SQL
+    # creation function to generate asyncpg connections as 'async_creator' arg
     async def getconn() -> asyncpg.Connection:
-            conn: asyncpg.Connection = await connector.connect_async(
-                "project:region:instance",  # Cloud SQL instance connection name
-                "asyncpg",
-                user="my-user",
-                password="my-password",
-                db="my-db-name"
-                # ... additional database driver args
-            )
-            return conn
+        conn: asyncpg.Connection = await connector.connect_async(
+            "project:region:instance",  # Cloud SQL instance connection name
+            "asyncpg",
+            user="my-user",
+            password="my-password",
+            db="my-db-name"
+            # ... additional database driver args
+        )
+        return conn
 
     # The Cloud SQL Python Connector can be used along with SQLAlchemy using the
     # 'async_creator' argument to 'create_async_engine'

cloud_sql_python_connector-1.15.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+google/cloud/sql/connector/__init__.py,sha256=kSGB2q6hQwkFLD1eI7RjY4BvPLvg2FD3wfPBmbnsjDE,1149
+google/cloud/sql/connector/asyncpg.py,sha256=HUOB0rRhr2-zMbygDtdWTDNlYqEPkN0ADqCIpM3waDc,1839
+google/cloud/sql/connector/client.py,sha256=ocUN1nrgZyJRnxgh6Ym3w0c_qKb8hqKCmR1OiJ2KUpM,12622
+google/cloud/sql/connector/connection_info.py,sha256=cFNOeHJ0lQODf7q5Hc25LXsNWzWgzYcFMrBuNdZ1y5k,4430
+google/cloud/sql/connector/connection_name.py,sha256=4F5XhgmSWGEeF-3TJk2E61YPbxMAecPGw56nPTZmQ2o,2067
+google/cloud/sql/connector/connector.py,sha256=9t2iz_Tx1NluGgaM8JlZUfb7HWHgsWjmLnAL8WvKp4E,21157
+google/cloud/sql/connector/enums.py,sha256=44tfMm8D_t0ls6GfKwiQ6YkslWM21PZR40RhJPWntkc,2882
+google/cloud/sql/connector/exceptions.py,sha256=eyflYggkKZx3t944FTPqQrX-R75lZgtpOwC4uVLPhG0,1823
+google/cloud/sql/connector/instance.py,sha256=nRzhE7t_M6AhjiYvEZHOjkBHx3d9wGRCC6RekgDApFI,8379
+google/cloud/sql/connector/lazy.py,sha256=p1wLte49xE_aHiY5shjMbxwytgW-ycS0Hd67C34gaDY,4631
+google/cloud/sql/connector/pg8000.py,sha256=gZisjfXP4rNIjyxOQS75fvr0Xe6eLrFo4mIhVjoMLTw,1815
+google/cloud/sql/connector/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+google/cloud/sql/connector/pymysql.py,sha256=82DwSJUhZHH2AW-vO7qhkljyShwj6Kmd17WCbOGZH74,2106
+google/cloud/sql/connector/pytds.py,sha256=h-1pDhqLDkhviKBBOJ29gnIeYHKWw7Dtj91VLu1iNUI,2453
+google/cloud/sql/connector/rate_limiter.py,sha256=bPTupfM4f5QRSCmCAWMqjQylEB7bUM-50plVBU3W2CA,2993
+google/cloud/sql/connector/refresh_utils.py,sha256=HfuuLdlqg2IxusB4T3BMj-BJlGsXtHsrCX_Hp-eJ_j0,5063
+google/cloud/sql/connector/resolver.py,sha256=cNDJMhmS_0CIAmz8kCABKHJNLNm1wiwIVoPEN-gWzzY,2850
+google/cloud/sql/connector/utils.py,sha256=7g1fX-JsZc7xOgTuxrAiroFHQIQk_BEJZNYaKOinwQY,3508
+google/cloud/sql/connector/version.py,sha256=l3R3usCjpr4Wwp3w2gpWFcrGmsLi8Y1gAAvZC15RLv0,598
+cloud_sql_python_connector-1.15.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cloud_sql_python_connector-1.15.0.dist-info/METADATA,sha256=Qszn2k_QqcVlX92c_1A-7MurYUoojTIMbx5M13aPZnI,30314
+cloud_sql_python_connector-1.15.0.dist-info/WHEEL,sha256=OpXWERl2xLPRHTvd2ZXo_iluPEQd8uSbYkJ53NAER_Y,109
+cloud_sql_python_connector-1.15.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
+cloud_sql_python_connector-1.15.0.dist-info/RECORD,,

{cloud_sql_python_connector-1.13.0.dist-info → cloud_sql_python_connector-1.15.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.38.4)
+Generator: setuptools (75.3.0)
 Root-Is-Purelib: true
 Tag: py2-none-any
 Tag: py3-none-any

google/cloud/sql/connector/__init__.py

@@ -18,12 +18,16 @@ from google.cloud.sql.connector.connector import Connector
 from google.cloud.sql.connector.connector import create_async_connector
 from google.cloud.sql.connector.enums import IPTypes
 from google.cloud.sql.connector.enums import RefreshStrategy
+from google.cloud.sql.connector.resolver import DefaultResolver
+from google.cloud.sql.connector.resolver import DnsResolver
 from google.cloud.sql.connector.version import __version__
 
 __all__ = [
     "__version__",
     "create_async_connector",
     "Connector",
+    "DefaultResolver",
+    "DnsResolver",
     "IPTypes",
     "RefreshStrategy",
 ]

google/cloud/sql/connector/asyncpg.py

@@ -13,6 +13,7 @@ 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.
 """
+
 import ssl
 from typing import Any, TYPE_CHECKING
 

google/cloud/sql/connector/client.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 import asyncio
 import datetime
 import logging
-from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
+from typing import Any, Optional, TYPE_CHECKING
 
 import aiohttp
 from cryptography.hazmat.backends import default_backend
@@ -26,6 +26,7 @@ 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.connection_name import ConnectionName
 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
@@ -98,7 +99,7 @@ class CloudSQLClient:
         project: str,
         region: str,
         instance: str,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Requests metadata from the Cloud SQL Instance
         and returns a dictionary containing the IP addresses and certificate
         authority of the Cloud SQL Instance.
@@ -113,7 +114,7 @@ class CloudSQLClient:
         :type instance: str
         :param instance: A string representing the name of the instance.
 
-        :rtype: Dict[str: Union[Dict, str]]
+        :rtype: dict[str: Union[dict, str]]
         :returns: Returns a dictionary containing a dictionary of all IP
             addresses and their type and a string representing the
             certificate authority.
@@ -128,8 +129,19 @@ class CloudSQLClient:
         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()
+        # try to get response json for better error message
+        try:
+            ret_dict = await resp.json()
+            if resp.status >= 400:
+                # if detailed error message is in json response, use as error message
+                message = ret_dict.get("error", {}).get("message")
+                if message:
+                    resp.reason = message
+        # skip, raise_for_status will catch all errors in finally block
+        except Exception:
+            pass
+        finally:
+            resp.raise_for_status()
 
         if ret_dict["region"] != region:
             raise ValueError(
@@ -161,7 +173,7 @@ class CloudSQLClient:
         instance: str,
         pub_key: str,
         enable_iam_auth: bool = False,
-    ) -> Tuple[str, datetime.datetime]:
+    ) -> tuple[str, datetime.datetime]:
         """Asynchronously requests an ephemeral certificate from the Cloud SQL Instance.
 
         :type project: str
@@ -198,8 +210,19 @@ class CloudSQLClient:
         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()
+        # try to get response json for better error message
+        try:
+            ret_dict = await resp.json()
+            if resp.status >= 400:
+                # if detailed error message is in json response, use as error message
+                message = ret_dict.get("error", {}).get("message")
+                if message:
+                    resp.reason = message
+        # skip, raise_for_status will catch all errors in finally block
+        except Exception:
+            pass
+        finally:
+            resp.raise_for_status()
 
         ephemeral_cert: str = ret_dict["ephemeralCert"]["cert"]
 
@@ -223,9 +246,7 @@ class CloudSQLClient:
 
     async def get_connection_info(
         self,
-        project: str,
-        region: str,
-        instance: str,
+        conn_name: ConnectionName,
         keys: asyncio.Future,
         enable_iam_auth: bool,
     ) -> ConnectionInfo:
@@ -233,10 +254,8 @@ class CloudSQLClient:
         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.
+            conn_name (ConnectionName): The Cloud SQL instance's
+                connection name.
             keys (asyncio.Future): A future to the client's public-private key
                 pair.
             enable_iam_auth (bool): Whether an automatic IAM database
@@ -256,16 +275,16 @@ class CloudSQLClient:
 
         metadata_task = asyncio.create_task(
             self._get_metadata(
-                project,
-                region,
-                instance,
+                conn_name.project,
+                conn_name.region,
+                conn_name.instance_name,
             )
         )
 
         ephemeral_task = asyncio.create_task(
             self._get_ephemeral(
-                project,
-                instance,
+                conn_name.project,
+                conn_name.instance_name,
                 pub_key,
                 enable_iam_auth,
             )
@@ -289,6 +308,7 @@ class CloudSQLClient:
         ephemeral_cert, expiration = await ephemeral_task
 
         return ConnectionInfo(
+            conn_name,
             ephemeral_cert,
             metadata["server_ca_cert"],
             priv_key,

google/cloud/sql/connector/connection_info.py

@@ -17,10 +17,11 @@ from __future__ import annotations
 from dataclasses import dataclass
 import logging
 import ssl
-from typing import Any, Dict, Optional, TYPE_CHECKING
+from typing import Any, Optional, TYPE_CHECKING
 
 from aiofiles.tempfile import TemporaryDirectory
 
+from google.cloud.sql.connector.connection_name import ConnectionName
 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
@@ -38,10 +39,11 @@ class ConnectionInfo:
     """Contains all necessary information to connect securely to the
     server-side Proxy running on a Cloud SQL instance."""
 
+    conn_name: ConnectionName
     client_cert: str
     server_ca_cert: str
     private_key: bytes
-    ip_addrs: Dict[str, Any]
+    ip_addrs: dict[str, Any]
     database_version: str
     expiration: datetime.datetime
     context: Optional[ssl.SSLContext] = None

google/cloud/sql/connector/connection_name.py

@@ -0,0 +1,61 @@
+# 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 dataclasses import dataclass
+import re
+
+# Instance connection name is the format <PROJECT>:<REGION>:<INSTANCE_NAME>
+# Additionally, we have to support legacy "domain-scoped" projects
+# (e.g. "google.com:PROJECT")
+CONN_NAME_REGEX = re.compile(("([^:]+(:[^:]+)?):([^:]+):([^:]+)"))
+
+
+@dataclass
+class ConnectionName:
+    """ConnectionName represents a Cloud SQL instance's "instance connection name".
+
+    Takes the format "<PROJECT>:<REGION>:<INSTANCE_NAME>".
+    """
+
+    project: str
+    region: str
+    instance_name: str
+    domain_name: str = ""
+
+    def __str__(self) -> str:
+        if self.domain_name:
+            return f"{self.domain_name} -> {self.project}:{self.region}:{self.instance_name}"
+        return f"{self.project}:{self.region}:{self.instance_name}"
+
+
+def _parse_connection_name(connection_name: str) -> ConnectionName:
+    return _parse_connection_name_with_domain_name(connection_name, "")
+
+
+def _parse_connection_name_with_domain_name(
+    connection_name: str, domain_name: str
+) -> ConnectionName:
+    if CONN_NAME_REGEX.fullmatch(connection_name) is None:
+        raise ValueError(
+            "Arg `instance_connection_string` must have "
+            "format: PROJECT:REGION:INSTANCE, "
+            f"got {connection_name}."
+        )
+    connection_name_split = CONN_NAME_REGEX.split(connection_name)
+    return ConnectionName(
+        connection_name_split[1],
+        connection_name_split[3],
+        connection_name_split[4],
+        domain_name,
+    )

google/cloud/sql/connector/connector.py

@@ -21,7 +21,7 @@ from functools import partial
 import logging
 from threading import Thread
 from types import TracebackType
-from typing import Any, Dict, Optional, Tuple, Type, Union
+from typing import Any, Optional, Type, Union
 
 import google.auth
 from google.auth.credentials import Credentials
@@ -37,6 +37,8 @@ from google.cloud.sql.connector.lazy import LazyRefreshCache
 import google.cloud.sql.connector.pg8000 as pg8000
 import google.cloud.sql.connector.pymysql as pymysql
 import google.cloud.sql.connector.pytds as pytds
+from google.cloud.sql.connector.resolver import DefaultResolver
+from google.cloud.sql.connector.resolver import DnsResolver
 from google.cloud.sql.connector.utils import format_database_user
 from google.cloud.sql.connector.utils import generate_keys
 
@@ -63,6 +65,7 @@ class Connector:
         user_agent: Optional[str] = None,
         universe_domain: Optional[str] = None,
         refresh_strategy: str | RefreshStrategy = RefreshStrategy.BACKGROUND,
+        resolver: Type[DefaultResolver] | Type[DnsResolver] = DefaultResolver,
     ) -> None:
         """Initializes a Connector instance.
 
@@ -104,6 +107,12 @@ class Connector:
                 of the following: RefreshStrategy.LAZY ("LAZY") or
                 RefreshStrategy.BACKGROUND ("BACKGROUND").
                 Default: RefreshStrategy.BACKGROUND
+
+            resolver (DefaultResolver | DnsResolver): The class name of the
+                resolver to use for resolving the Cloud SQL instance connection
+                name. To resolve a DNS record to an instance connection name, use
+                DnsResolver.
+                Default: DefaultResolver
         """
         # if refresh_strategy is str, convert to RefreshStrategy enum
         if isinstance(refresh_strategy, str):
@@ -133,8 +142,8 @@ class Connector:
                 )
         # initialize dict to store caches, key is a tuple consisting of instance
         # connection name string and enable_iam_auth boolean flag
-        self._cache: Dict[
-            Tuple[str, bool], Union[RefreshAheadCache, LazyRefreshCache]
+        self._cache: dict[
+            tuple[str, bool], Union[RefreshAheadCache, LazyRefreshCache]
         ] = {}
         self._client: Optional[CloudSQLClient] = None
 
@@ -157,6 +166,7 @@ class Connector:
         self._enable_iam_auth = enable_iam_auth
         self._quota_project = quota_project
         self._user_agent = user_agent
+        self._resolver = resolver()
         # if ip_type is str, convert to IPTypes enum
         if isinstance(ip_type, str):
             ip_type = IPTypes._from_str(ip_type)
@@ -269,31 +279,28 @@ class Connector:
         if (instance_connection_string, enable_iam_auth) in self._cache:
             cache = self._cache[(instance_connection_string, enable_iam_auth)]
         else:
+            conn_name = await self._resolver.resolve(instance_connection_string)
             if self._refresh_strategy == RefreshStrategy.LAZY:
                 logger.debug(
-                    f"['{instance_connection_string}']: Refresh strategy is set"
-                    " to lazy refresh"
+                    f"['{conn_name}']: Refresh strategy is set to lazy refresh"
                 )
                 cache = LazyRefreshCache(
-                    instance_connection_string,
+                    conn_name,
                     self._client,
                     self._keys,
                     enable_iam_auth,
                 )
             else:
                 logger.debug(
-                    f"['{instance_connection_string}']: Refresh strategy is set"
-                    " to backgound refresh"
+                    f"['{conn_name}']: Refresh strategy is set to backgound refresh"
                 )
                 cache = RefreshAheadCache(
-                    instance_connection_string,
+                    conn_name,
                     self._client,
                     self._keys,
                     enable_iam_auth,
                 )
-            logger.debug(
-                f"['{instance_connection_string}']: Connection info added to cache"
-            )
+            logger.debug(f"['{conn_name}']: Connection info added to cache")
             self._cache[(instance_connection_string, enable_iam_auth)] = cache
 
         connect_func = {
@@ -332,9 +339,7 @@ class Connector:
             # the cache and re-raise the error
             await self._remove_cached(instance_connection_string, enable_iam_auth)
             raise
-        logger.debug(
-            f"['{instance_connection_string}']: Connecting to {ip_address}:3307"
-        )
+        logger.debug(f"['{conn_info.conn_name}']: Connecting to {ip_address}:3307")
         # format `user` param for automatic IAM database authn
         if enable_iam_auth:
             formatted_user = format_database_user(

google/cloud/sql/connector/exceptions.py

@@ -70,3 +70,10 @@ class IncompatibleDriverError(Exception):
     Exception to be raised when the database driver given is for the wrong
     database engine. (i.e. asyncpg for a MySQL database)
     """
+
+
+class DnsResolutionError(Exception):
+    """
+    Exception to be raised when an instance connection name can not be resolved
+    from a DNS record.
+    """

google/cloud/sql/connector/instance.py

@@ -21,13 +21,10 @@ from datetime import datetime
 from datetime import timedelta
 from datetime import timezone
 import logging
-import re
-from typing import Tuple
-
-import aiohttp
 
 from google.cloud.sql.connector.client import CloudSQLClient
 from google.cloud.sql.connector.connection_info import ConnectionInfo
+from google.cloud.sql.connector.connection_name import ConnectionName
 from google.cloud.sql.connector.exceptions import RefreshNotValidError
 from google.cloud.sql.connector.rate_limiter import AsyncRateLimiter
 from google.cloud.sql.connector.refresh_utils import _is_valid
@@ -37,22 +34,6 @@ logger = logging.getLogger(name=__name__)
 
 APPLICATION_NAME = "cloud-sql-python-connector"
 
-# Instance connection name is the format <PROJECT>:<REGION>:<INSTANCE>
-# Additionally, we have to support legacy "domain-scoped" projects
-# (e.g. "google.com:PROJECT")
-CONN_NAME_REGEX = re.compile(("([^:]+(:[^:]+)?):([^:]+):([^:]+)"))
-
-
-def _parse_instance_connection_name(connection_name: str) -> Tuple[str, str, str]:
-    if CONN_NAME_REGEX.fullmatch(connection_name) is None:
-        raise ValueError(
-            "Arg `instance_connection_string` must have "
-            "format: PROJECT:REGION:INSTANCE, "
-            f"got {connection_name}."
-        )
-    connection_name_split = CONN_NAME_REGEX.split(connection_name)
-    return connection_name_split[1], connection_name_split[3], connection_name_split[4]
-
 
 class RefreshAheadCache:
     """Cache that refreshes connection info in the background prior to expiration.
@@ -64,7 +45,7 @@ class RefreshAheadCache:
 
     def __init__(
         self,
-        instance_connection_string: str,
+        conn_name: ConnectionName,
         client: CloudSQLClient,
         keys: asyncio.Future,
         enable_iam_auth: bool = False,
@@ -72,8 +53,8 @@ class RefreshAheadCache:
         """Initializes a RefreshAheadCache instance.
 
         Args:
-            instance_connection_string (str): The Cloud SQL Instance's
-                connection string (also known as an instance connection name).
+            conn_name (ConnectionName): The Cloud SQL instance's
+                connection name.
             client (CloudSQLClient): The Cloud SQL Client instance.
             keys (asyncio.Future): A future to the client's public-private key
                 pair.
@@ -81,11 +62,7 @@ class RefreshAheadCache:
                 (Postgres and MySQL) as the default authentication method for all
                 connections.
         """
-        # validate and parse instance connection name
-        self._project, self._region, self._instance = _parse_instance_connection_name(
-            instance_connection_string
-        )
-        self._instance_connection_string = instance_connection_string
+        self._conn_name = conn_name
 
         self._enable_iam_auth = enable_iam_auth
         self._keys = keys
@@ -122,40 +99,27 @@ class RefreshAheadCache:
         """
         self._refresh_in_progress.set()
         logger.debug(
-            f"['{self._instance_connection_string}']: Connection info refresh "
-            "operation started"
+            f"['{self._conn_name}']: Connection info refresh operation started"
         )
 
         try:
             await self._refresh_rate_limiter.acquire()
             connection_info = await self._client.get_connection_info(
-                self._project,
-                self._region,
-                self._instance,
+                self._conn_name,
                 self._keys,
                 self._enable_iam_auth,
             )
             logger.debug(
-                f"['{self._instance_connection_string}']: Connection info "
-                "refresh operation complete"
+                f"['{self._conn_name}']: Connection info refresh operation complete"
             )
             logger.debug(
-                f"['{self._instance_connection_string}']: Current certificate "
+                f"['{self._conn_name}']: Current certificate "
                 f"expiration = {connection_info.expiration.isoformat()}"
             )
 
-        except aiohttp.ClientResponseError as e:
-            logger.debug(
-                f"['{self._instance_connection_string}']: Connection info "
-                f"refresh operation failed: {str(e)}"
-            )
-            if e.status == 403:
-                e.message = "Forbidden: Authenticated IAM principal does not seem authorized to make API request. Verify 'Cloud SQL Admin API' is enabled within your GCP project and 'Cloud SQL Client' role has been granted to IAM principal."
-            raise
-
         except Exception as e:
             logger.debug(
-                f"['{self._instance_connection_string}']: Connection info "
+                f"['{self._conn_name}']: Connection info "
                 f"refresh operation failed: {str(e)}"
             )
             raise
@@ -189,18 +153,17 @@ class RefreshAheadCache:
                 # check that refresh is valid
                 if not await _is_valid(refresh_task):
                     raise RefreshNotValidError(
-                        f"['{self._instance_connection_string}']: Invalid refresh operation. Certficate appears to be expired."
+                        f"['{self._conn_name}']: Invalid refresh operation. Certficate appears to be expired."
                     )
             except asyncio.CancelledError:
                 logger.debug(
-                    f"['{self._instance_connection_string}']: Scheduled refresh"
-                    " operation cancelled"
+                    f"['{self._conn_name}']: Scheduled refresh" " operation cancelled"
                 )
                 raise
             # bad refresh attempt
             except Exception as e:
                 logger.exception(
-                    f"['{self._instance_connection_string}']: "
+                    f"['{self._conn_name}']: "
                     "An error occurred while performing refresh. "
                     "Scheduling another refresh attempt immediately",
                     exc_info=e,
@@ -217,7 +180,7 @@ class RefreshAheadCache:
             # calculate refresh delay based on certificate expiration
             delay = _seconds_until_refresh(refresh_data.expiration)
             logger.debug(
-                f"['{self._instance_connection_string}']: Connection info refresh"
+                f"['{self._conn_name}']: Connection info refresh"
                 " operation scheduled for "
                 f"{(datetime.now(timezone.utc) + timedelta(seconds=delay)).isoformat(timespec='seconds')} "
                 f"(now + {timedelta(seconds=delay)})"
@@ -241,7 +204,7 @@ class RefreshAheadCache:
         graceful exit.
         """
         logger.debug(
-            f"['{self._instance_connection_string}']: Canceling connection info "
+            f"['{self._conn_name}']: Canceling connection info "
             "refresh operation tasks"
         )
         self._current.cancel()

google/cloud/sql/connector/lazy.py

@@ -21,7 +21,7 @@ from typing import Optional
 
 from google.cloud.sql.connector.client import CloudSQLClient
 from google.cloud.sql.connector.connection_info import ConnectionInfo
-from google.cloud.sql.connector.instance import _parse_instance_connection_name
+from google.cloud.sql.connector.connection_name import ConnectionName
 from google.cloud.sql.connector.refresh_utils import _refresh_buffer
 
 logger = logging.getLogger(name=__name__)
@@ -38,7 +38,7 @@ class LazyRefreshCache:
 
     def __init__(
         self,
-        instance_connection_string: str,
+        conn_name: ConnectionName,
         client: CloudSQLClient,
         keys: asyncio.Future,
         enable_iam_auth: bool = False,
@@ -46,8 +46,8 @@ class LazyRefreshCache:
         """Initializes a LazyRefreshCache instance.
 
         Args:
-            instance_connection_string (str): The Cloud SQL Instance's
-                connection string (also known as an instance connection name).
+            conn_name (ConnectionName): The Cloud SQL instance's
+                connection name.
             client (CloudSQLClient): The Cloud SQL Client instance.
             keys (asyncio.Future): A future to the client's public-private key
                 pair.
@@ -55,12 +55,7 @@ class LazyRefreshCache:
                 (Postgres and MySQL) as the default authentication method for all
                 connections.
         """
-        # validate and parse instance connection name
-        self._project, self._region, self._instance = _parse_instance_connection_name(
-            instance_connection_string
-        )
-        self._instance_connection_string = instance_connection_string
-
+        self._conn_name = conn_name
         self._enable_iam_auth = enable_iam_auth
         self._keys = keys
         self._client = client
@@ -91,34 +86,31 @@ class LazyRefreshCache:
                 < (self._cached.expiration - timedelta(seconds=_refresh_buffer))
             ):
                 logger.debug(
-                    f"['{self._instance_connection_string}']: Connection info "
+                    f"['{self._conn_name}']: Connection info "
                     "is still valid, using cached info"
                 )
                 return self._cached
             logger.debug(
-                f"['{self._instance_connection_string}']: Connection info "
-                "refresh operation started"
+                f"['{self._conn_name}']: Connection info " "refresh operation started"
             )
             try:
                 conn_info = await self._client.get_connection_info(
-                    self._project,
-                    self._region,
-                    self._instance,
+                    self._conn_name,
                     self._keys,
                     self._enable_iam_auth,
                 )
             except Exception as e:
                 logger.debug(
-                    f"['{self._instance_connection_string}']: Connection info "
+                    f"['{self._conn_name}']: Connection info "
                     f"refresh operation failed: {str(e)}"
                 )
                 raise
             logger.debug(
-                f"['{self._instance_connection_string}']: Connection info "
+                f"['{self._conn_name}']: Connection info "
                 "refresh operation completed successfully"
             )
             logger.debug(
-                f"['{self._instance_connection_string}']: Current certificate "
+                f"['{self._conn_name}']: Current certificate "
                 f"expiration = {str(conn_info.expiration)}"
             )
             self._cached = conn_info

google/cloud/sql/connector/pg8000.py

@@ -13,6 +13,7 @@ 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.
 """
+
 import socket
 import ssl
 from typing import Any, TYPE_CHECKING

google/cloud/sql/connector/pymysql.py

@@ -13,6 +13,7 @@ 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.
 """
+
 import socket
 import ssl
 from typing import Any, TYPE_CHECKING

google/cloud/sql/connector/pytds.py

@@ -13,6 +13,7 @@ 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.
 """
+
 import platform
 import socket
 import ssl

google/cloud/sql/connector/refresh_utils.py

@@ -21,7 +21,7 @@ import copy
 import datetime
 import logging
 import random
-from typing import Any, Callable, List
+from typing import Any, Callable
 
 import aiohttp
 from google.auth.credentials import Credentials
@@ -77,7 +77,7 @@ async def _is_valid(task: asyncio.Task) -> bool:
 
 def _downscope_credentials(
     credentials: Credentials,
-    scopes: List[str] = ["https://www.googleapis.com/auth/sqlservice.login"],
+    scopes: list[str] = ["https://www.googleapis.com/auth/sqlservice.login"],
 ) -> Credentials:
     """Generate a down-scoped credential.
 
@@ -85,7 +85,7 @@ def _downscope_credentials(
     :param credentials
         Credentials object used to generate down-scoped credentials.
 
-    :type scopes: List[str]
+    :type scopes: list[str]
     :param scopes
         List of Google scopes to include in down-scoped credentials object.
 

google/cloud/sql/connector/resolver.py

@@ -0,0 +1,70 @@
+# 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.
+
+import dns.asyncresolver
+
+from google.cloud.sql.connector.connection_name import (
+    _parse_connection_name_with_domain_name,
+)
+from google.cloud.sql.connector.connection_name import _parse_connection_name
+from google.cloud.sql.connector.connection_name import ConnectionName
+from google.cloud.sql.connector.exceptions import DnsResolutionError
+
+
+class DefaultResolver:
+    """DefaultResolver simply validates and parses instance connection name."""
+
+    async def resolve(self, connection_name: str) -> ConnectionName:
+        return _parse_connection_name(connection_name)
+
+
+class DnsResolver(dns.asyncresolver.Resolver):
+    """
+    DnsResolver resolves domain names into instance connection names using
+    TXT records in DNS.
+    """
+
+    async def resolve(self, dns: str) -> ConnectionName:  # type: ignore
+        try:
+            conn_name = _parse_connection_name(dns)
+        except ValueError:
+            # The connection name was not project:region:instance format.
+            # Attempt to query a TXT record to get connection name.
+            conn_name = await self.query_dns(dns)
+        return conn_name
+
+    async def query_dns(self, dns: str) -> ConnectionName:
+        try:
+            # Attempt to query the TXT records.
+            records = await super().resolve(dns, "TXT", raise_on_no_answer=True)
+            # Sort the TXT record values alphabetically, strip quotes as record
+            # values can be returned as raw strings
+            rdata = [record.to_text().strip('"') for record in records]
+            rdata.sort()
+            # Attempt to parse records, returning the first valid record.
+            for record in rdata:
+                try:
+                    conn_name = _parse_connection_name_with_domain_name(record, dns)
+                    return conn_name
+                except Exception:
+                    continue
+            # If all records failed to parse, throw error
+            raise DnsResolutionError(
+                f"Unable to parse TXT record for `{dns}` -> `{rdata[0]}`"
+            )
+        # Don't override above DnsResolutionError
+        except DnsResolutionError:
+            raise
+        except Exception as e:
+            raise DnsResolutionError(f"Unable to resolve TXT record for `{dns}`") from e

google/cloud/sql/connector/utils.py

@@ -14,15 +14,13 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Tuple
-
 import aiofiles
 from cryptography.hazmat.backends import default_backend
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric import rsa
 
 
-async def generate_keys() -> Tuple[bytes, str]:
+async def generate_keys() -> tuple[bytes, str]:
     """A helper function to generate the private and public keys.
 
     backend - The value specified is default_backend(). This is because the
@@ -61,7 +59,7 @@ async def generate_keys() -> Tuple[bytes, str]:
 
 async def write_to_file(
     dir_path: str, serverCaCert: str, ephemeralCert: str, priv_key: bytes
-) -> Tuple[str, str, str]:
+) -> tuple[str, str, str]:
     """
     Helper function to write the serverCaCert, ephemeral certificate and
     private key to .pem files in a given directory

google/cloud/sql/connector/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "1.13.0"
+__version__ = "1.15.0"

cloud_sql_python_connector-1.13.0.dist-info/RECORD

@@ -1,22 +0,0 @@
-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=dqUYJdUdusV_s2Xs0uWFmKqqoOU4mpHkrgl0qqbx9Vw,11713
-google/cloud/sql/connector/connection_info.py,sha256=exxhtb0-rk8J3OIotf8drEPMx8pke17hAX_Mbt7gOts,4336
-google/cloud/sql/connector/connector.py,sha256=NWyuwUoAsCuPxxzjB9OiD19tD1LdcQtqfbxJOLlS5-A,20731
-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=nQVZVfEijbO3XEj1oU68cR-u8Nx99rRM2a8aXaygOg0,3534
-google/cloud/sql/connector/version.py,sha256=EWwYfhVJ-gfn9Us5uJphJ-6hyY5hIvZ1lMkYVSAinqo,598
-cloud_sql_python_connector-1.13.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-cloud_sql_python_connector-1.13.0.dist-info/METADATA,sha256=4D0iy9DJ08BNblMe2HaliEjMi6Wee_eQVQY_JT7nb4o,25950
-cloud_sql_python_connector-1.13.0.dist-info/WHEEL,sha256=bb2Ot9scclHKMOLDEHY6B2sicWOgugjFKaJsT7vwMQo,110
-cloud_sql_python_connector-1.13.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
-cloud_sql_python_connector-1.13.0.dist-info/RECORD,,