AlloyDB Java Connector

Product Documentation

NOTE: The Connector is currently in public preview and may contain breaking changes.

The AlloyDB Java Connector is a Java library for connecting securely to your AlloyDB instances. Using a Connector provides the following benefits:

IAM Authorization: The Connector uses IAM to ensure only principals with valid permissions are allowed to connect.
Improved Security: The Connector uses TLS 1.3 encryption and identity verification between the client connector and the server-side proxy, independent of the database protocol.
Convenience: The Connector removes the requirement to use and distribute SSL certificates.

Usage

This library provides a socket factory for use with the JDBC Postgres Driver. At a high level, you will need to:

Configure IAM permissions
Add the Connector and Postgres driver as dependencies
Configure a connection pool that configures the driver to use the Connector as a socket factory

Configuring IAM permissions

The Java Connector uses Application Default Credentials (ADC). For information on how to configure Application Default Credentials, see the documentation.

In addition, the associated IAM principal must have the IAM role "Cloud AlloyDB Client" (i.e., roles/alloydb.client). See the docs on AlloyDB IAM permissions for more information.

Adding the Connector as a Dependency

You'll need to add the Connector and the appropriate Postgres Driver in your list of dependencies.

Maven

Include the following in the project's pom.xml:

<!-- Add the connector with the latest version -->
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>alloydb-jdbc-connector</artifactId>
  <version>0.1.0</version>
</dependency>

<!-- 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

// Add connector with the latest version
implementation group: 'com.google.cloud.alloydb', name: 'alloydb-jdbc-connector', version: '0.1.0'
// 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:

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:

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 for a full example.

See About Pool Sizing for useful guidance on getting the best performance from a connection pool.

Support policy

Major version lifecycle

This project uses semantic versioning, and uses the following lifecycle regarding support for a major version:

Active - Active versions get all new features and security fixes (that would not otherwise introduce a breaking change). New major versions are guaranteed to be "active" for a minimum of 1 year.

Deprecated - Deprecated versions continue to receive security and critical bug fixes, but do not receive new features. Deprecated versions will be supported for 1 year.

Unsupported - Any major version that has been deprecated for >=1 year is considered unsupported.

Supported JDK versions

We test and support at minimum, any publicly supported LTS JDK version. Changes in supported versions will be considered a minor change, and will be listed in the release notes.

Release cadence

This project aims for a minimum monthly release cadence. If no new features or fixes have been added, a new PATCH version with the latest dependencies is released.

Versioning

This library follows Semantic Versioning.

Contributing

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Code of Conduct for more information.

License

Apache 2.0 - See LICENSE for more information.

Notice

Java is a registered trademark of Oracle and/or its affiliates.

kolea2/alloydb-java-connector