From 55f0c9ebd854900419a1b6ca0fbe171b6a521b08 Mon Sep 17 00:00:00 2001 From: Tatiane Tosta Date: Thu, 9 Nov 2023 02:34:30 +0000 Subject: [PATCH 1/2] docs: move driver-specific info to separate file --- .github/release-please.yml | 2 +- README.md | 209 +------------------------------------ docs/jdbc.md | 208 ++++++++++++++++++++++++++++++++++++ 3 files changed, 213 insertions(+), 206 deletions(-) create mode 100644 docs/jdbc.md diff --git a/.github/release-please.yml b/.github/release-please.yml index d5fb9ebd..7bcbe62a 100644 --- a/.github/release-please.yml +++ b/.github/release-please.yml @@ -3,4 +3,4 @@ handleGHRelease: true releaseType: java-yoshi extraFiles: - alloydb-jdbc-connector/src/main/java/com/google/cloud/alloydb/Version.java - - README.md + - docs/jdbc.md diff --git a/README.md b/README.md index 4f328a5d..e5e263e0 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,10 @@ This library provides a [socket factory][socket-factory] for use with the 1. Configure a connection pool that configures the driver to use the Connector as a socket factory +For usage information specific to your database engine and driver, see the pages below: + +* [Connecting to AlloyDB using JDBC](docs/jdbc.md) + [socket-factory]: https://docs.oracle.com/javase/8/docs/api/javax/net/SocketFactory.html [postgres-driver]: https://jdbc.postgresql.org/ @@ -51,211 +55,6 @@ for more information. [set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc [iam-docs]: https://cloud.google.com/alloydb/docs/reference/iam-roles-permissions#roles -### Adding the Connector as a Dependency - -You'll need to add the Connector and the appropriate [Postgres Driver][pg-driver] in your -list of dependencies. - -[pg-driver]: https://mvnrepository.com/artifact/org.postgresql/postgresql - -#### Maven - -Include the following in the project's `pom.xml`: - - -```maven-pom - - - com.google.cloud - alloydb-jdbc-connector - 0.1.3-SNAPSHOT - -``` - - -```maven-pom - - - org.postgresql - postgresql - 42.6.0 - -``` - -#### Gradle - -Include the following the project's `gradle.build` - - -```gradle -// Add connector with the latest version -implementation group: 'com.google.cloud.alloydb', name: 'alloydb-jdbc-connector', version: '0.1.3-SNAPSHOT' -``` - - -```gradle -// Add driver with the latest version -implementation group: 'org.postgresql', name: 'postgresql', version: '42.6.0' -``` - -### Configuring a Connection Pool - -We recommend using [HikariCP][] for connection pooling. To use HikariCP with -the Java Connector, you will need to set the usual properties (e.g., JDBC URL, -username, password, etc) and you will need to set two Connector specific -properties: - -[HikariCP]: https://github.com/brettwooldridge/HikariCP - -- `socketFactory` should be set to `com.google.cloud.alloydb.SocketFactory` -- `alloydbInstanceName` should be set to the AlloyDB instance you want to - connect to, e.g.: -``` -projects//locations//clusters//instances/ -``` - -Basic configuration of a data source looks like this: - -``` java -import com.zaxxer.hikari.HikariConfig; -import com.zaxxer.hikari.HikariDataSource; - -public class ExampleApplication { - - private HikariDataSource dataSource; - - HikariDataSource getDataSource() { - HikariConfig config = new HikariConfig(); - - // There is no need to set a host on the JDBC URL - // since the Connector will resolve the correct IP address. - config.setJdbcUrl("jdbc:postgresql:///postgres"); - config.setUsername(System.getenv("ALLOYDB_USER")); - config.setPassword(System.getenv("ALLOYDB_PASS")); - - // Tell the driver to use the AlloyDB Java Connector's SocketFactory - // when connecting to an instance/ - config.addDataSourceProperty("socketFactory", - "com.google.cloud.alloydb.SocketFactory"); - // Tell the Java Connector which instance to connect to. - config.addDataSourceProperty("alloydbInstanceName", - System.getenv("ALLOYDB_INSTANCE_NAME")); - - this.dataSource = new HikariDataSource(config); - } - - // Use DataSource as usual ... - -} -``` - -See our [end to end test][e2e] for a full example. - -See [About Pool Sizing][pool-sizing] for useful guidance on getting the best -performance from a connection pool. - -[e2e]: https://github.com/GoogleCloudPlatform/alloydb-java-connector/blob/main/alloydb-jdbc-connector/src/test/java/com/google/cloud/alloydb/ITSocketFactoryTest.java -[pool-sizing]: https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing - -### Service Account Impersonation - -The Java Connector supports service account impersonation with the -`alloydbTargetPrincipal` JDBC connection property. When enabled, -all API requests are made impersonating the supplied service account. -The IAM principal must have the IAM role "Service Account Token Creator" -(i.e., `roles/iam.serviceAccounts.serviceAccountTokenCreator`) on the -service account provided in the `alloydbTargetPrincipal` property. - -#### Example - -``` java -import com.zaxxer.hikari.HikariConfig; -import com.zaxxer.hikari.HikariDataSource; - -public class ExampleApplication { - - private HikariDataSource dataSource; - - HikariDataSource getDataSource() { - HikariConfig config = new HikariConfig(); - - // There is no need to set a host on the JDBC URL - // since the Connector will resolve the correct IP address. - config.setJdbcUrl("jdbc:postgresql:///postgres"); - config.setUsername(System.getenv("ALLOYDB_USER")); - config.setPassword(System.getenv("ALLOYDB_PASS")); - - // Tell the driver to use the AlloyDB Java Connector's SocketFactory - // when connecting to an instance/ - config.addDataSourceProperty("socketFactory", - "com.google.cloud.alloydb.SocketFactory"); - // Tell the Java Connector which instance to connect to. - config.addDataSourceProperty("alloydbInstanceName", - System.getenv("ALLOYDB_INSTANCE_NAME")); - config.addDataSourceProperty("alloydbTargetPrincipal", - System.getenv("ALLOYDB_IMPERSONATED_USER")); - - this.dataSource = new HikariDataSource(config); - } - - // Use DataSource as usual ... - -} -``` - -#### Delegated Service Account Impersonation - -In addition, the `alloydbDelegates` property controls impersonation delegation. -The value is a comma-separated list of service accounts containing chained -list of delegates required to grant the final access_token. If set, -the sequence of identities must have "Service Account Token Creator" capability -granted to the preceding identity. For example, if set to -`"serviceAccountB,serviceAccountC"`, the IAM principal must have the -Token Creator role on serviceAccountB. Then serviceAccountB must have the -Token Creator role on serviceAccountC. Finally, serviceAccountC must have the -Token Creator role on `alloydbTargetPrincipal`. If unset, the IAM principal -must have the Token Creator role on `alloydbTargetPrincipal`. - -```java -config.addDataSourceProperty("alloydbTargetPrincipal", - "TARGET_SERVICE_ACCOUNT"); -config.addDataSourceProperty("alloydbDelegates", - "SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2"); -``` - -In this example, the IAM principal impersonates SERVICE_ACCOUNT_1 which -impersonates SERVICE_ACCOUNT_2 which then impersonates the -TARGET_SERVICE_ACCOUNT. - -### Admin API Service Endpoint - -The Java Connector supports setting the Admin API Service Endpoint with the -`alloydbAdminServiceEndpoint` JDBC connection property. This feature is -used by applications that need to connect to a Google Cloud API other -than the GCP public API. - -The `alloydbAdminServiceEndpoint` property specifies a network address that -the AlloyDB Admin API service uses to service the actual API requests, -for example `"googleapis.example.com:443"`. - -If this option is not set, the connector will use the default service address -as follows: - -``` -DEFAULT_ENDPOINT = "alloydb.googleapis.com:443" -``` - -For more information, see the [underlying client library documentation][client-docs]. - -[client-docs]: https://cloud.google.com/java/docs/reference/google-cloud-alloydb/latest/com.google.cloud.alloydb.v1beta#alloydbadminclient_1 - -### Example - -```java -config.addDataSourceProperty("alloydbAdminServiceEndpoint", - "NEW_API_SERVICE_ENDPOINT"); -``` - ## Support policy ### Major version lifecycle diff --git a/docs/jdbc.md b/docs/jdbc.md new file mode 100644 index 00000000..8f134185 --- /dev/null +++ b/docs/jdbc.md @@ -0,0 +1,208 @@ +# Connecting to AlloyDB using JDBC + +## Setup and Usage + +### Adding the Connector as a Dependency + +You'll need to add the Connector and the appropriate [Postgres Driver][pg-driver] in your +list of dependencies. + +[pg-driver]: https://mvnrepository.com/artifact/org.postgresql/postgresql + +#### Maven + +Include the following in the project's `pom.xml`: + + +```maven-pom + + + com.google.cloud + alloydb-jdbc-connector + 0.1.2 + +``` + + +```maven-pom + + + org.postgresql + postgresql + 42.6.0 + +``` + +#### Gradle + +Include the following the project's `gradle.build` + + +```gradle +// Add connector with the latest version +implementation group: 'com.google.cloud.alloydb', name: 'alloydb-jdbc-connector', version: '0.1.2' +``` + + +```gradle +// Add driver with the latest version +implementation group: 'org.postgresql', name: 'postgresql', version: '42.6.0' +``` + +### Configuring a Connection Pool + +We recommend using [HikariCP][] for connection pooling. To use HikariCP with +the Java Connector, you will need to set the usual properties (e.g., JDBC URL, +username, password, etc) and you will need to set two Connector specific +properties: + +[HikariCP]: https://github.com/brettwooldridge/HikariCP + +- `socketFactory` should be set to `com.google.cloud.alloydb.SocketFactory` +- `alloydbInstanceName` should be set to the AlloyDB instance you want to + connect to, e.g.: +``` +projects//locations//clusters//instances/ +``` + +Basic configuration of a data source looks like this: + +``` java +import com.zaxxer.hikari.HikariConfig; +import com.zaxxer.hikari.HikariDataSource; + +public class ExampleApplication { + + private HikariDataSource dataSource; + + HikariDataSource getDataSource() { + HikariConfig config = new HikariConfig(); + + // There is no need to set a host on the JDBC URL + // since the Connector will resolve the correct IP address. + config.setJdbcUrl("jdbc:postgresql:///postgres"); + config.setUsername(System.getenv("ALLOYDB_USER")); + config.setPassword(System.getenv("ALLOYDB_PASS")); + + // Tell the driver to use the AlloyDB Java Connector's SocketFactory + // when connecting to an instance/ + config.addDataSourceProperty("socketFactory", + "com.google.cloud.alloydb.SocketFactory"); + // Tell the Java Connector which instance to connect to. + config.addDataSourceProperty("alloydbInstanceName", + System.getenv("ALLOYDB_INSTANCE_NAME")); + + this.dataSource = new HikariDataSource(config); + } + + // Use DataSource as usual ... + +} +``` + +See our [end to end test][e2e] for a full example. + +See [About Pool Sizing][pool-sizing] for useful guidance on getting the best +performance from a connection pool. + +[e2e]: https://github.com/GoogleCloudPlatform/alloydb-java-connector/blob/main/alloydb-jdbc-connector/src/test/java/com/google/cloud/alloydb/ITSocketFactoryTest.java +[pool-sizing]: https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing + +### Service Account Impersonation + +The Java Connector supports service account impersonation with the +`alloydbTargetPrincipal` JDBC connection property. When enabled, +all API requests are made impersonating the supplied service account. +The IAM principal must have the IAM role "Service Account Token Creator" +(i.e., `roles/iam.serviceAccounts.serviceAccountTokenCreator`) on the +service account provided in the `alloydbTargetPrincipal` property. + +#### Example + +``` java +import com.zaxxer.hikari.HikariConfig; +import com.zaxxer.hikari.HikariDataSource; + +public class ExampleApplication { + + private HikariDataSource dataSource; + + HikariDataSource getDataSource() { + HikariConfig config = new HikariConfig(); + + // There is no need to set a host on the JDBC URL + // since the Connector will resolve the correct IP address. + config.setJdbcUrl("jdbc:postgresql:///postgres"); + config.setUsername(System.getenv("ALLOYDB_USER")); + config.setPassword(System.getenv("ALLOYDB_PASS")); + + // Tell the driver to use the AlloyDB Java Connector's SocketFactory + // when connecting to an instance/ + config.addDataSourceProperty("socketFactory", + "com.google.cloud.alloydb.SocketFactory"); + // Tell the Java Connector which instance to connect to. + config.addDataSourceProperty("alloydbInstanceName", + System.getenv("ALLOYDB_INSTANCE_NAME")); + config.addDataSourceProperty("alloydbTargetPrincipal", + System.getenv("ALLOYDB_IMPERSONATED_USER")); + + this.dataSource = new HikariDataSource(config); + } + + // Use DataSource as usual ... + +} +``` + +#### Delegated Service Account Impersonation + +In addition, the `alloydbDelegates` property controls impersonation delegation. +The value is a comma-separated list of service accounts containing chained +list of delegates required to grant the final access_token. If set, +the sequence of identities must have "Service Account Token Creator" capability +granted to the preceding identity. For example, if set to +`"serviceAccountB,serviceAccountC"`, the IAM principal must have the +Token Creator role on serviceAccountB. Then serviceAccountB must have the +Token Creator role on serviceAccountC. Finally, serviceAccountC must have the +Token Creator role on `alloydbTargetPrincipal`. If unset, the IAM principal +must have the Token Creator role on `alloydbTargetPrincipal`. + +```java +config.addDataSourceProperty("alloydbTargetPrincipal", + "TARGET_SERVICE_ACCOUNT"); +config.addDataSourceProperty("alloydbDelegates", + "SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2"); +``` + +In this example, the IAM principal impersonates SERVICE_ACCOUNT_1 which +impersonates SERVICE_ACCOUNT_2 which then impersonates the +TARGET_SERVICE_ACCOUNT. + +### Admin API Service Endpoint + +The Java Connector supports setting the Admin API Service Endpoint with the +`alloydbAdminServiceEndpoint` JDBC connection property. This feature is +used by applications that need to connect to a Google Cloud API other +than the GCP public API. + +The `alloydbAdminServiceEndpoint` property specifies a network address that +the AlloyDB Admin API service uses to service the actual API requests, +for example `"googleapis.example.com:443"`. + +If this option is not set, the connector will use the default service address +as follows: + +``` +DEFAULT_ENDPOINT = "alloydb.googleapis.com:443" +``` + +For more information, see the [underlying client library documentation][client-docs]. + +[client-docs]: https://cloud.google.com/java/docs/reference/google-cloud-alloydb/latest/com.google.cloud.alloydb.v1beta#alloydbadminclient_1 + +### Example + +```java +config.addDataSourceProperty("alloydbAdminServiceEndpoint", + "NEW_API_SERVICE_ENDPOINT"); +``` From a1ab3287006784ab007e016c074fa819f94243a1 Mon Sep 17 00:00:00 2001 From: Tatiane Tosta Date: Thu, 9 Nov 2023 17:04:47 +0000 Subject: [PATCH 2/2] chore: update README as suggested --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e5e263e0..2e0afbe6 100644 --- a/README.md +++ b/README.md @@ -34,12 +34,11 @@ This library provides a [socket factory][socket-factory] for use with the 1. Configure a connection pool that configures the driver to use the Connector as a socket factory -For usage information specific to your database engine and driver, see the pages below: - -* [Connecting to AlloyDB using JDBC](docs/jdbc.md) +For information on configuring a connection, see the [documentation][jdbc-doc]. [socket-factory]: https://docs.oracle.com/javase/8/docs/api/javax/net/SocketFactory.html [postgres-driver]: https://jdbc.postgresql.org/ +[jdbc-doc]: docs/jdbc.md ### Configuring IAM permissions