Cloud SQL Socket Factory for JDBC drivers
The Cloud SQL Socket Factory is a library for the MySQL/Postgres JDBC drivers that allows a user with the appropriate permissions to connect to a Cloud SQL database without having to deal with IP whitelisting or SSL certificates manually.
Instructions
Examples
For examples of this library being used in the context of an application, check out the sample applications located here.
Authentication
This library uses the Application Default Credentials to authenticate the connection to the Cloud SQL server. For more details, see the previously mentioned link.
To activate credentials locally, use the following gcloud command:
gcloud auth application-default loginAdd library as a dependency
MySQL
Note: Use your JDBC driver version to figure out which SocketFactory you should use. If you
are unsure, it is recommended to use the latest version of mysql-connector-java:8.x.
| JDBC Driver Version | Cloud SQL Socket Factory Version |
|---|---|
| mysql-connector-java:8.x | mysql-socket-factory-connector-j-8:1.0.15 |
| mysql-connector-java:6.x | mysql-socket-factory-connector-j-6:1.0.15 |
| mysql-connector-java:5.1.x | mysql-socket-factory:1.0.15 |
Maven
Include the following in the project's pom.xml:
<dependency>
<groupId>com.google.cloud.sql</groupId>
<artifactId>mysql-socket-factory-connector-j-8</artifactId>
<version>1.0.15</version>
</dependency>Gradle
Include the following the project's gradle.build
compile 'com.google.cloud.sql:mysql-socket-factory-connector-j-8:1.0.15'PostgreSQL
Maven
Include the following in the project's pom.xml:
<dependency>
<groupId>com.google.cloud.sql</groupId>
<artifactId>postgres-socket-factory</artifactId>
<version>1.0.15</version>
</dependency>Gradle
Include the following the project's gradle.build
compile 'com.google.cloud.sql:postgres-socket-factory:1.0.15'Creating the JDBC URL
MySQL
Base JDBC URL: jdbc:mysql:///<DATABASE_NAME>
When specifying the JDBC connection URL, add the additional parameters:
| Property | Value |
|---|---|
| socketFactory | com.google.cloud.sql.mysql.SocketFactory |
| cloudSqlInstance | The instance connection name (found on the instance details page) |
| useSSL | False |
| user | MySQL username |
| password | MySQL user's password |
The full JDBC URL should look like this:
jdbc:mysql:///<DATABASE_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&socketFactory=com.google.cloud.sql.mysql.SocketFactory&useSSL=false&user=<MYSQL_USER_NAME>&password=<MYSQL_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 base on the provided cloudSqlInstance arg.
Postgres
Base JDBC URL: jdbc:postgresql:///<DATABASE_NAME>
When specifying the JDBC connection URL, add the additional parameters:
| Property | Value |
|---|---|
| socketFactory | com.google.cloud.sql.postgres.SocketFactory |
| cloudSqlInstance | The instance connection name (found on the instance details page) |
| user | Postgres username |
| password | Postgres user's password |
The full JDBC URL should look like this:
jdbc:postgresql:///<DATABASE_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&socketFactory=com.google.cloud.sql.postgres.SocketFactory&user=<POSTGRESQL_USER_NAME>&password=<POSTGRESQL_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 base on the provided cloudSqlInstance arg.
Building the Drivers
To build a fat JAR containing the JDBC driver with the bundles Socket Factory dependencies you can issue the following Maven command from the location containing the project pom.xml:
mvn -P jar-with-dependencies clean package -DskipTests
This will create a target sub-folder within each of the module directories. Within these target directories you'll find the JDBC driver files.
Example:
mysql-socket-factory-connector-j-8–1.0.15-jar-with-dependencies.jar
postgres-socket-factory-1.0.15-jar-with-dependencies.jar
Additional Information
Specifying IP Types
The ipTypes argument can be used to specify a comma delimited list of preferred IP types for
connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the
SocketFactory to connect with an instance's associated private IP. Default value is
PUBLIC,PRIVATE.
Firewall configuration
The Cloud SQL proxy establishes connections to Cloud SQL instances using port 3307. Applications
that are protected by a firewall may need to be configured to allow outgoing connections on TCP port
3307. A connection blocked by a firewall typically results in an error stating connection failure
(e.g. com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure).
Connect with IntelliJ
In order to connect IntelliJ to your Cloud SQL instance, you will need to add this library as a jar with dependencies in "Additional Files" section on the driver settings page. Prebuilt fat jars can be found on the Releases page for this purpose.
Connection via Unix Sockets
The library will automatically detect when it is running on GAE Standard, and will connect via the provided unix socket for reduced latency.
To force the library to connect to a unix socket (typically created by the Cloud SQL proxy) when
running outside of the GAE-Standard environment, set the environment variable
CLOUD_SQL_FORCE_UNIX_SOCKET to any value.