Skip to content

Commit 712023b

Browse files
chore: add usage example in README
1 parent 2c8bace commit 712023b

File tree

1 file changed

+63
-0
lines changed

1 file changed

+63
-0
lines changed

README.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -365,6 +365,69 @@ conn = connector.connect(
365365
)
366366
```
367367

368+
### Using DNS domain names to identify instances
369+
370+
The connector can be configured to use DNS to look up an instance. This would
371+
allow you to configure your application to connect to a database instance, and
372+
centrally configure which instance in your DNS zone.
373+
374+
#### Configure your DNS Records
375+
376+
Add a DNS TXT record for the Cloud SQL instance to a **private** DNS server
377+
or a private Google Cloud DNS Zone used by your application.
378+
379+
> [!NOTE]
380+
>
381+
> You are strongly discouraged from adding DNS records for your
382+
> Cloud SQL instances to a public DNS server. This would allow anyone on the
383+
> internet to discover the Cloud SQL instance name.
384+
385+
For example: suppose you wanted to use the domain name
386+
`prod-db.mycompany.example.com` to connect to your database instance
387+
`my-project:region:my-instance`. You would create the following DNS record:
388+
389+
* Record type: `TXT`
390+
* Name: `prod-db.mycompany.example.com` – This is the domain name used by the application
391+
* Value: `my-project:my-region:my-instance` – This is the Cloud SQL instance connection name
392+
393+
#### Configure the connector
394+
395+
Configure the connector to resolve DNS names by initializing it with
396+
`resolver=DnsResolver` and replacing the instance connection name with the DNS
397+
name in `connector.connect`:
398+
399+
```python
400+
from google.cloud.sql.connector import Connector, DnsResolver
401+
import pymysql
402+
import sqlalchemy
403+
404+
# helper function to return SQLAlchemy connection pool
405+
def init_connection_pool(connector: Connector) -> sqlalchemy.engine.Engine:
406+
# function used to generate database connection
407+
def getconn() -> pymysql.connections.Connection:
408+
conn = connector.connect(
409+
"prod-db.mycompany.example.com", # using DNS name
410+
"pymysql",
411+
user="my-user",
412+
password="my-password",
413+
db="my-db-name"
414+
)
415+
return conn
416+
417+
# create connection pool
418+
pool = sqlalchemy.create_engine(
419+
"mysql+pymysql://",
420+
creator=getconn,
421+
)
422+
return pool
423+
424+
# initialize Cloud SQL Python Connector with `resolver=DnsResolver`
425+
with Connector(resolver=DnsResolver) as connector:
426+
# initialize connection pool
427+
pool = init_connection_pool(connector)
428+
# ... use SQLAlchemy engine normally
429+
```
430+
368431
### Using the Python Connector with Python Web Frameworks
369432

370433
The Python Connector can be used alongside popular Python web frameworks such

0 commit comments

Comments
 (0)