Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: move driver-specific info to separate file #290

Merged
merged 2 commits into from
Nov 9, 2023
Merged

docs: move driver-specific info to separate file #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
55f0c9e
docs: move driver-specific info to separate file
ttosta-google Nov 9, 2023
a1ab328
chore: update README as suggested
ttosta-google Nov 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/release-please.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
208 changes: 3 additions & 205 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +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 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

Expand All @@ -51,211 +54,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`:

<!-- {x-version-update-start:alloydb-jdbc-connector:released} -->
```maven-pom
<!-- Add the connector with the latest version -->
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>alloydb-jdbc-connector</artifactId>
<version>0.1.3-SNAPSHOT</version>
</dependency>
```
<!-- {x-version-update-end} -->

```maven-pom
<!-- Add the driver with the latest version -->
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>42.6.0</version>
</dependency>
```

#### Gradle

Include the following the project's `gradle.build`

<!-- {x-version-update-start:alloydb-jdbc-connector:released} -->
```gradle
// Add connector with the latest version
implementation group: 'com.google.cloud.alloydb', name: 'alloydb-jdbc-connector', version: '0.1.3-SNAPSHOT'
```
<!-- {x-version-update-end} -->

```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/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>
```

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
Expand Down
Loading
Loading