cloud-sql-python-connector 1.20.4__py3-none-any.whl → 1.22.0__py3-none-any.whl

google/cloud/sql/connector/enums.py

@@ -61,7 +61,8 @@ class DriverMapping(Enum):
     """Maps a given database driver to it's corresponding database engine."""
 
     ASYNCPG = "POSTGRES"
-    PG8000 = "POSTGRES"
+    PG8000 = "POSTGRES"  # noqa: PIE796
+    PSYCOPG = "POSTGRES"  # noqa: PIE796
     PYMYSQL = "MYSQL"
     PYTDS = "SQLSERVER"
 

google/cloud/sql/connector/exceptions.py

@@ -21,7 +21,6 @@ class ConnectorLoopError(Exception):
     in an invalid state (event loop in current thread).
     """
 
-    pass
 
 
 class TLSVersionError(Exception):
@@ -29,7 +28,6 @@ class TLSVersionError(Exception):
     Raised when the required TLS protocol version is not supported.
     """
 
-    pass
 
 
 class CloudSQLIPTypeError(Exception):
@@ -37,7 +35,6 @@ class CloudSQLIPTypeError(Exception):
     Raised when IP address for the preferred IP type is not found.
     """
 
-    pass
 
 
 class PlatformNotSupportedError(Exception):
@@ -45,7 +42,6 @@ class PlatformNotSupportedError(Exception):
     Raised when a feature is not supported on the current platform.
     """
 
-    pass
 
 
 class AutoIAMAuthNotSupported(Exception):
@@ -54,7 +50,6 @@ class AutoIAMAuthNotSupported(Exception):
     supported with database engine version.
     """
 
-    pass
 
 
 class RefreshNotValidError(Exception):
@@ -62,7 +57,6 @@ class RefreshNotValidError(Exception):
     Exception to be raised when the task returned from refresh is not valid.
     """
 
-    pass
 
 
 class IncompatibleDriverError(Exception):
@@ -79,6 +73,12 @@ class DnsResolutionError(Exception):
     """
 
 
+class DnsLoopError(DnsResolutionError):
+    """
+    Exception to be raised when a CNAME loop is detected during DNS resolution.
+    """
+
+
 class CacheClosedError(Exception):
     """
     Exception to be raised when a ConnectionInfoCache can not be accessed after

google/cloud/sql/connector/instance.py

@@ -130,7 +130,7 @@ class RefreshAheadCache(ConnectionInfoCache):
         except Exception as e:
             logger.debug(
                 f"['{self._conn_name}']: Connection info "
-                f"refresh operation failed: {str(e)}"
+                f"refresh operation failed: {e!s}"
             )
             raise
 

google/cloud/sql/connector/lazy.py

@@ -12,12 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import asyncio
 from datetime import datetime
 from datetime import timedelta
 from datetime import timezone
 import logging
-from typing import Optional
 
 from google.cloud.sql.connector.client import CloudSQLClient
 from google.cloud.sql.connector.connection_info import ConnectionInfo
@@ -61,7 +62,7 @@ class LazyRefreshCache(ConnectionInfoCache):
         self._keys = keys
         self._client = client
         self._lock = asyncio.Lock()
-        self._cached: Optional[ConnectionInfo] = None
+        self._cached: ConnectionInfo | None = None
         self._needs_refresh = False
         self._closed = False
 
@@ -112,7 +113,7 @@ class LazyRefreshCache(ConnectionInfoCache):
             except Exception as e:
                 logger.debug(
                     f"['{self._conn_name}']: Connection info "
-                    f"refresh operation failed: {str(e)}"
+                    f"refresh operation failed: {e!s}"
                 )
                 raise
             logger.debug(
@@ -121,7 +122,7 @@ class LazyRefreshCache(ConnectionInfoCache):
             )
             logger.debug(
                 f"['{self._conn_name}']: Current certificate "
-                f"expiration = {str(conn_info.expiration)}"
+                f"expiration = {conn_info.expiration!s}"
             )
             self._cached = conn_info
             self._needs_refresh = False
@@ -132,4 +133,3 @@ class LazyRefreshCache(ConnectionInfoCache):
         other cache types.
         """
         self._closed = True
-        return

google/cloud/sql/connector/monitored_cache.py

@@ -12,18 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import asyncio
 import logging
 import ssl
-from typing import Any, Callable, Optional, Union
+from typing import Any, Callable
+
+import aiohttp
 
 from google.cloud.sql.connector.connection_info import ConnectionInfo
 from google.cloud.sql.connector.connection_info import ConnectionInfoCache
 from google.cloud.sql.connector.exceptions import CacheClosedError
+from google.cloud.sql.connector.exceptions import DnsLoopError
 from google.cloud.sql.connector.instance import RefreshAheadCache
 from google.cloud.sql.connector.lazy import LazyRefreshCache
 from google.cloud.sql.connector.resolver import DefaultResolver
 from google.cloud.sql.connector.resolver import DnsResolver
+from google.cloud.sql.connector.resolver import is_instance_dns_name
 
 logger = logging.getLogger(name=__name__)
 
@@ -31,18 +37,27 @@ logger = logging.getLogger(name=__name__)
 class MonitoredCache(ConnectionInfoCache):
     def __init__(
         self,
-        cache: Union[RefreshAheadCache, LazyRefreshCache],
+        cache: RefreshAheadCache | LazyRefreshCache,
         failover_period: int,
-        resolver: Union[DefaultResolver, DnsResolver],
+        resolver: DefaultResolver | DnsResolver,
     ) -> None:
         self.resolver = resolver
         self.cache = cache
-        self.domain_name_ticker: Optional[asyncio.Task] = None
+        self.domain_name_ticker: asyncio.Task | None = None
         self.sockets: list[ssl.SSLSocket] = []
 
         # If domain name is configured for instance and failover period is set,
         # poll for DNS record changes.
-        if self.cache.conn_name.domain_name and failover_period > 0:
+        is_instance_dns = False
+        if self.cache.conn_name.domain_name:
+            is_instance_dns = is_instance_dns_name(
+                self.cache.conn_name.domain_name or ""
+            )
+        if (
+            self.cache.conn_name.domain_name
+            and failover_period > 0
+            and not is_instance_dns
+        ):
             self.domain_name_ticker = asyncio.create_task(
                 ticker(failover_period, self._check_domain_name)
             )
@@ -87,13 +102,29 @@ class MonitoredCache(ConnectionInfoCache):
                 )
                 await self.close()
 
-        except Exception as e:
-            # Domain name checks should not be fatal, log error and continue.
-            logger.debug(
-                f"['{self.cache.conn_name}']: Unable to check domain name, "
-                f"domain name {self.cache.conn_name.domain_name} did not "
-                f"resolve: {e}"
+        except Exception as e:  # noqa: BLE001
+            if self._is_non_transient(e):
+                logger.debug(
+                    f"['{self.cache.conn_name}']: Domain name check failed with "
+                    f"non-transient error, closing all connections: {e}"
+                )
+                await self.close()
+            else:
+                # Domain name checks should not be fatal for transient errors, log error and continue.
+                logger.debug(
+                    f"['{self.cache.conn_name}']: Unable to check domain name, "
+                    f"domain name {self.cache.conn_name.domain_name} did not "
+                    f"resolve (transient error): {e}"
+                )
+
+    def _is_non_transient(self, e: Exception) -> bool:
+        return (
+            isinstance(e, (ValueError, DnsLoopError))
+            or (
+                isinstance(e, aiohttp.ClientResponseError)
+                and e.status in (403, 404)
             )
+        )
 
     async def connect_info(self) -> ConnectionInfo:
         if self.closed:

google/cloud/sql/connector/pg8000.py

@@ -48,7 +48,9 @@ def connect(
         )
 
     user = kwargs.pop("user")
-    db = kwargs.pop("db")
+    db = kwargs.pop("database", kwargs.pop("db", None))
+    if db is None:
+        raise KeyError("database")
     passwd = kwargs.pop("password", None)
     return pg8000.dbapi.connect(
         user,

google/cloud/sql/connector/psycopg.py

@@ -0,0 +1,235 @@
+# Copyright 2026 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 logging
+import os
+import selectors
+import socket
+import ssl
+import tempfile
+import threading
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import psycopg
+
+logger = logging.getLogger(name=__name__)
+
+
+def _proxy(local: socket.socket, remote: "ssl.SSLSocket") -> None:
+    """Single-threaded selectors-based proxy to avoid SSLSocket thread-safety issues."""
+    sel = selectors.DefaultSelector()
+    sel.register(local, selectors.EVENT_READ, data="local")
+    sel.register(remote, selectors.EVENT_READ, data="remote")
+
+    def forward_pending() -> bool:
+        """Read any pending decrypted data from SSL buffer and forward it.
+        Returns True if EOF was reached or error occurred (should exit).
+        """
+        if not hasattr(remote, "pending"):
+            return False
+        pending_bytes = remote.pending()
+        if not isinstance(pending_bytes, int):
+            return False
+
+        while pending_bytes > 0:
+            try:
+                data = remote.recv(8192)
+            except OSError as e:
+                logger.debug("psycopg proxy: remote recv pending error: %s", e)
+                return True
+            if not data:
+                logger.debug("psycopg proxy: remote pending EOF")
+                return True
+            try:
+                local.sendall(data)
+            except OSError as e:
+                logger.debug("psycopg proxy: local send pending error: %s", e)
+                return True
+            try:
+                pending_bytes = remote.pending()
+            except OSError:
+                break
+            if not isinstance(pending_bytes, int):
+                break
+        return False
+
+    try:
+        while True:
+            # First check if there is any pending data in SSL buffer
+            if forward_pending():
+                break
+
+            events = sel.select()
+
+            for key, mask in events:
+                if key.data == "local":
+                    try:
+                        data = local.recv(8192)
+                    except OSError as e:
+                        logger.debug("psycopg proxy: local recv error: %s", e)
+                        return
+                    if not data:
+                        logger.debug("psycopg proxy: local EOF")
+                        return
+                    try:
+                        remote.sendall(data)
+                    except OSError as e:
+                        logger.debug("psycopg proxy: remote send error: %s", e)
+                        return
+                elif key.data == "remote":
+                    try:
+                        data = remote.recv(8192)
+                    except OSError as e:
+                        logger.debug("psycopg proxy: remote recv error: %s", e)
+                        return
+                    if not data:
+                        logger.debug("psycopg proxy: remote EOF")
+                        return
+                    try:
+                        local.sendall(data)
+                    except OSError as e:
+                        logger.debug("psycopg proxy: local send error: %s", e)
+                        return
+    except OSError as e:
+        logger.debug("psycopg proxy: OSError in loop: %s", e)
+    finally:
+        sel.close()
+        for s in (local, remote):
+            try:
+                s.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+            try:
+                s.close()
+            except OSError:
+                pass
+
+
+def connect(
+    ip_address: str, remote_sock: "ssl.SSLSocket", **kwargs: Any
+) -> "psycopg.Connection":
+    """Create a psycopg DBAPI connection object.
+
+    Because psycopg does not accept a pre-connected socket, this function
+    creates a temporary Unix domain socket, tells psycopg to connect there,
+    and runs a background proxy that forwards bytes between that socket and
+    the already-established Cloud SQL TLS connection.
+
+    Args:
+        ip_address (str): IP address of the Cloud SQL instance.
+        remote_sock (ssl.SSLSocket): SSL/TLS secure socket stream connected to the
+            Cloud SQL proxy server.
+
+    Returns:
+        psycopg.Connection: A psycopg Connection object for the Cloud SQL instance.
+    """
+    try:
+        import psycopg
+    except ImportError:
+        raise ImportError(
+            'Unable to import module "psycopg." Please install and try again.'
+        )
+
+    if not hasattr(socket, "AF_UNIX"):
+        raise NotImplementedError(
+            "Unix domain sockets (AF_UNIX) are not supported on this platform"
+        )
+
+    tmpdir = tempfile.mkdtemp()
+    socket_path = os.path.join(tmpdir, ".s.PGSQL.5432")
+    logger.debug("psycopg: created Unix socket at %s", socket_path)
+
+    local_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    local_sock.bind(socket_path)
+    local_sock.listen(1)
+
+    def _accept_and_proxy() -> None:
+        """Accept one connection then proxy bytes until the connection closes."""
+        unix_conn = None
+        try:
+            unix_conn, _ = local_sock.accept()
+            local_sock.close()
+            logger.debug("psycopg proxy: accepted connection, starting proxy")
+            _proxy(unix_conn, remote_sock)
+        except Exception as e:  # noqa: BLE001
+            logger.debug("psycopg proxy: error in accept/proxy thread: %s", e)
+            # Ensure cleanup on any exception
+            if unix_conn:
+                try:
+                    unix_conn.shutdown(socket.SHUT_RDWR)
+                except OSError:
+                    pass
+                try:
+                    unix_conn.close()
+                except OSError:
+                    pass
+            try:
+                remote_sock.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+            try:
+                remote_sock.close()
+            except OSError:
+                pass
+
+    threading.Thread(target=_accept_and_proxy, daemon=True).start()
+
+    user = kwargs.pop("user")
+    db = kwargs.pop("db")
+    passwd = kwargs.pop("password", None)
+    # SSL is already handled by the underlying SSLSocket; disable it on the
+    # Unix socket so psycopg does not attempt a second TLS handshake.
+    kwargs.pop("sslmode", None)
+    timeout = kwargs.pop("timeout", None)
+    if timeout is not None:
+        kwargs["connect_timeout"] = int(timeout)
+
+    logger.debug("psycopg: connecting as user=%s dbname=%s", user, db)
+    try:
+        conn = psycopg.connect(
+            user=user,
+            dbname=db,
+            password=passwd,
+            host=tmpdir,
+            port=5432,
+            sslmode="disable",
+            **kwargs,
+        )
+        logger.debug("psycopg: connection established")
+        return conn
+    except Exception as e:
+        logger.debug("psycopg: connection failed: %s", e)
+        # psycopg never connected (or failed mid-handshake); close the server
+        # socket so the proxy thread unblocks and exits cleanly.
+        try:
+            local_sock.close()
+        except OSError:
+            pass
+        try:
+            remote_sock.close()
+        except OSError:
+            pass
+        raise
+    finally:
+        # The socket file and its parent directory are only needed during the
+        # initial connect() call; remove them now regardless of outcome.
+        try:
+            os.remove(socket_path)
+        except OSError:
+            pass
+        try:
+            os.rmdir(tmpdir)
+        except OSError:
+            pass

google/cloud/sql/connector/pymysql.py

@@ -47,11 +47,18 @@ def connect(
         )
 
     # allow automatic IAM database authentication to not require password
-    kwargs["password"] = kwargs["password"] if "password" in kwargs else None
+    kwargs["password"] = kwargs.get("password", None)
 
     # pop timeout as timeout arg is called 'connect_timeout' for pymysql
     timeout = kwargs.pop("timeout")
     kwargs["connect_timeout"] = kwargs.get("connect_timeout", timeout)
+
+    # map 'db' to 'database' to avoid deprecation warning in pymysql,
+    # giving precedence to 'database' if both are provided
+    db = kwargs.pop("database", kwargs.pop("db", None))
+    if db is not None:
+        kwargs["database"] = db
+
     # Create pymysql connection object and hand in pre-made connection
     conn = pymysql.Connection(host=ip_address, defer_connect=True, **kwargs)
     conn.connect(sock)

google/cloud/sql/connector/pytds.py

@@ -47,7 +47,7 @@ def connect(ip_address: str, sock: ssl.SSLSocket, **kwargs: Any) -> "pytds.Conne
             'Unable to import module "pytds." Please install and try again.'
         )
 
-    db = kwargs.pop("db", None)
+    db = kwargs.pop("database", kwargs.pop("db", None))
 
     if kwargs.pop("active_directory_auth", False):
         if platform.system() == "Windows":

google/cloud/sql/connector/rate_limiter.py

@@ -13,12 +13,12 @@ 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
-from typing import Optional
 
 
-class AsyncRateLimiter(object):
+class AsyncRateLimiter:
     """An asyncio-compatible rate limiter which uses the Token Bucket algorithm
     (https://en.wikipedia.org/wiki/Token_bucket) to limit the number
     of function calls over a time interval using an event queue.
@@ -35,7 +35,7 @@ class AsyncRateLimiter(object):
         self,
         max_capacity: int = 1,
         rate: float = 1 / 60,
-        loop: Optional[asyncio.AbstractEventLoop] = None,
+        loop: asyncio.AbstractEventLoop | None = None,
     ) -> None:
         self.rate = rate
         self.max_capacity = max_capacity

google/cloud/sql/connector/refresh_utils.py

@@ -72,7 +72,7 @@ async def _is_valid(task: asyncio.Task) -> bool:
         # only valid if now is before the cert expires
         if datetime.datetime.now(datetime.timezone.utc) < metadata.expiration:
             return True
-    except Exception:
+    except Exception:  # noqa: BLE001
         # supress any errors from task
         logger.debug("Current instance metadata is invalid.")
     return False
@@ -80,7 +80,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] | None = None,
 ) -> Credentials:
     """Generate a down-scoped credential.
 
@@ -95,6 +95,8 @@ def _downscope_credentials(
     """
     # credentials sourced from a service account or metadata are children of
     # Scoped class and are capable of being re-scoped
+    if scopes is None:
+        scopes = ["https://www.googleapis.com/auth/sqlservice.login"]
     if isinstance(credentials, Scoped):
         scoped_creds = credentials.with_scopes(scopes=scopes)
     # authenticated user credentials can not be re-scoped