cloud-sql-python-connector 1.23.0__py3-none-any.whl → 1.24.0__py3-none-any.whl

{cloud_sql_python_connector-1.23.0.dist-info → cloud_sql_python_connector-1.24.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloud-sql-python-connector
-Version: 1.23.0
+Version: 1.24.0
 Summary: Google Cloud SQL Python Connector library
 Author-email: Google LLC <googleapis-packages@google.com>
 License-Expression: Apache-2.0
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -789,6 +790,84 @@ async def main():
         await pool.dispose()
 ```
 
+### Post-Quantum Cryptography (PQC)
+
+The Cloud SQL Python Connector establishes mTLS connections over TLS 1.3 using
+Python's standard `ssl` module without restricting key-exchange groups. When
+Python's `ssl` module is linked against **OpenSSL 3.5 or later**, TLS 1.3
+connections automatically offer and negotiate the hybrid post-quantum key
+exchange group **`X25519MLKEM768`** (ML-KEM-768 combined with X25519) whenever
+the Cloud SQL instance supports it. No code changes or connector configuration
+are required.
+
+#### Checking your OpenSSL version
+
+Post-quantum TLS key exchange depends on the OpenSSL library linked into your
+Python runtime's `ssl` module (not the Python language version or the
+`cryptography` package version alone). Run the following command to check which
+OpenSSL version your Python interpreter uses:
+
+```sh
+python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
+```
+
+- **OpenSSL 3.5.0 or higher** (for example, `python:3.13-trixie` / Debian 13
+  "Trixie" container images; check your runtime with the one-liner above):
+  `X25519MLKEM768` is enabled by default on TLS 1.3 connections.
+- **OpenSSL earlier than 3.5.0** (for example, Ubuntu 24.04 LTS, which ships
+  system OpenSSL 3.0.x): TLS 1.3 connections continue to use classical elliptic
+  curve Diffie-Hellman (such as `X25519` or `P-256`).
+
+> [!NOTE]
+>
+> Connections configured with `ip_type="sql_data"` (`IPTypes.SQL_DATA`) stream
+> over gRPC (`grpcio`), which uses its bundled BoringSSL (supporting
+> `X25519MLKEM768` independently of Python's `ssl` module and `OPENSSL_CONF`),
+> whereas its direct-TLS fallback path uses `create_ssl_context()` and Python's
+> linked OpenSSL library as described above.
+
+#### Backwards compatibility
+
+Hybrid post-quantum key exchange is backwards-compatible. On OpenSSL 3.5+,
+Python's `ssl` module advertises both hybrid (`X25519MLKEM768`) and classical
+(`X25519`, `secp256r1`, etc.) groups in the TLS 1.3 `ClientHello`. If either the
+client runtime (OpenSSL `< 3.5`) or the Cloud SQL instance only supports
+classical groups, the TLS 1.3 handshake automatically falls back to classical
+ECDHE without error.
+
+#### Opting out
+
+If you need to disable post-quantum key exchange on an OpenSSL 3.5+ client (for
+example, to troubleshoot a network middlebox sensitive to larger TLS
+`ClientHello` records), configure OpenSSL's `Groups` list via an OpenSSL
+configuration file (`OPENSSL_CONF`) to advertise only classical curves.
+
+> [!WARNING]
+>
+> Setting `OPENSSL_CONF` replaces the system default OpenSSL configuration for
+> the entire Python process. It affects **all** TLS connections made by the
+> process (not just Cloud SQL connections), and starting from a minimal file
+> omits distribution defaults (such as Debian's `MinProtocol` or
+> `CipherString`). Copy your system's `openssl.cnf` (check `openssl version -d`,
+> typically `/etc/ssl/openssl.cnf`) and add `Groups = X25519:P-256:P-384` under
+> its `[system_default_sect]` section rather than using a bare file from
+> scratch.
+
+For example, after copying `/etc/ssl/openssl.cnf`, ensure its
+`[system_default_sect]` (referenced via `ssl_conf` -> `system_default`) sets
+`Groups`:
+
+```ini
+[system_default_sect]
+Groups = X25519:P-256:P-384
+```
+
+Then point `OPENSSL_CONF` to your modified copy when starting your application:
+
+```sh
+OPENSSL_CONF=/path/to/openssl.cnf python3 app.py
+```
+
 ### Debug Logging
 
 The Cloud SQL Python Connector uses the standard [Python logging module][python-logging]

{cloud_sql_python_connector-1.23.0.dist-info → cloud_sql_python_connector-1.24.0.dist-info}/RECORD

@@ -1,16 +1,17 @@
-cloud_sql_python_connector-1.23.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cloud_sql_python_connector-1.24.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
 google/cloud/sql/connector/__init__.py,sha256=pfa-FD-VRpYI49OUul9p6UFDp7G_yT2f6WS9rZMn8CM,1148
 google/cloud/sql/connector/asyncpg.py,sha256=MpZhwFke0WXvYD3OcEF1Ok0qHl-CU7ZIPy85PCog5QY,2002
 google/cloud/sql/connector/client.py,sha256=GfiZKDDBOxeA0yfqETQuaw3Nhg0BS71oQNZNxq3CooY,14991
-google/cloud/sql/connector/connection_info.py,sha256=lwhrOG01efvvvR2gXiesiZ1BrXJ4iP7geoRi0zI80do,5666
+google/cloud/sql/connector/connection_info.py,sha256=NnHSHs1PZ_9WeFICkZ53gbA2hVvlWuzdBdhWizOI6hs,5770
 google/cloud/sql/connector/connection_name.py,sha256=SCCVeWb8YN0f9My09_l9FGTr6iRbi1b_52TJQaS6xzM,2574
-google/cloud/sql/connector/connector.py,sha256=at6WZJJCwQ3Ds8Ssd3ZF9bSJJYwN10Yxh-oK9UhkmFc,37843
+google/cloud/sql/connector/connector.py,sha256=8A4uxTIGJKxnRgG2TqBHQwi4dG5KPO_1vNAQkNrR5vs,41574
 google/cloud/sql/connector/enums.py,sha256=F_mUdwscpW2fAzw4XElSy4BWkWcGQAkBOAUG8bvd3vg,3118
 google/cloud/sql/connector/exceptions.py,sha256=-QgsUq4gZaMrl3MH5KnsfJybEegAKW84-sdRmPKT-Dg,3137
-google/cloud/sql/connector/instance.py,sha256=Lz4kjwBdp3IVb6xpjPEJkawR7LS89XPLZSOt-IDxunI,8677
-google/cloud/sql/connector/lazy.py,sha256=MDJTAcB5iOqYYMewbzuX0RWh5PdIrY4RWpYfmFUYkr0,4918
-google/cloud/sql/connector/monitored_cache.py,sha256=5YAVjdiQaywZOqzQlvx9HkPLxA8tlV0HhQDJFsa1_qc,6674
+google/cloud/sql/connector/instance.py,sha256=j3xj3ZuSpV7AcQz6_eYsS6F6bFPySKcGeFYfNOnIEKU,17269
+google/cloud/sql/connector/lazy.py,sha256=9OOSfr13aX1OSA77V72Utp8M8VUQlwLloogRlUm0GDE,6746
+google/cloud/sql/connector/monitored_cache.py,sha256=BarNBg-VsthW5bguGl3aq17IP4QaiF099W0AnrboujM,6919
 google/cloud/sql/connector/pg8000.py,sha256=tbqFSIoSguMX1hTZ4kWeBOKLhLHKX1Vq5SespfA0Y0w,1801
+google/cloud/sql/connector/postgres_connection.py,sha256=NCUCZ_X6svNoJaqSClYDyqXaIArZYPQrPZu7wC-LtjU,7509
 google/cloud/sql/connector/psycopg.py,sha256=UD7OFVJ7C_PPsiIWzpbi1k3YIkqC4rM1pQS08wPeSM0,10950
 google/cloud/sql/connector/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 google/cloud/sql/connector/pymysql.py,sha256=MOau37nTOTesUR5Hor7lLtEckvvGThzjECEWQYHcM8U,2166
@@ -18,10 +19,10 @@ google/cloud/sql/connector/pytds.py,sha256=e-KBCqv0m3a7cRi9YmFHNuYqClhlJbf-KoF61
 google/cloud/sql/connector/rate_limiter.py,sha256=60k-r9h-nUBqovVIHnIGbW0NMgUGD4exH_rZ02ukNa0,2924
 google/cloud/sql/connector/refresh_utils.py,sha256=Eghd-_uR5ndCGLsPgnyeUOoAvN7Tz4yzTlQFW4QWOjo,5228
 google/cloud/sql/connector/resolver.py,sha256=4U8G0Pxwmy64qoRmP5shLnmIykxcGcGCoFSH_7tr120,6353
-google/cloud/sql/connector/sqldata_client.py,sha256=gIgfgyYN5tBjYJxEWzvJkL67FCjhYxjg2Qs_2Z7QBhU,23862
-google/cloud/sql/connector/utils.py,sha256=ApLG4z4H0S4lWXQ9PyclXbrEoY5VrshqN9QB6BG8lyg,4132
-google/cloud/sql/connector/version.py,sha256=cbp_THzh62LsaoqJEz9Prs5EyZAWmeu6HB74bMAMqGY,598
-cloud_sql_python_connector-1.23.0.dist-info/METADATA,sha256=7dGxD8x9D5bsEnn9BmzbZtSN1mMGpAmcqj8w6EFPRjo,31777
-cloud_sql_python_connector-1.23.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-cloud_sql_python_connector-1.23.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
-cloud_sql_python_connector-1.23.0.dist-info/RECORD,,
+google/cloud/sql/connector/sqldata_client.py,sha256=vov9R3xI_0LBxByMUIBDBsXZOE64cnUADp25Tp4Kvo0,23892
+google/cloud/sql/connector/utils.py,sha256=bGsWj_SupSBmxcnsaMlmREP7hyLV7CcZ4g2_qHzHVoA,4119
+google/cloud/sql/connector/version.py,sha256=juuKD5HYyccQin3zqup25QoyaBFJQnEtQgG7cgdeFIg,598
+cloud_sql_python_connector-1.24.0.dist-info/METADATA,sha256=fLmn8G44gYU1v-gXeu3FvCGScL1xqipmX6lh3UfSB1w,35170
+cloud_sql_python_connector-1.24.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+cloud_sql_python_connector-1.24.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
+cloud_sql_python_connector-1.24.0.dist-info/RECORD,,

{cloud_sql_python_connector-1.23.0.dist-info → cloud_sql_python_connector-1.24.0.dist-info}/WHEEL

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

google/cloud/sql/connector/connection_info.py

@@ -46,6 +46,10 @@ class ConnectionInfoCache(abc.ABC):
     async def force_refresh(self) -> None:
         pass
 
+    @abc.abstractmethod
+    def record_principal(self, user: str, database: str) -> None:
+        pass
+
     @abc.abstractmethod
     async def close(self) -> None:
         pass

google/cloud/sql/connector/connector.py

@@ -23,6 +23,7 @@ import logging
 import os
 import random
 import socket
+import ssl
 from threading import Thread
 import time
 from types import TracebackType
@@ -38,6 +39,7 @@ from google.cloud.sql.connector import psycopg
 from google.cloud.sql.connector import pymysql
 from google.cloud.sql.connector import pytds
 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.enums import DriverMapping
 from google.cloud.sql.connector.enums import IPTypes
@@ -49,6 +51,7 @@ from google.cloud.sql.connector.exceptions import ResourceExhaustedError
 from google.cloud.sql.connector.instance import RefreshAheadCache
 from google.cloud.sql.connector.lazy import LazyRefreshCache
 from google.cloud.sql.connector.monitored_cache import MonitoredCache
+from google.cloud.sql.connector.postgres_connection import PostgresConnection
 from google.cloud.sql.connector.resolver import DefaultResolver
 from google.cloud.sql.connector.resolver import DnsResolver
 from google.cloud.sql.connector.sqldata_client import SqlDataClient
@@ -346,6 +349,7 @@ class Connector:
         self,
         conn_name: ConnectionName,
         enable_iam_auth: bool,
+        ip_type: IPTypes | None = None,
     ) -> MonitoredCache:
         assert self._client is not None, "client must be initialized before creating cache"
         assert self._keys is not None, "keys must be initialized before creating cache"
@@ -355,6 +359,13 @@ class Connector:
         ].closed:
             return self._cache[(str(conn_name), enable_iam_auth)]
 
+        effective_ip_type = ip_type if ip_type is not None else self._ip_type
+        dial_func = partial(
+            self._dial_probe_connection,
+            enable_iam_auth=enable_iam_auth,
+            ip_type=effective_ip_type,
+        )
+
         if self._refresh_strategy == RefreshStrategy.LAZY:
             logger.debug(
                 f"['{conn_name}']: Refresh strategy is set to lazy refresh"
@@ -364,6 +375,9 @@ class Connector:
                 self._client,
                 self._keys,
                 enable_iam_auth,
+                ip_type=effective_ip_type,
+                timeout=self._timeout,
+                dial_func=dial_func,
             )
         else:
             logger.debug(
@@ -374,6 +388,9 @@ class Connector:
                 self._client,
                 self._keys,
                 enable_iam_auth,
+                ip_type=effective_ip_type,
+                timeout=self._timeout,
+                dial_func=dial_func,
             )
         # wrap cache as a MonitoredCache
         monitored_cache = MonitoredCache(
@@ -452,7 +469,9 @@ class Connector:
 
         conn_name = await self._resolver.resolve(instance_connection_string)
         if ip_type != IPTypes.SQL_DATA:
-            monitored_cache = self._get_or_create_cache(conn_name, enable_iam_auth)
+            monitored_cache = self._get_or_create_cache(
+                conn_name, enable_iam_auth, ip_type
+            )
 
         connect_func = {
             "pymysql": pymysql.connect,
@@ -587,33 +606,7 @@ class Connector:
                     await self._remove_cached(str(conn_name), enable_iam_auth)
                     raise
 
-                targets = []
-                if conn_info.conn_name.domain_name and isinstance(self._resolver, DnsResolver):
-                    try:
-                        ips = await self._resolver.resolve_a_record(conn_info.conn_name.domain_name)
-                        if ips:
-                            targets.extend(ips)
-                            logger.debug(
-                                f"['{instance_connection_string}']: Custom DNS name "
-                                f"'{conn_info.conn_name.domain_name}' resolved to '{ips}', "
-                                "using it to connect"
-                            )
-                        else:
-                            logger.debug(
-                                f"['{instance_connection_string}']: Custom DNS name "
-                                f"'{conn_info.conn_name.domain_name}' resolved but returned no "
-                                f"entries, using '{preferred_ips}' from instance metadata"
-                            )
-                            targets.extend(preferred_ips)
-                    except Exception as e:  # noqa: BLE001
-                        logger.debug(
-                            f"['{instance_connection_string}']: Custom DNS name "
-                            f"'{conn_info.conn_name.domain_name}' did not resolve to an IP "
-                            f"address: {e}, using '{preferred_ips}' from instance metadata"
-                        )
-                        targets.extend(preferred_ips)
-                else:
-                    targets.extend(preferred_ips)
+                targets = await self._resolve_targets(conn_info, preferred_ips)
                 # format `user` param for automatic IAM database authn
                 if enable_iam_auth:
                     formatted_user = format_database_user(
@@ -636,14 +629,28 @@ class Connector:
                                 await conn_info.create_ssl_context(enable_iam_auth),
                                 **kwargs,
                             )
+                            if (
+                                enable_iam_auth
+                                and conn_info.database_version.startswith("POSTGRES")
+                            ):
+                                db_name = kwargs.get("database")
+                                if db_name is None:
+                                    db_name = kwargs.get("db")
+                                user = kwargs.get("user")
+                                if user:
+                                    monitored_cache.record_principal(
+                                        str(user),
+                                        str(db_name) if db_name else str(user),
+                                    )
                             last_ex = None
                             return conn
 
                         # Create socket with SSLContext for sync drivers
                         ctx = await conn_info.create_ssl_context(enable_iam_auth)
                         raw_sock = socket.create_connection((target_ip, SERVER_PROXY_PORT))
+                        sync_sock: socket.socket | ssl.SSLSocket | PostgresConnection
                         try:
-                            sock = ctx.wrap_socket(
+                            sync_sock = ctx.wrap_socket(
                                 raw_sock,
                                 server_hostname=target_ip,
                             )
@@ -651,15 +658,24 @@ class Connector:
                             raw_sock.close()
                             raise
 
+                        if (
+                            enable_iam_auth
+                            and conn_info.database_version.startswith("POSTGRES")
+                        ):
+                            sync_sock = PostgresConnection(
+                                sync_sock,
+                                on_startup=monitored_cache.record_principal,
+                            )
+
                         # If this connection was opened using a domain name, then store it
                         # for later in case we need to forcibly close it on failover.
                         if conn_info.conn_name.domain_name:
-                            monitored_cache.sockets.append(sock)
+                            monitored_cache.sockets.append(sync_sock)
                         # Synchronous drivers are blocking and run using executor
                         connect_partial = partial(
                             connector,
                             target_ip,
-                            sock,
+                            sync_sock,
                             **kwargs,
                         )
                         conn = await self._loop.run_in_executor(None, connect_partial)
@@ -670,7 +686,6 @@ class Connector:
                             f"['{conn_info.conn_name}']: Connection to {target_ip} failed: {e}"
                         )
                         last_ex = e
-
                 if last_ex:
                     raise last_ex
 
@@ -694,6 +709,87 @@ class Connector:
         cache = self._cache.pop((instance_connection_string, enable_iam_auth))
         await cache.close()
 
+    async def _resolve_targets(
+        self,
+        conn_info: ConnectionInfo,
+        preferred_ips: list[str],
+    ) -> list[str]:
+        """Resolves target IP addresses for a Cloud SQL instance, with DNS fallback."""
+        targets: list[str] = []
+        if conn_info.conn_name.domain_name and isinstance(self._resolver, DnsResolver):
+            try:
+                ips = await self._resolver.resolve_a_record(
+                    conn_info.conn_name.domain_name
+                )
+                if ips:
+                    targets.extend(ips)
+                    logger.debug(
+                        f"['{conn_info.conn_name}']: Custom DNS name "
+                        f"'{conn_info.conn_name.domain_name}' resolved to '{ips}', "
+                        "using it to connect"
+                    )
+                else:
+                    logger.debug(
+                        f"['{conn_info.conn_name}']: Custom DNS name "
+                        f"'{conn_info.conn_name.domain_name}' resolved but returned no "
+                        f"entries, using '{preferred_ips}' from instance metadata"
+                    )
+                    targets.extend(preferred_ips)
+            except Exception as e:  # noqa: BLE001
+                logger.debug(
+                    f"['{conn_info.conn_name}']: Custom DNS name "
+                    f"'{conn_info.conn_name.domain_name}' did not resolve to an IP "
+                    f"address: {e}, using '{preferred_ips}' from instance metadata"
+                )
+                targets.extend(preferred_ips)
+        else:
+            targets.extend(preferred_ips)
+        return targets
+
+    async def _dial_probe_connection(
+        self,
+        conn_info: ConnectionInfo,
+        enable_iam_auth: bool,
+        ip_type: IPTypes | None = None,
+    ) -> tuple[asyncio.StreamReader, asyncio.StreamWriter]:
+        """Dials a TLS probe connection using the connector's IP resolution and SSLContext."""
+        effective_ip_type = ip_type if ip_type is not None else self._ip_type
+        preferred_ips = conn_info.get_preferred_ips(effective_ip_type)
+        targets = await self._resolve_targets(conn_info, preferred_ips)
+
+        if not targets:
+            raise ConnectionError(
+                f"No target IP addresses found for {conn_info.conn_name}"
+            )
+
+        ssl_context = await conn_info.create_ssl_context(enable_iam_auth)
+        server_hostname = (
+            conn_info.conn_name.domain_name
+            if conn_info.conn_name.domain_name
+            else None
+        )
+
+        last_err: Exception | None = None
+        for target in targets:
+            try:
+                reader, writer = await asyncio.wait_for(
+                    asyncio.open_connection(
+                        host=target,
+                        port=SERVER_PROXY_PORT,
+                        ssl=ssl_context,
+                        server_hostname=server_hostname,
+                    ),
+                    timeout=float(max(1, self._timeout)),
+                )
+                return reader, writer
+            except Exception as e:  # noqa: BLE001
+                last_err = e
+        if last_err:
+            raise last_err
+        raise ConnectionError(
+            f"Failed to connect to any target for {conn_info.conn_name}"
+        )
+
     def __enter__(self) -> Any:
         """Enter context manager by returning Connector object"""
         return self

google/cloud/sql/connector/instance.py

@@ -17,6 +17,8 @@ limitations under the License.
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Awaitable
+from collections.abc import Callable
 from datetime import datetime
 from datetime import timedelta
 from datetime import UTC
@@ -26,7 +28,10 @@ from google.cloud.sql.connector.client import CloudSQLClient
 from google.cloud.sql.connector.connection_info import ConnectionInfo
 from google.cloud.sql.connector.connection_info import ConnectionInfoCache
 from google.cloud.sql.connector.connection_name import ConnectionName
+from google.cloud.sql.connector.enums import IPTypes
 from google.cloud.sql.connector.exceptions import RefreshNotValidError
+from google.cloud.sql.connector.postgres_connection import build_postgres_startup_packet
+from google.cloud.sql.connector.postgres_connection import build_terminate_packet
 from google.cloud.sql.connector.rate_limiter import AsyncRateLimiter
 from google.cloud.sql.connector.refresh_utils import _is_valid
 from google.cloud.sql.connector.refresh_utils import _seconds_until_refresh
@@ -34,6 +39,8 @@ from google.cloud.sql.connector.refresh_utils import _seconds_until_refresh
 logger = logging.getLogger(name=__name__)
 
 APPLICATION_NAME = "cloud-sql-python-connector"
+SERVER_PROXY_PORT = 3307
+DEFAULT_CONNECT_TIMEOUT = 30
 
 
 class RefreshAheadCache(ConnectionInfoCache):
@@ -50,6 +57,15 @@ class RefreshAheadCache(ConnectionInfoCache):
         client: CloudSQLClient,
         keys: asyncio.Future,
         enable_iam_auth: bool = False,
+        ip_type: IPTypes | str = IPTypes.PUBLIC,
+        timeout: int = DEFAULT_CONNECT_TIMEOUT,
+        dial_func: (
+            Callable[
+                [ConnectionInfo],
+                Awaitable[tuple[asyncio.StreamReader, asyncio.StreamWriter]],
+            ]
+            | None
+        ) = None,
     ) -> None:
         """Initializes a RefreshAheadCache instance.
 
@@ -62,10 +78,18 @@ class RefreshAheadCache(ConnectionInfoCache):
             enable_iam_auth (bool): Enables automatic IAM database authentication
                 (Postgres and MySQL) as the default authentication method for all
                 connections.
+            ip_type (IPTypes | str): Preferred IP type used to connect to the instance.
+            timeout (int): Connect timeout in seconds.
+            dial_func: Optional callable to dial probe connections.
         """
         self._conn_name = conn_name
 
         self._enable_iam_auth = enable_iam_auth
+        if isinstance(ip_type, str):
+            ip_type = IPTypes._from_str(ip_type)
+        self._ip_type = ip_type
+        self._timeout = timeout
+        self._dial_func = dial_func
         self._keys = keys
         self._client = client
         self._refresh_rate_limiter = AsyncRateLimiter(
@@ -73,10 +97,15 @@ class RefreshAheadCache(ConnectionInfoCache):
             rate=1 / 30,
         )
         self._refresh_in_progress = asyncio.locks.Event()
+        self._iam_principals: list[tuple[str, str]] = []
         self._current: asyncio.Task = self._schedule_refresh(0)
         self._next: asyncio.Task = self._current
         self._closed = False
 
+    def record_principal(self, user: str, database: str) -> None:
+        """Records a PostgreSQL (user, database) pair observed on an IAM connection."""
+        _append_iam_principal(self._iam_principals, user, database)
+
     @property
     def conn_name(self) -> ConnectionName:
         return self._conn_name
@@ -119,6 +148,8 @@ class RefreshAheadCache(ConnectionInfoCache):
                 self._keys,
                 self._enable_iam_auth,
             )
+            if self._enable_iam_auth:
+                await self._probe_connection(connection_info)
             logger.debug(
                 f"['{self._conn_name}']: Connection info refresh operation complete"
             )
@@ -138,6 +169,18 @@ class RefreshAheadCache(ConnectionInfoCache):
             self._refresh_in_progress.clear()
         return connection_info
 
+    async def _probe_connection(self, conn_info: ConnectionInfo) -> None:
+        """Proactively probes the database to refresh IAM tokens on server-side MCP."""
+        await _probe_instance_connection(
+            self._conn_name,
+            conn_info,
+            self._enable_iam_auth,
+            self._ip_type,
+            self._timeout,
+            self._iam_principals,
+            self._dial_func,
+        )
+
     def _schedule_refresh(self, delay: int) -> asyncio.Task:
         """
         Schedule task to sleep and then perform refresh to get ConnectionInfo.
@@ -223,3 +266,196 @@ class RefreshAheadCache(ConnectionInfoCache):
         tasks = asyncio.gather(self._current, self._next, return_exceptions=True)
         await asyncio.wait_for(tasks, timeout=2.0)
         self._closed = True
+
+
+def _append_iam_principal(
+    principals: list[tuple[str, str]], user: str, database: str
+) -> None:
+    """Appends (user, database) to principals if not already present."""
+    if not user:
+        return
+    if not database:
+        database = user
+    pair = (user, database)
+    if pair not in principals:
+        principals.append(pair)
+
+
+async def _probe_instance_connection(
+    conn_name: ConnectionName,
+    conn_info: ConnectionInfo,
+    enable_iam_auth: bool,
+    ip_type: IPTypes,
+    timeout: int,
+    iam_principals: list[tuple[str, str]],
+    dial_func: (
+        Callable[
+            [ConnectionInfo],
+            Awaitable[tuple[asyncio.StreamReader, asyncio.StreamWriter]],
+        ]
+        | None
+    ) = None,
+) -> None:
+    """Proactively probes the database to refresh IAM tokens on server-side MCP."""
+    if not enable_iam_auth:
+        return
+
+    # Proactive IAM refresh probe is PostgreSQL-only.
+    if not conn_info.database_version.startswith("POSTGRES"):
+        logger.debug(
+            f"['{conn_name}']: Proactive IAM token refresh probe skipped: instance engine '{conn_info.database_version}' is not PostgreSQL"
+        )
+        return
+
+    # Do not probe if no IAM principals have connected yet.
+    if not iam_principals:
+        logger.debug(
+            f"['{conn_name}']: Proactive IAM token refresh probe skipped: no IAM principals connected"
+        )
+        return
+
+    targets: list[str] = []
+    ssl_context = None
+    if dial_func is None:
+        if conn_name.domain_name:
+            targets.append(conn_name.domain_name)
+        if ip_type.value in conn_info.ip_addrs:
+            targets.extend(conn_info.ip_addrs[ip_type.value])
+
+        if not targets:
+            logger.debug(
+                f"['{conn_name}']: Proactive IAM token refresh probe skipped: no target IP addresses"
+            )
+            return
+
+        try:
+            ssl_context = await conn_info.create_ssl_context(enable_iam_auth)
+        except Exception as e:  # noqa: BLE001
+            logger.debug(
+                f"['{conn_name}']: Failed to create SSL context for probe: {e!s}"
+            )
+            return
+
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + float(max(1, timeout))
+
+    all_succeeded = True
+    for user, database in list(iam_principals):
+        remaining = deadline - loop.time()
+        if remaining <= 0:
+            all_succeeded = False
+            break
+
+        probed_principal = False
+        if dial_func is not None:
+            try:
+                reader, writer = await asyncio.wait_for(
+                    dial_func(conn_info),
+                    timeout=remaining,
+                )
+                probed_principal = await _send_startup_probe(
+                    reader,
+                    writer,
+                    user,
+                    database,
+                    max(0.0, deadline - loop.time()),
+                    conn_name,
+                )
+            except Exception as e:  # noqa: BLE001
+                logger.debug(
+                    f"['{conn_name}']: Probing IAM token refresh for ({user}, {database}) failed: {e!s}"
+                )
+        else:
+            for target in targets:
+                remaining = deadline - loop.time()
+                if remaining <= 0:
+                    break
+                try:
+                    logger.debug(
+                        f"['{conn_name}']: Probing IAM token refresh on {target}:{SERVER_PROXY_PORT}"
+                    )
+                    reader, writer = await asyncio.wait_for(
+                        asyncio.open_connection(
+                            host=target,
+                            port=SERVER_PROXY_PORT,
+                            ssl=ssl_context,
+                            server_hostname=(
+                                conn_name.domain_name
+                                if conn_name.domain_name
+                                else None
+                            ),
+                        ),
+                        timeout=remaining,
+                    )
+                    probed_principal = await _send_startup_probe(
+                        reader,
+                        writer,
+                        user,
+                        database,
+                        max(0.0, deadline - loop.time()),
+                        conn_name,
+                    )
+                    break
+                except Exception as e:  # noqa: BLE001
+                    logger.debug(
+                        f"['{conn_name}']: Probing IAM token refresh on {target}:{SERVER_PROXY_PORT} failed: {e!s}"
+                    )
+        if not probed_principal:
+            all_succeeded = False
+
+    if all_succeeded:
+        logger.debug(
+            f"['{conn_name}']: Proactive IAM token refresh probe successful"
+        )
+    else:
+        logger.debug(
+            f"['{conn_name}']: Proactive IAM token refresh probe encountered error across all targets"
+        )
+
+
+async def _send_startup_probe(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    user: str,
+    database: str,
+    timeout: float,
+    conn_name: ConnectionName,
+) -> bool:
+    """Sends a PostgreSQL StartupMessage probe and gracefully terminates."""
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + max(0.0, float(timeout))
+    try:
+        remaining = deadline - loop.time()
+        if remaining <= 0:
+            return False
+        writer.write(build_postgres_startup_packet(user, database))
+        await asyncio.wait_for(writer.drain(), timeout=remaining)
+        await asyncio.wait_for(
+            reader.read(1024),
+            timeout=max(0.0, deadline - loop.time()),
+        )
+        writer.write(build_terminate_packet())
+        await asyncio.wait_for(
+            writer.drain(),
+            timeout=max(0.0, deadline - loop.time()),
+        )
+        eof_timeout = min(max(0.0, deadline - loop.time()), 1.0)
+        if eof_timeout > 0:
+            try:
+                await asyncio.wait_for(reader.read(1024), timeout=eof_timeout)
+            except Exception as e:  # noqa: BLE001
+                logger.debug(
+                    f"['{conn_name}']: Ignoring error while waiting for server EOF: {e!s}"
+                )
+        return True
+    finally:
+        writer.close()
+        try:
+            await asyncio.wait_for(writer.wait_closed(), timeout=2.0)
+        except Exception as e:  # noqa: BLE001
+            logger.debug(
+                f"['{conn_name}']: Ignoring error while waiting for socket to close: {e!s}"
+            )
+            transport = getattr(writer, "transport", None)
+            if transport is not None and hasattr(transport, "abort"):
+                transport.abort()

google/cloud/sql/connector/lazy.py

@@ -15,6 +15,8 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Awaitable
+from collections.abc import Callable
 from datetime import datetime
 from datetime import timedelta
 from datetime import UTC
@@ -24,6 +26,10 @@ from google.cloud.sql.connector.client import CloudSQLClient
 from google.cloud.sql.connector.connection_info import ConnectionInfo
 from google.cloud.sql.connector.connection_info import ConnectionInfoCache
 from google.cloud.sql.connector.connection_name import ConnectionName
+from google.cloud.sql.connector.enums import IPTypes
+from google.cloud.sql.connector.instance import _append_iam_principal
+from google.cloud.sql.connector.instance import _probe_instance_connection
+from google.cloud.sql.connector.instance import DEFAULT_CONNECT_TIMEOUT
 from google.cloud.sql.connector.refresh_utils import _refresh_buffer
 
 logger = logging.getLogger(name=__name__)
@@ -44,6 +50,15 @@ class LazyRefreshCache(ConnectionInfoCache):
         client: CloudSQLClient,
         keys: asyncio.Future,
         enable_iam_auth: bool = False,
+        ip_type: IPTypes | str = IPTypes.PUBLIC,
+        timeout: int = DEFAULT_CONNECT_TIMEOUT,
+        dial_func: (
+            Callable[
+                [ConnectionInfo],
+                Awaitable[tuple[asyncio.StreamReader, asyncio.StreamWriter]],
+            ]
+            | None
+        ) = None,
     ) -> None:
         """Initializes a LazyRefreshCache instance.
 
@@ -56,16 +71,29 @@ class LazyRefreshCache(ConnectionInfoCache):
             enable_iam_auth (bool): Enables automatic IAM database authentication
                 (Postgres and MySQL) as the default authentication method for all
                 connections.
+            ip_type (IPTypes | str): Preferred IP type used to connect to the instance.
+            timeout (int): Connect timeout in seconds.
+            dial_func: Optional callable to dial probe connections.
         """
         self._conn_name = conn_name
         self._enable_iam_auth = enable_iam_auth
+        if isinstance(ip_type, str):
+            ip_type = IPTypes._from_str(ip_type)
+        self._ip_type = ip_type
+        self._timeout = timeout
+        self._dial_func = dial_func
         self._keys = keys
         self._client = client
         self._lock = asyncio.Lock()
+        self._iam_principals: list[tuple[str, str]] = []
         self._cached: ConnectionInfo | None = None
         self._needs_refresh = False
         self._closed = False
 
+    def record_principal(self, user: str, database: str) -> None:
+        """Records a PostgreSQL (user, database) pair observed on an IAM connection."""
+        _append_iam_principal(self._iam_principals, user, database)
+
     @property
     def conn_name(self) -> ConnectionName:
         return self._conn_name
@@ -82,6 +110,18 @@ class LazyRefreshCache(ConnectionInfoCache):
         async with self._lock:
             self._needs_refresh = True
 
+    async def _probe_connection(self, conn_info: ConnectionInfo) -> None:
+        """Proactively probes the database to refresh IAM tokens on server-side MCP."""
+        await _probe_instance_connection(
+            self._conn_name,
+            conn_info,
+            self._enable_iam_auth,
+            self._ip_type,
+            self._timeout,
+            self._iam_principals,
+            self._dial_func,
+        )
+
     async def connect_info(self) -> ConnectionInfo:
         """Retrieves ConnectionInfo instance for establishing a secure
         connection to the Cloud SQL instance.
@@ -126,7 +166,11 @@ class LazyRefreshCache(ConnectionInfoCache):
             )
             self._cached = conn_info
             self._needs_refresh = False
-            return conn_info
+
+        if self._enable_iam_auth:
+            await self._probe_connection(conn_info)
+
+        return conn_info
 
     async def close(self) -> None:
         """Close is a no-op and provided purely for a consistent interface with

google/cloud/sql/connector/monitored_cache.py

@@ -18,6 +18,7 @@ import asyncio
 from collections.abc import Callable
 import logging
 import socket
+import ssl
 from typing import Any
 
 import aiohttp
@@ -28,6 +29,7 @@ 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.postgres_connection import PostgresConnection
 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
@@ -45,7 +47,7 @@ class MonitoredCache(ConnectionInfoCache):
         self.resolver = resolver
         self.cache = cache
         self.domain_name_ticker: asyncio.Task | None = None
-        self.sockets: list[socket.socket] = []
+        self.sockets: list[socket.socket | ssl.SSLSocket | PostgresConnection] = []
 
         # If domain name is configured for instance and failover period is set,
         # poll for DNS record changes.
@@ -140,6 +142,9 @@ class MonitoredCache(ConnectionInfoCache):
             return
         return await self.cache.force_refresh()
 
+    def record_principal(self, user: str, database: str) -> None:
+        self.cache.record_principal(user, database)
+
     async def close(self) -> None:
         # Cancel domain name ticker task.
         if self.domain_name_ticker:

google/cloud/sql/connector/postgres_connection.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
+
+  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 __future__ import annotations
+
+from collections.abc import Callable
+import socket
+import ssl
+from typing import Any
+
+MAX_PG_STARTUP_PACKET_LEN = 10000
+PG_PROTOCOL_VERSION_30 = 196608  # 0x00030000
+PG_SSL_REQUEST_CODE = 80877103  # 0x04d2162f
+PG_GSS_ENC_REQUEST_CODE = 80877104  # 0x04d21630
+
+
+class PostgresConnection:
+    """Wraps a socket to inspect initial client-side PostgreSQL v3 StartupMessage bytes.
+
+    Extracts the (user, database) principal pair for Auto-IAM refresh probes.
+    Handles chunked streaming across multiple write/send operations.
+    Once the startup message is detected or determined not to be a PostgreSQL v3
+    startup packet, startup_message_sent is set to True, the internal buffer is
+    cleared, and all subsequent writes pass through directly with zero overhead.
+
+    Like standard Python socket and stream wrappers, callers own synchronization
+    for concurrent writes; no internal lock is acquired on the write path.
+    """
+
+    def __init__(
+        self,
+        sock: socket.socket | ssl.SSLSocket,
+        on_startup: Callable[[str, str], None],
+    ) -> None:
+        self._sock = sock
+        self._on_startup = on_startup
+        self._buf = bytearray()
+        self.startup_message_sent = False
+
+    def _inspect(self, data: bytes | bytearray | memoryview) -> None:
+        if self.startup_message_sent or not data:
+            return
+        self._buf.extend(data)
+        user, database, complete = parse_postgres_startup_packet(self._buf)
+        if complete:
+            self.startup_message_sent = True
+            self._buf.clear()
+            if user:
+                self._on_startup(user, database)
+        elif len(self._buf) > MAX_PG_STARTUP_PACKET_LEN + 16:
+            self.startup_message_sent = True
+            self._buf.clear()
+
+    def send(
+        self,
+        data: bytes | bytearray | memoryview,
+        *args: Any,
+        **kwargs: Any,
+    ) -> int:
+        sent = self._sock.send(data, *args, **kwargs)
+        if not self.startup_message_sent:
+            chunk = data[:sent] if isinstance(sent, int) else data
+            if chunk:
+                self._inspect(chunk)
+        return sent
+
+    def sendall(
+        self,
+        data: bytes | bytearray | memoryview,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        self._sock.sendall(data, *args, **kwargs)
+        if not self.startup_message_sent and data:
+            self._inspect(data)
+
+    def write(self, data: bytes | bytearray | memoryview) -> int:
+        written = (
+            self._sock.write(data)
+            if hasattr(self._sock, "write")
+            else self._sock.send(data)
+        )
+        if not self.startup_message_sent:
+            chunk = data[:written] if isinstance(written, int) else data
+            if chunk:
+                self._inspect(chunk)
+        return written
+
+    @property
+    def _io_refs(self) -> int:
+        return getattr(self._sock, "_io_refs", 0)
+
+    @_io_refs.setter
+    def _io_refs(self, value: int) -> None:
+        self._sock._io_refs = value  # type: ignore[union-attr]
+
+    def makefile(
+        self,
+        mode: str = "r",
+        buffering: int | None = None,
+        *,
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
+    ) -> Any:
+        """Returns an I/O stream connected to this wrapped socket so makefile writes are inspected."""
+        return socket.socket.makefile(  # type: ignore[call-overload]
+            self,
+            mode=mode,
+            buffering=buffering,
+            encoding=encoding,
+            errors=errors,
+            newline=newline,
+        )
+
+    def close(self) -> None:
+        self._sock.close()
+
+    def fileno(self) -> int:
+        return self._sock.fileno()
+
+    def __enter__(self) -> Any:
+        return self
+
+    def __exit__(self, *args: object) -> Any:
+        if hasattr(self._sock, "__exit__"):
+            return self._sock.__exit__(*args)
+        return None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._sock, name)
+
+
+def parse_postgres_startup_packet(
+    buf: bytes | bytearray | memoryview,
+) -> tuple[str, str, bool]:
+    """Parses a buffer to extract the PostgreSQL v3 StartupMessage (user, database) pair.
+
+    Returns:
+        (user, database, complete):
+            complete is True if the packet was fully parsed (or rejected),
+            False if more bytes are needed (partial packet).
+    """
+    data = bytes(buf)
+    # Step 1: Skip prepended SSLRequest (80877103) or GSSENCRequest (80877104) (can occur in succession).
+    while len(data) >= 8:
+        pkt_len = int.from_bytes(data[0:4], byteorder="big")
+        code = int.from_bytes(data[4:8], byteorder="big")
+        if pkt_len == 8 and (
+            code == PG_SSL_REQUEST_CODE or code == PG_GSS_ENC_REQUEST_CODE
+        ):
+            data = data[8:]
+        else:
+            break
+
+    # Step 2: Wait for at least 8 bytes (4-byte packet length + 4-byte protocol code).
+    if len(data) < 8:
+        return "", "", False
+
+    pkt_len = int.from_bytes(data[0:4], byteorder="big")
+    code = int.from_bytes(data[4:8], byteorder="big")
+
+    # Step 3: Validate protocol version (v3.0) and packet length bounds.
+    if (
+        code != PG_PROTOCOL_VERSION_30
+        or pkt_len < 8
+        or pkt_len > MAX_PG_STARTUP_PACKET_LEN
+    ):
+        return "", "", True
+
+    # Step 4: Wait until the complete packet body has arrived.
+    if len(data) < pkt_len:
+        return "", "", False
+
+    # Step 5: Decode null-terminated key-value pairs (user, database) from the payload.
+    payload = data[8:pkt_len]
+    user = ""
+    database = ""
+    while payload and payload[0] != 0:
+        try:
+            k_end = payload.index(0)
+        except ValueError:
+            break
+        key = payload[:k_end].decode("utf-8", errors="replace")
+        payload = payload[k_end + 1 :]
+        try:
+            v_end = payload.index(0)
+        except ValueError:
+            break
+        val = payload[:v_end].decode("utf-8", errors="replace")
+        payload = payload[v_end + 1 :]
+
+        if key == "user":
+            user = val
+        elif key == "database":
+            database = val
+
+    if user and not database:
+        database = user
+
+    # Step 6: Successfully extracted credentials.
+    return user, database, True
+
+
+def build_postgres_startup_packet(user: str, database: str) -> bytes:
+    """Builds a PostgreSQL v3.0 StartupMessage for (user, database)."""
+    if not database:
+        database = user
+    body = (
+        b"user\x00"
+        + user.encode("utf-8")
+        + b"\x00database\x00"
+        + database.encode("utf-8")
+        + b"\x00\x00"
+    )
+    total_len = 8 + len(body)
+    return total_len.to_bytes(4, byteorder="big") + b"\x00\x03\x00\x00" + body
+
+
+def build_terminate_packet() -> bytes:
+    """Builds a PostgreSQL Terminate packet ('X' followed by int32 length 4)."""
+    return b"X\x00\x00\x00\x04"

google/cloud/sql/connector/sqldata_client.py

@@ -30,7 +30,7 @@ from google.api_core.exceptions import ResourceExhausted
 from google.auth.credentials import Credentials
 import grpc
 
-from google.cloud import sqladmin_v1beta4
+from google.cloud import sqladmin_v1beta4  # type: ignore[attr-defined]
 from google.cloud.sql.connector.enums import IPTypes
 from google.cloud.sql.connector.exceptions import CloudSQLIPTypeError
 

google/cloud/sql/connector/utils.py

@@ -52,7 +52,7 @@ async def generate_keys() -> tuple[bytes, str]:
 
     priv_key = private_key_obj.private_bytes(
         encoding=serialization.Encoding.PEM,
-        format=serialization.PrivateFormat.TraditionalOpenSSL,
+        format=serialization.PrivateFormat.PKCS8,
         encryption_algorithm=serialization.NoEncryption(),
     )
 

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.23.0"
+__version__ = "1.24.0"