From 91442354f3cbe026329ffd4baea556dfd28d4465 Mon Sep 17 00:00:00 2001 From: Jonathan Hess Date: Fri, 10 Jan 2025 11:23:50 -0700 Subject: [PATCH] docs: Add docs for connector configuration using DNS Names, Part of #2043. --- docs/jdbc.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/r2dbc.md | 84 ++++++++++++++++++++++++++++++++++++ 2 files changed, 201 insertions(+) diff --git a/docs/jdbc.md b/docs/jdbc.md index dac050be1..fee0cd469 100644 --- a/docs/jdbc.md +++ b/docs/jdbc.md @@ -563,6 +563,123 @@ Properties connProps = new Properties(); connProps.setProperty("cloudSqlRefreshStrategy", "lazy"); ``` + + +### Using DNS domain names to identify instances + +The connector can be configured to use DNS to look up an instance. This would +allow you to configure your application to connect to a database instance, and +centrally configure which instance in your DNS zone. + +#### Configure your DNS Records + +Add a DNS TXT record for the Cloud SQL instance to a **private** DNS server +or a private Google Cloud DNS Zone used by your application. + +**Note:** You are strongly discouraged from adding DNS records for your +Cloud SQL instances to a public DNS server. This would allow anyone on the +internet to discover the Cloud SQL instance name. + +For example: suppose you wanted to use the domain name +`prod-db.mycompany.example.com` to connect to your database instance +`my-project:region:my-instance`. You would create the following DNS record: + +- Record type: `TXT` +- Name: `prod-db.mycompany.example.com` – This is the domain name used by the application +- Value: `my-project:region:my-instance` – This is the instance name + + +### Creating the JDBC URL + +When specifying the JDBC connection URL, add the additional parameters: + +| Property | Value | +|------------------|-------------------------------------------------------------------| +| socketFactory | | +| user | Database username | +| password | Database user's password | + +Replace with the class name specific to your database. + +#### MySQL + +HOST: The domain name configured in your DNS TXT record. + +Base JDBC URL: `jdbc:mysql:///` + +SOCKET_FACTORY_CLASS: `com.google.cloud.sql.mysql.SocketFactory` + +The full JDBC URL should look like this: + +```java +String jdbcUrl = "jdbc:mysql:///?" + + "&socketFactory=com.google.cloud.sql.mysql.SocketFactory" + + "&user=" + + "&password="; +``` + +#### Maria DB + +HOST: The domain name configured in your DNS TXT record. + +Base JDBC URL: `jdbc:mariadb:///` + +SOCKET_FACTORY_CLASS: `com.google.cloud.sql.mariadb.SocketFactory` + +**Note:** You can use `mysql` as the scheme if you set `permitMysqlScheme` on +the URL. +Please refer to the +MariaDB [documentation](https://mariadb.com/kb/en/about-mariadb-connector-j/#jdbcmysql-scheme-compatibility). + +The full JDBC URL should look like this: + +```java +String jdbcUrl = "jdbc:mariadb:///?" + + "&socketFactory=com.google.cloud.sql.mariadb.SocketFactory" + + "&user=" + + "&password="; +``` + +#### Postgres + +Base JDBC URL: `jdbc:postgresql:///` + +SOCKET_FACTORY_CLASS: `com.google.cloud.sql.postgres.SocketFactory` + +When specifying the JDBC connection URL, add the additional parameters: + +The full JDBC URL should look like this: + +```java +String jdbcUrl = "jdbc:postgresql:///?" + + "&socketFactory=com.google.cloud.sql.postgres.SocketFactory" + + "&user=" + + "&password="; +``` + +#### SQL Server + +Base JDBC URL: `jdbc:sqlserver://localhost;databaseName=` + +SOCKET_FACTORY_CLASS: `com.google.cloud.sql.sqlserver.SocketFactory` + +The full JDBC URL should look like this: + +```java +String jdbcUrl = "jdbc:sqlserver://localhost;" + + "databaseName=;" + + "socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;" + + "socketFactoryConstructorArg=;" + + "user=;" + + "password="; +``` + +**Note:** The host portion of the JDBC URL is currently unused, and has no +effect on the connection process. The SocketFactory will get your instances IP +address based on the provided `socketFactoryConstructorArg` arg. + + + ## Configuration Reference - See [Configuration Reference](configuration.md) diff --git a/docs/r2dbc.md b/docs/r2dbc.md index bb102d8c1..e3788acd3 100644 --- a/docs/r2dbc.md +++ b/docs/r2dbc.md @@ -362,6 +362,90 @@ ConnectionFactoryOptions options = ConnectionFactoryOptions.builder() .build; ``` +### Using DNS domain names to identify instances + +The connector can be configured to use DNS to look up an instance. This would +allow you to configure your application to connect to a database instance, and +centrally configure which instance in your DNS zone. + +#### Configure your DNS Records + +Add a DNS TXT record for the Cloud SQL instance to a **private** DNS server +or a private Google Cloud DNS Zone used by your application. + +**Note:** You are strongly discouraged from adding DNS records for your +Cloud SQL instances to a public DNS server. This would allow anyone on the +internet to discover the Cloud SQL instance name. + +For example: suppose you wanted to use the domain name +`prod-db.mycompany.example.com` to connect to your database instance +`my-project:region:my-instance`. You would create the following DNS record: + +- Record type: `TXT` +- Name: `prod-db.mycompany.example.com` – This is the domain name used by the application +- Value: `my-project:region:my-instance` – This is the instance name + +#### Creating the R2DBC URL + +Add the following connection properties: + +| Property | Value | +|---------------|----------------------------------| +| DATABASE_NAME | The name of the database | +| HOST | The domain name for the instance | +| DB_USER | Database username | +| DB_PASS | Database user's password | + +R2DBC URL template: + +#### MySQL + +``` +r2dbc:gcp:mysql://:@/ +``` + +#### MariaDB + +``` +r2dbc:gcp:mariadb://:@/ +``` + +#### Postgres + +``` +r2dbc:gcp:postgres://:@/ +``` + +##### SQL Server + +``` +r2dbc:gcp:mssql://:@/ +``` + +#### Example + +```java +// Set up URL parameters +ConnectionFactoryOptions options = ConnectionFactoryOptions.builder() + .option(DRIVER,"gcp") + .option(PROTOCOL,"mysql") // OR "postgres" or "mssql" or "mariadb" + .option(PASSWORD,"") + .option(USER,"") + .option(DATABASE,"") + .build(); + +ConnectionFactory connectionFactory = ConnectionFactories.get(options); +ConnectionPoolConfiguration configuration = ConnectionPoolConfiguration + .builder(connectionFactory) + .build(); + +ConnectionPool connectionPool = new ConnectionPool(configuration); +``` + + + + ## Configuration Reference - See [Configuration Reference](configuration.md)