Developers & Practitioners

Cloud Spanner connectivity using JetBrains IDEs


If you are a developer working on an application backed by Google Cloud Spanner and use an IDE from  the JetBrains suite of developer tools, we’ve got some good news for you! You can now browse the database schema and query data stored in Cloud Spanner directly from your JetBrains IDE. In this post, I will show you how to connect to a Cloud Spanner instance using IntelliJ IDEA.


To connect to Cloud Spanner within IntelliJ, you will need:

Adding the Cloud Spanner data source

To add Cloud Spanner as a data source, open the Database tool window by navigating to View -> Tool Windows -> Database within your IntelliJ project. This will open a sidebar in IntelliJ that will show you a list of your current database connections for the project. If you have never added a connection, this sidebar will be empty. Click the ‘+’ icon to bring up the list of data sources you can add. The Cloud Spanner data source can be found under the ‘Other’ section of this list. This is because the data source is published under Basic Support. 

According to IntelliJ documentation, Basic Support provides, "code highlighting and displays objects that were retrieved by the JDBC driver. IntelliJ IDEA uses JDBC metadata for database introspection and the SQL 2016 dialect for code highlighting. No errors are detected and highlighted. The introspection with JDBC metadata means that some specific database objects will not appear in the database tree view. Code completion will not include objects that were not retrieved during introspection."

Add Google Cloud Spanner data source in IntelliJ

From here, the connection information you provide will depend on whether you are connecting to a Cloud Spanner instance or the emulator.

Connecting to a Cloud Spanner instance

To connect to a Cloud Spanner instance you will need the following information:

  • The projectID where the Cloud Spanner instance is located.
  • The instance name
  • The database name
You will also need to setup the gcloud tool to work with Spanner and enable the Spanner API so that your local environment can connect to the Cloud Spanner instance:
  # Ensure the currently set project is the one where the Cloud Spanner instance is
gcloud config list project

# If it is not, set the correct project
gcloud config set project intellij

# Authenticate 
gcloud auth application-default login

Once you have authenticated, you can fill in the connection information in IntelliJ. In the image below, I’m connecting to the intellij project. This contains a Cloud Spanner instance called intellij. And that instance has a database named demo.

Connection to Cloud Spanner Instance

Connecting to the Cloud Spanner Emulator

The emulator is available to make developing applications against Cloud Spanner easier. It is run locally, and exposes connectivity on localhost:9010 by default. Before you can connect to the emulator, you must configure it with a projectID, instance name and database name. You can do that with the gcloud command line tool:

  # Create a new configuration named 'emulator' to avoid overwriting other configurations
gcloud config configurations create emulator

# Set the project to 'intellij'
gcloud config set project intellij

# Start the emulator running in the background
gcloud emulators spanner start &

# Create the instance 'emulator'
gcloud spanner instances create emulator --config=emulator-config --description="Emulator Instance" --nodes=1

# Create the 'test' database
gcloud spanner databases create test --instance emulator

Now, back in the IntelliJ IDE, add a Google Cloud Spanner data source, as previously described. Choose ‘No Auth’ because there is no authentication for the emulator. Like the Cloud Spanner connection previously, the JDBC connection string expects the projectID, an instance name, and a database name that you configured above.

Additionally, you will need to provide the REST API port to the connection string. The default for the emulator is localhost:9010. Also note the additional metadata at the end of the connection string in the image below for ?autoConfigEmulator=true

Connection to Cloud Spanner Emulator

Using the connection in IntelliJ

Whether you created the connection to a Cloud Spanner instance or the emulator, you can now browse the database model and issue queries on the Cloud Spanner backend. For example, you can issue a CREATE TABLE command and INSERT data into that table. Once you have created the table, you can explore the data directly, or issue SQL queries against the data.

Run Spanner Queries in Intellij

Next steps

While the Cloud Spanner driver is intended for use during development and testing, it is not intended for the administration of production database environments. With that in mind, interacting with Cloud Spanner databases from within your IDE can make your development process more efficient by reducing the need to switch between multiple tools and interfaces. 

Go ahead and try it for yourself! Start exploring your Cloud Spanner databases from within JetBrains developer tools.

If you have questions or comments, feel free to reach out to me on Twitter. We would love to hear your feedback.

Copyright © 2000-2021 JetBrains s.r.o. JetBrains and the JetBrains logo are registered trademarks of JetBrains s.r.o.