cloud-sql-python-connector 1.17.0.dev0__py3-none-any.whl

cloud_sql_python_connector-1.17.0.dev0.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=emahfH9ZSrbooFBV-m6gcwGJ7yYQwaUJuCJPz0DHfHA,22547
+google/cloud/sql/connector/enums.py,sha256=dVBS9eEWNrHtzze0AJlmtbdUogG3EocNWOQcI_8qPd0,2937
+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=YfNpSkpcPhRwrFt2dV7ut5xGe0KjgvNinweha483X2w,603
+cloud_sql_python_connector-1.17.0.dev0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cloud_sql_python_connector-1.17.0.dev0.dist-info/METADATA,sha256=qlls3nyZF0ZxHsLxEvorF9ukUEyY5pQpWUhvbQ0H2tk,30494
+cloud_sql_python_connector-1.17.0.dev0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+cloud_sql_python_connector-1.17.0.dev0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
+cloud_sql_python_connector-1.17.0.dev0.dist-info/RECORD,,

cloud_sql_python_connector-1.17.0.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cloud_sql_python_connector-1.17.0.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+google

google/cloud/sql/connector/__init__.py

@@ -0,0 +1,33 @@
+""""
+Copyright 2019 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
+
+  https://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 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

@@ -0,0 +1,65 @@
+"""
+Copyright 2022 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
+
+  https://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 ssl
+from typing import Any, TYPE_CHECKING
+
+SERVER_PROXY_PORT = 3307
+
+if TYPE_CHECKING:
+    import asyncpg
+
+
+async def connect(
+    ip_address: str, ctx: ssl.SSLContext, **kwargs: Any
+) -> "asyncpg.Connection":
+    """Helper function to create an asyncpg DB-API connection object.
+
+    :type ip_address: str
+    :param ip_address: A string containing an IP address for the Cloud SQL
+        instance.
+
+    :type ctx: ssl.SSLContext
+    :param ctx: An SSLContext object created from the Cloud SQL server CA
+        cert and ephemeral cert.
+
+    :type kwargs: Any
+    :param kwargs: Keyword arguments for establishing asyncpg connection
+        object to Cloud SQL instance.
+
+    :rtype: asyncpg.Connection
+    :returns: An asyncpg.Connection object to a Cloud SQL instance.
+    """
+    try:
+        import asyncpg
+    except ImportError:
+        raise ImportError(
+            'Unable to import module "asyncpg." Please install and try again.'
+        )
+    user = kwargs.pop("user")
+    db = kwargs.pop("db")
+    passwd = kwargs.pop("password", None)
+
+    return await asyncpg.connect(
+        user=user,
+        database=db,
+        password=passwd,
+        host=ip_address,
+        port=SERVER_PROXY_PORT,
+        ssl=ctx,
+        direct_tls=True,
+        **kwargs,
+    )

google/cloud/sql/connector/client.py

@@ -0,0 +1,324 @@
+# 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
+
+import asyncio
+import datetime
+import logging
+from typing import Any, Optional, TYPE_CHECKING
+
+import aiohttp
+from cryptography.hazmat.backends import default_backend
+from cryptography.x509 import load_pem_x509_certificate
+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
+from google.cloud.sql.connector.version import __version__ as version
+
+if TYPE_CHECKING:
+    from google.auth.credentials import Credentials
+
+USER_AGENT: str = f"cloud-sql-python-connector/{version}"
+API_VERSION: str = "v1beta4"
+DEFAULT_SERVICE_ENDPOINT: str = "https://sqladmin.googleapis.com"
+
+logger = logging.getLogger(name=__name__)
+
+
+def _format_user_agent(driver: Optional[str], custom: Optional[str]) -> str:
+    agent = f"{USER_AGENT}+{driver}" if driver else USER_AGENT
+    if custom and isinstance(custom, str):
+        agent = f"{agent} {custom}"
+    return agent
+
+
+class CloudSQLClient:
+    def __init__(
+        self,
+        sqladmin_api_endpoint: Optional[str],
+        quota_project: Optional[str],
+        credentials: Credentials,
+        client: Optional[aiohttp.ClientSession] = None,
+        driver: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        """
+        Establish the client to be used for Cloud SQL Admin API requests.
+
+        Args:
+            sqladmin_api_endpoint (str): Base URL to use when calling
+                the Cloud SQL Admin API endpoints.
+            quota_project (str): The Project ID for an existing Google Cloud
+                project. The project specified is used for quota and
+                billing purposes.
+            credentials (google.auth.credentials.Credentials):
+                A credentials object created from the google-auth Python library.
+                Must have the Cloud SQL Admin scopes. For more info check out
+                https://google-auth.readthedocs.io/en/latest/.
+            client (aiohttp.ClientSession): Async client used to make requests to
+                Cloud SQL Admin APIs.
+                Optional, defaults to None and creates new client.
+            driver (str): Database driver to be used by the client.
+        """
+        user_agent = _format_user_agent(driver, user_agent)
+        headers = {
+            "x-goog-api-client": user_agent,
+            "User-Agent": user_agent,
+            "Content-Type": "application/json",
+        }
+        if quota_project:
+            headers["x-goog-user-project"] = quota_project
+
+        self._client = client if client else aiohttp.ClientSession(headers=headers)
+        self._credentials = credentials
+        if sqladmin_api_endpoint is None:
+            self._sqladmin_api_endpoint = DEFAULT_SERVICE_ENDPOINT
+        else:
+            self._sqladmin_api_endpoint = sqladmin_api_endpoint
+        self._user_agent = user_agent
+
+    async def _get_metadata(
+        self,
+        project: str,
+        region: str,
+        instance: str,
+    ) -> 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.
+
+        :type project: str
+        :param project:
+            A string representing the name of the project.
+
+        :type region: str
+        :param region : A string representing the name of the region.
+
+        :type instance: str
+        :param instance: A string representing the name of the instance.
+
+        :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.
+        """
+
+        headers = {
+            "Authorization": f"Bearer {self._credentials.token}",
+        }
+
+        url = f"{self._sqladmin_api_endpoint}/sql/{API_VERSION}/projects/{project}/instances/{instance}/connectSettings"
+
+        resp = await self._client.get(url, headers=headers)
+        if resp.status >= 500:
+            resp = await retry_50x(self._client.get, url, headers=headers)
+        # 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(
+                f'[{project}:{region}:{instance}]: Provided region was mismatched - got region {region}, expected {ret_dict["region"]}.'
+            )
+
+        ip_addresses = (
+            {ip["type"]: ip["ipAddress"] for ip in ret_dict["ipAddresses"]}
+            if "ipAddresses" in ret_dict
+            else {}
+        )
+        # resolve dnsName into IP address for PSC
+        # Note that we have to check for PSC enablement also because CAS
+        # instances also set the dnsName field.
+        # Remove trailing period from DNS name. Required for SSL in Python
+        dns_name = ret_dict.get("dnsName", "").rstrip(".")
+        if dns_name and ret_dict.get("pscEnabled"):
+            ip_addresses["PSC"] = dns_name
+
+        return {
+            "ip_addresses": ip_addresses,
+            "server_ca_cert": ret_dict["serverCaCert"]["cert"],
+            "database_version": ret_dict["databaseVersion"],
+        }
+
+    async def _get_ephemeral(
+        self,
+        project: str,
+        instance: str,
+        pub_key: str,
+        enable_iam_auth: bool = False,
+    ) -> tuple[str, datetime.datetime]:
+        """Asynchronously requests an ephemeral certificate from the Cloud SQL Instance.
+
+        :type project: str
+        :param project : A string representing the name of the project.
+
+        :type instance: str
+        :param instance: A string representing the name of the instance.
+
+        :type pub_key:
+        :param str: A string representing PEM-encoded RSA public key.
+
+        :type enable_iam_auth: bool
+        :param enable_iam_auth
+            Enables automatic IAM database authentication for Postgres or MySQL
+            instances.
+
+        :rtype: str
+        :returns: An ephemeral certificate from the Cloud SQL instance that allows
+            authorized connections to the instance.
+        """
+        headers = {
+            "Authorization": f"Bearer {self._credentials.token}",
+        }
+
+        url = f"{self._sqladmin_api_endpoint}/sql/{API_VERSION}/projects/{project}/instances/{instance}:generateEphemeralCert"
+
+        data = {"public_key": pub_key}
+
+        if enable_iam_auth:
+            # down-scope credentials with only IAM login scope (refreshes them too)
+            login_creds = _downscope_credentials(self._credentials)
+            data["access_token"] = login_creds.token
+
+        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)
+        # 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"]
+
+        # decode cert to read expiration
+        x509 = load_pem_x509_certificate(
+            ephemeral_cert.encode("UTF-8"), default_backend()
+        )
+        expiration = x509.not_valid_after_utc
+        # for IAM authentication OAuth2 token is embedded in cert so it
+        # must still be valid for successful connection
+        if enable_iam_auth:
+            token_expiration: datetime.datetime = login_creds.expiry
+            # google.auth library strips timezone info for backwards compatibality
+            # reasons with Python 2. Add it back to allow timezone aware datetimes.
+            # Ref: https://github.com/googleapis/google-auth-library-python/blob/49a5ff7411a2ae4d32a7d11700f9f961c55406a9/google/auth/_helpers.py#L93-L99
+            token_expiration = token_expiration.replace(tzinfo=datetime.timezone.utc)
+
+            if expiration > token_expiration:
+                expiration = token_expiration
+        return ephemeral_cert, expiration
+
+    async def get_connection_info(
+        self,
+        conn_name: ConnectionName,
+        keys: asyncio.Future,
+        enable_iam_auth: bool,
+    ) -> ConnectionInfo:
+        """Immediately performs a full refresh operation using the Cloud SQL
+        Admin API.
+
+        Args:
+            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
+                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(
+                conn_name.project,
+                conn_name.region,
+                conn_name.instance_name,
+            )
+        )
+
+        ephemeral_task = asyncio.create_task(
+            self._get_ephemeral(
+                conn_name.project,
+                conn_name.instance_name,
+                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(
+            conn_name,
+            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,108 @@
+# 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 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
+
+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."""
+
+    conn_name: ConnectionName
+    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
+
+    async 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
+        async with TemporaryDirectory() as tmpdir:
+            ca_filename, cert_filename, key_filename = await 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}"
+        )

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,
+    )