cloud-sql-python-connector 1.16.0__tar.gz → 1.18.2__tar.gz

{cloud_sql_python_connector-1.16.0 → cloud_sql_python_connector-1.18.2}/PKG-INFO

@@ -1,21 +1,23 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: cloud-sql-python-connector
-Version: 1.16.0
-Summary: The Cloud SQL Python Connector is a library that can be used alongside a database driver to allow users with sufficient permissions to connect to a Cloud SQL database without having to manually allowlist IPs or manage SSL certificates.
-Home-page: https://github.com/GoogleCloudPlatform/cloud-sql-python-connector
-Author: Google LLC
-Author-email: googleapis-packages@google.com
-License: Apache 2.0
-Platform: Posix; MacOS X; Windows
+Version: 1.18.2
+Summary: Google Cloud SQL Python Connector library
+Author-email: Google LLC <googleapis-packages@google.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/GoogleCloudPlatform/cloud-sql-python-connector
+Project-URL: Repository, https://github.com/GoogleCloudPlatform/cloud-sql-python-connector.git
+Project-URL: Issues, https://github.com/GoogleCloudPlatform/cloud-sql-python-connector/issues
+Project-URL: Changelog, https://github.com/GoogleCloudPlatform/cloud-sql-python-connector/blob/main/CHANGELOG.md
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -33,6 +35,7 @@ Provides-Extra: pytds
 Requires-Dist: python-tds>=1.15.0; extra == "pytds"
 Provides-Extra: asyncpg
 Requires-Dist: asyncpg>=0.30.0; extra == "asyncpg"
+Dynamic: license-file
 
 <p align="center">
     <a href="https://cloud.google.com/blog/topics/developers-practitioners/how-connect-cloud-sql-using-python-easy-way">
@@ -162,21 +165,16 @@ import sqlalchemy
 # initialize Connector object
 connector = Connector()
 
-# function to return the database connection
-def getconn() -> pymysql.connections.Connection:
-    conn: pymysql.connections.Connection = connector.connect(
+# initialize SQLAlchemy connection pool with Connector
+pool = sqlalchemy.create_engine(
+    "mysql+pymysql://",
+    creator=lambda: connector.connect(
         "project:region:instance",
         "pymysql",
         user="my-user",
         password="my-password",
         db="my-db-name"
-    )
-    return conn
-
-# create connection pool
-pool = sqlalchemy.create_engine(
-    "mysql+pymysql://",
-    creator=getconn,
+    ),
 )
 ```
 
@@ -243,33 +241,21 @@ Connector as a context manager:
 
 ```python
 from google.cloud.sql.connector import Connector
-import pymysql
 import sqlalchemy
 
-# helper function to return SQLAlchemy connection pool
-def init_connection_pool(connector: Connector) -> sqlalchemy.engine.Engine:
-    # function used to generate database connection
-    def getconn() -> pymysql.connections.Connection:
-        conn = connector.connect(
+# initialize Cloud SQL Python Connector as context manager
+with Connector() as connector:
+    # initialize SQLAlchemy connection pool with Connector
+    pool = sqlalchemy.create_engine(
+        "mysql+pymysql://",
+        creator=lambda: connector.connect(
             "project:region:instance",
             "pymysql",
             user="my-user",
             password="my-password",
             db="my-db-name"
-        )
-        return conn
-
-    # create connection pool
-    pool = sqlalchemy.create_engine(
-        "mysql+pymysql://",
-        creator=getconn,
+        ),
     )
-    return pool
-
-# initialize Cloud SQL Python Connector as context manager
-with Connector() as connector:
-    # initialize connection pool
-    pool = init_connection_pool(connector)
     # insert statement
     insert_stmt = sqlalchemy.text(
         "INSERT INTO my_table (id, title) VALUES (:id, :title)",
@@ -437,33 +423,60 @@ from google.cloud.sql.connector import Connector, DnsResolver
 import pymysql
 import sqlalchemy
 
-# helper function to return SQLAlchemy connection pool
-def init_connection_pool(connector: Connector) -> sqlalchemy.engine.Engine:
-    # function used to generate database connection
-    def getconn() -> pymysql.connections.Connection:
-        conn = connector.connect(
+# initialize Cloud SQL Python Connector with `resolver=DnsResolver`
+with Connector(resolver=DnsResolver) as connector:
+    # initialize SQLAlchemy connection pool with Connector
+    pool = sqlalchemy.create_engine(
+        "mysql+pymysql://",
+        creator=lambda: connector.connect(
             "prod-db.mycompany.example.com",  # using DNS name
             "pymysql",
             user="my-user",
             password="my-password",
             db="my-db-name"
-        )
-        return conn
-
-    # create connection pool
-    pool = sqlalchemy.create_engine(
-        "mysql+pymysql://",
-        creator=getconn,
+        ),
     )
-    return pool
-
-# initialize Cloud SQL Python Connector with `resolver=DnsResolver`
-with Connector(resolver=DnsResolver) as connector:
-    # initialize connection pool
-    pool = init_connection_pool(connector)
     # ... use SQLAlchemy engine normally
 ```
 
+### Automatic failover using DNS domain names
+
+> [!NOTE]
+>
+> Usage of the `asyncpg` driver does not currently support automatic failover.
+
+When the connector is configured using a domain name, the connector will
+periodically check if the DNS record for an instance changes. When the connector
+detects that the domain name refers to a different instance, the connector will
+close all open connections to the old instance. Subsequent connection attempts
+will be directed to the new instance.
+
+For example: suppose application is configured to connect using the
+domain name `prod-db.mycompany.example.com`. Initially the private DNS
+zone has a TXT record with the value `my-project:region:my-instance`. The
+application establishes connections to the `my-project:region:my-instance`
+Cloud SQL instance.
+
+Then, to reconfigure the application to use a different database
+instance, change the value of the `prod-db.mycompany.example.com` DNS record
+from `my-project:region:my-instance` to `my-project:other-region:my-instance-2`
+
+The connector inside the application detects the change to this
+DNS record. Now, when the application connects to its database using the
+domain name `prod-db.mycompany.example.com`, it will connect to the
+`my-project:other-region:my-instance-2` Cloud SQL instance.
+
+The connector will automatically close all existing connections to
+`my-project:region:my-instance`. This will force the connection pools to
+establish new connections. Also, it may cause database queries in progress
+to fail.
+
+The connector will poll for changes to the DNS name every 30 seconds by default.
+You may configure the frequency of the connections using the Connector's
+`failover_period` argument (i.e. `Connector(failover_period=60`). When this is
+set to 0, the connector will disable polling and only check if the DNS record
+changed when it is creating a new connection.
+
 ### Using the Python Connector with Python Web Frameworks
 
 The Python Connector can be used alongside popular Python web frameworks such
@@ -499,9 +512,12 @@ from google.cloud.sql.connector import Connector
 # initialize Python Connector object
 connector = Connector()
 
-# Python Connector database connection function
-def getconn():
-    conn = connector.connect(
+app = Flask(__name__)
+
+# configure Flask-SQLAlchemy to use Python Connector
+app.config['SQLALCHEMY_DATABASE_URI'] = "postgresql+pg8000://"
+app.config['SQLALCHEMY_ENGINE_OPTIONS'] = {
+    "creator": lambda: conn = connector.connect(
         "project:region:instance-name", # Cloud SQL Instance Connection Name
         "pg8000",
         user="my-user",
@@ -509,15 +525,6 @@ def getconn():
         db="my-database",
         ip_type="public"  # "private" for private IP
     )
-    return conn
-
-
-app = Flask(__name__)
-
-# configure Flask-SQLAlchemy to use Python Connector
-app.config['SQLALCHEMY_DATABASE_URI'] = "postgresql+pg8000://"
-app.config['SQLALCHEMY_ENGINE_OPTIONS'] = {
-    "creator": getconn
 }
 
 # initialize the app with the extension
@@ -538,38 +545,27 @@ your web application using [SQLAlchemy ORM](https://docs.sqlalchemy.org/en/14/or
 through the following:
 
 ```python
-from sqlalchemy import create_engine
-from sqlalchemy.engine import Engine
+import sqlalchemy
 from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import sessionmaker
 from google.cloud.sql.connector import Connector
 
-# helper function to return SQLAlchemy connection pool
-def init_connection_pool(connector: Connector) -> Engine:
-    # Python Connector database connection function
-    def getconn():
-        conn = connector.connect(
-            "project:region:instance-name", # Cloud SQL Instance Connection Name
-            "pg8000",
-            user="my-user",
-            password="my-password",
-            db="my-database",
-            ip_type="public"  # "private" for private IP
-        )
-        return conn
-
-    SQLALCHEMY_DATABASE_URL = "postgresql+pg8000://"
-
-    engine = create_engine(
-        SQLALCHEMY_DATABASE_URL , creator=getconn
-    )
-    return engine
 
 # initialize Cloud SQL Python Connector
 connector = Connector()
 
 # create connection pool engine
-engine = init_connection_pool(connector)
+engine = sqlalchemy.create_engine(
+    "postgresql+pg8000://",
+    creator=lambda: connector.connect(
+        "project:region:instance-name", # Cloud SQL Instance Connection Name
+        "pg8000",
+        user="my-user",
+        password="my-password",
+        db="my-database",
+        ip_type="public"  # "private" for private IP
+    ),
+)
 
 # create SQLAlchemy ORM session
 SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
@@ -638,40 +634,29 @@ async def main():
 #### SQLAlchemy Async Engine
 
 ```python
-import asyncpg
-
 import sqlalchemy
 from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 
 from google.cloud.sql.connector import Connector, create_async_connector
 
-async def init_connection_pool(connector: Connector) -> AsyncEngine:
-    # creation function to generate asyncpg connections as 'async_creator' arg
-    async def getconn() -> asyncpg.Connection:
-        conn: asyncpg.Connection = await connector.connect_async(
+
+async def main():
+    # initialize Connector object for connections to Cloud SQL
+    connector = await create_async_connector()
+
+    # The Cloud SQL Python Connector can be used along with SQLAlchemy using the
+    # 'async_creator' argument to 'create_async_engine'
+    pool = create_async_engine(
+        "postgresql+asyncpg://",
+        async_creator=lambda: connector.connect_async(
             "project:region:instance",  # Cloud SQL instance connection name
             "asyncpg",
             user="my-user",
             password="my-password",
             db="my-db-name"
             # ... additional database driver args
-        )
-        return conn
-
-    # The Cloud SQL Python Connector can be used along with SQLAlchemy using the
-    # 'async_creator' argument to 'create_async_engine'
-    pool = create_async_engine(
-        "postgresql+asyncpg://",
-        async_creator=getconn,
+        ),
     )
-    return pool
-
-async def main():
-    # initialize Connector object for connections to Cloud SQL
-    connector = await create_async_connector()
-
-    # initialize connection pool
-    pool = await init_connection_pool(connector)
 
     # example query
     async with pool.connect() as conn:
@@ -742,33 +727,24 @@ from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 
 from google.cloud.sql.connector import Connector
 
-async def init_connection_pool(connector: Connector) -> AsyncEngine:
-    # creation function to generate asyncpg connections as 'async_creator' arg
-    async def getconn() -> asyncpg.Connection:
-        conn: asyncpg.Connection = await connector.connect_async(
-            "project:region:instance",  # Cloud SQL instance connection name
-            "asyncpg",
-            user="my-user",
-            password="my-password",
-            db="my-db-name"
-            # ... additional database driver args
-        )
-        return conn
-
-    # The Cloud SQL Python Connector can be used along with SQLAlchemy using the
-    # 'async_creator' argument to 'create_async_engine'
-    pool = create_async_engine(
-        "postgresql+asyncpg://",
-        async_creator=getconn,
-    )
-    return pool
 
 async def main():
     # initialize Connector object for connections to Cloud SQL
     loop = asyncio.get_running_loop()
     async with Connector(loop=loop) as connector:
-        # initialize connection pool
-        pool = await init_connection_pool(connector)
+        # The Cloud SQL Python Connector can be used along with SQLAlchemy using the
+        # 'async_creator' argument to 'create_async_engine'
+        pool = create_async_engine(
+            "postgresql+asyncpg://",
+            async_creator=lambda: connector.connect_async(
+                "project:region:instance",  # Cloud SQL instance connection name
+                "asyncpg",
+                user="my-user",
+                password="my-password",
+                db="my-db-name"
+                # ... additional database driver args
+            ),
+        )
 
         # example query
         async with pool.connect() as conn: