CloudSQL for the busy Java Developer

CloudSQL, Google’s fully-managed and highly-available MySQL-based relational database service, can be accessed directly by Java IDE’s or used as a target for on-premise running Java application servers, and of course it can be seamlessly used from AppEngine Java applications. Here’s how.


This paper assumes you have a CloudSQL database instance configured and (ideally) populated. You should have authorized your local machine using OAuth and the command-line tool and have the CloudSQL JDBC driver handy (it’s in the AppEngine SDK in lib/impl). If you need help on any of this, consider reading this Getting Started paper.

Here are the values used here :

  1. Cloud SQL instance name : scott-tiger:scott
  2. Database Name : jpetstore
  3. JDBC Driver Class Name :
  4. JDBC URL : jdbc:google:rdbms://scott-tiger:scott/jpetstore

By default the CloudSQL instance can be accessed with user root and an empty password.

This paper uses NetBeans (7.x) as the IDE and GlassFish (ships with NetBeans) as the local Java Application Server but everything should be easily adaptable for other tools such as Eclipse and other runtimes (tomcat, JBoss, etc).

NetBeans & CloudSQL

The NetBeans IDE offers a JDBC database explorer feature which you can use to access your CloudSQL database instance. In the NetBeans Services tab, chose Databases > Drivers and create a new driver configuration by pointing to the google_sql.jar archive and using as the JDBC driver name (should be auto-detected). Right-click this newly created JDBC driver and select “Connect With…” to create a new connection. Provide the username, the password and the full JDBC URL (jdbc:google:rdbms://scott-tiger:scott/jpetstore in my case) and test the connection.

You should now be able to navigate the database schema, view table content, manipulate data, and execute any SQL statement.

WebApp Project

We’ll now create a web application using JPA entities manipulating data from the Cloud SQL instance discussed above. We’ll deploy this application first to GlassFish, then to App Engine.

Within NetBeans, create a (Maven) Web Application project with GlassFish as the default target. Right-click on the project to select the “New Entity Classes from Database” wizard. Create a new data source using the JDBC connection defined in the previous step. Select the tables you want to create JPA entities for and do not check the “Create Persistence Unit” option (we’ll get back to this later). This generates standard JPA 2.0 @Entity-annotated classes for every table selected from CloudSQL.

Here’s a proper persistence.xml that will work with CloudSQL. Notice how this JPA persistence unit uses RESOURCE_LOCAL and not a JTA data source :

<persistence version="2.0">
  <persistence-unit name="CloudSQLPU" transaction-type="RESOURCE_LOCAL">
      <property name="javax.persistence.jdbc.url" value="jdbc:google:rdbms://scott-tiger:scott/jpetstore"/>
      <property name="javax.persistence.jdbc.user" value="user"/>
      <property name="javax.persistence.jdbc.password" value="pw"/>
      <property name="javax.persistence.jdbc.driver" value=""/>

Once this is setup, you can get a hold of this persistence unit in the servlet created by default the typical way you would in an servlet :

EntityManagerFactory emf = 
EntityManager em = emf.createEntityManager();

A simple use to exercise the data could be to list all the names stored in the Category table (using its JPA entity representation) :

CriteriaQuery cq = em.getCriteriaBuilder().createQuery();;
List<Category> categories = em.createQuery(cq).getResultList();

for (Category category : categories) {
    out.println(category.getName() + "<br/>");

Deploying this simple application to the GlassFish application server shouldn’t require any other changes. Obviously with this architecture, the performance is not ideal given the server is not exactly close to the data. Nevertheless, this demonstrates the standalone capabilities of CloudSQL

Ship it all to the cloud!

A better approach is to probably to use CloudSQL from a Google AppEngine-hosted application where all sorts of optimisations will quick in. To do so, only limited changes to the standard application described above are required.

The first simple change is to add the AppEngine-specific deployment descriptor appengine-web.xml :

<?xml version="1.0" encoding="UTF-8"?>
<appengine-web-app xmlns=""

You’ll also need to change the name of the JDBC driver in persistence.xml (a more elegant solution could be to use Maven profiles to keep the project fully portable) :

- <property name="javax.persistence.jdbc.driver"
-          value=""/>
+ <property name="javax.persistence.jdbc.driver"
+         value=""/>;

The JDBC URL remains the same.

Finally, you’ll need to bundle JPA / EclipseLink and BeanValidation / Hibernate Validator by making them runtime-scope dependencies. The Servlet and AppEngine SDK API artifacts should use the default scoping. Your mileage may vary when it comes to the implementation versions. Here is my complete set of Maven dependencies :


Make sure the AppEngine application is authorized to access the CloudSQL instance (use the API Console for that). Once this is all done, simply deploy the application to AppEngine :

$ update target/MyCloudSQLApp-1.0.0-SNAPSHOT

You’ll find the CloudSQL developer documentation here.

JPA/EclipseLink multitenancy screencast

I find JPA and in particular EclipseLink 2.3 to be particularly well suited to illustrate the concept of multitenancy, one of the key PaaS features en route for Java EE 7.

Here’s a short (5-minute) screencast showing GlassFish 3.1.1 (due out real soon now) and its EclipseLink 2.3 JPA provider showing multitenancy in action. In short, it adds EclipseLink annotations to a JPA entity and deploys two identical applications with different tenant-id properties defined in the persistence.xml descriptor. Each application only sees its own data, yet everything is stored in the same table which was augmented with a discriminator column.

For more advanced (or more realistic) uses such as tenant property being set on the @PersistenceContext, XML configuration of multitenant JPA entities, and more check out the nicely written wiki page.