cloud-sql-python-connector

The Cloud SQL Python Connector is a Google-maintained library for connecting securely to Cloud SQL instances from Python. It provides a native, in-process alternative to the Cloud SQL Auth Proxy, handling TLS 1.3 encryption, identity verification, and IAM-based authorization so applications can reach MySQL, PostgreSQL, and SQL Server instances without managing SSL certificates, firewalls, or source/destination IP addresses.

The connector works alongside a standard database driver (pymysql, pg8000, asyncpg, or pytds), producing authenticated connections that plug into SQLAlchemy or your own connection pooling. It supports both synchronous and asyncio usage and optionally enables Cloud SQL automatic IAM database authentication, making it the recommended way to connect Python workloads to Cloud SQL.

What You Get

• Secure, IAM-authorized connections to Cloud SQL without managing SSL certificates or firewalls
• Support for MySQL (pymysql), PostgreSQL (pg8000, asyncpg), and SQL Server (pytds) drivers
• Both synchronous and asyncio connection APIs
• Optional automatic IAM database authentication
• TLS 1.3 encryption and identity verification independent of the database protocol

Common Use Cases

• Connecting a Python web app or service to Cloud SQL over IAM instead of an IP allow-list
• Integrating Cloud SQL with SQLAlchemy via a connection-creator function
• Running async database access with asyncpg against Cloud SQL PostgreSQL
• Deploying serverless workloads (Cloud Run, Cloud Functions) that reach Cloud SQL securely

Under The Hood

Architecture - The package lives under google/cloud/sql/connector. The central Connector class (connector.py) orchestrates connection setup, delegating to client.py for the Cloud SQL Admin API calls that fetch instance metadata and ephemeral certificates, instance.py and connection_info.py for per-instance state and credential caching, and connection_name.py plus resolver.py for parsing and resolving instance identifiers. Driver-specific modules (pymysql.py, pg8000.py, asyncpg.py, pytds.py) adapt the authenticated socket to each database library, while refresh_utils.py, lazy.py, and monitored_cache.py handle background refresh of soon-to-expire credentials and rate_limiter.py throttles refresh calls.

Tech Stack - Pure Python (>=3.9) built on aiohttp for async HTTP to the Cloud SQL Admin API, cryptography for TLS material, google-auth for credentials, dnspython for resolution, and requests. Packaging is via setuptools with a py.typed marker for full type-hint support. Optional extras pull in the appropriate database driver.

Code Quality - The codebase is type-annotated and ships a py.typed marker, with a tests tree split into unit and system suites plus conftest fixtures, exercised in CI via nox (noxfile.py). It carries a SECURITY.md and CONTRIBUTING guide and is marked Production/Stable, reflecting Google ongoing maintenance.

API Design - Usage is deliberately small: instantiate Connector, call connect(instance_connection_name, driver, …) to get a live DB connection, and typically wire it into SQLAlchemy as a creator function. Both sync and async entry points exist, and the samples directory (Cloud Run, notebooks) plus a Colab notebook make the getting-started path clear. The main concepts to learn are instance connection names and IAM roles rather than the library own surface.