home User Guide Getting Started Help Center Documentation Community Training Certification
Looker keyboard_arrow_down
language keyboard_arrow_down
Google Cloud Spanner

Looker has limited support for Google Cloud Spanner. This page lists the known issues of the current Spanner integration and explains how to connect.

The Google Cloud Spanner JDBC driver is not included in the Looker JAR files. Customer-hosted instances must install the Google Cloud Spanner JDBC driver before connecting Looker.


There are several feature limitations when using Google Cloud Spanner with Looker:

Getting the connection credentials

  1. Log in to the Google Console.

  2. Select the appropriate project:

  3. Select IAM & Admin and then Service accounts:

  4. Select Create service account and fill in the dialog box as follows:

    • Service account name: Enter looker-spanner-service or something similar.
    • Role: Select Cloud Spanner then Cloud Spanner Database Reader.
    • Furnish a new private key: Check the box and select JSON under Key type.

  5. Click Create and keep track of the following:

    • The email address associated with the service account
    • The name and location of the JSON credential file that was downloaded

Creating the Looker connection

This section requires command line access to the machine running Looker. If your instance is hosted by Looker, open a support request in Looker’s Help Center by clicking Contact Us and provide your credential file so that we can perform these steps for you.

Preparing the credential file

  1. Copy the credential file to the machine that will be running Looker:

    cp ~/Downloads/spanner-credentials.json ~/looker/

  2. Optional, but recommended: Modify the permissions on the credential file so that only the account running Looker can read it. Use the following commands:

    chown looker:looker ~/looker/spanner-credentials.json.json chmod 600 ~/looker/spanner-credentials.json.json

Preparing the Looker environment

The Google Cloud Spanner JDBC driver must have access to the spanner-credentials.json file to authenticate to a Google Cloud Spanner instance. Depending on the version of the Cloud Spanner JDBC Driver you use, you may need to configure Looker to access this file differently.

Versions of the Cloud Spanner JDBC Driver prior to 1.0.6 may have issues with the PvtKeyPath where, despite this parameter being documented, the driver cannot locate the Spanner credential file. In order to connect with earlier drivers, you must set the GOOGLE_APPLICATION_CREDENTIALS environment variable as the path to the spanner-credentials.json on the Looker host. This sets the environment variable for the entire host, so it has potential to cause issues with other Google Cloud processes described below in the Troubleshooting section. For these reasons we recommend using the latest version of the Cloud Spanner JDBC Driver.

Cloud Spanner JDBC drivers prior to version 1.0.6

In the Looker application base directory, usually called looker, create or edit the lookerstart.cfg file and add a line similar to this:

export GOOGLE_APPLICATION_CREDENTIALS=/home/looker/spanner-credentials.json

where /home/looker/spanner-credentials.json is the absolute path to the Spanner credentials file.

Installing the Cloud Spanner JDBC driver

Follow the steps on the Custom JDBC drivers documentation page using the values below:

driver symbol: spanner

driver entry:

- name: spanner
  dir_name: spanner
  module_path: com.simba.cloudspanner.core.jdbc42.CloudSpanner42Driver

This assumes you are using the JDBC 4.2 driver. If you are using 4.1, the module path will be com.simba.cloudspanner.core.jdbc41.CloudSpanner41Driver

Configuring the Connection Settings page

  1. In the Admin section of Looker, select Connections, and then select New Connection.
  2. Fill out the connection details (see the Connecting Looker to Your Database documentation page for more information):

    • Dialect: Google Cloud Spanner.
    • Name: The name of the connection. This is how it is referred to in the LookML model.
    • Project Name: The Project ID for the Google Project containing the Spanner database.
    • Instance Name: The name of the instance containing the Spanner database.
    • Database: The name of the Spanner database.
    • Schema: Leave this blank.
    • Max Connections: The maximum number of total connections to the Spanner database across all users. The default is 30.
    • Connection Pool Timeout: The number of seconds a query will wait before timing out due to a full connection pool.
    • Additional Params: For JDBC Driver versions 1.0.6 and up, specify PvtKeyPath=path/to/spanner-credentials.json. For prior JDBC Driver versions, leave blank.
  3. Click Test These Settings to verify a connection.

  4. Click Add Connection.


The following is a general error meaning that the credential file can’t be found:

Cannot connect: connection refused: Java::JavaSql::SQLException: [Simba]SpannerJDBCDriver Failed to connect to Spanner: A project ID is required for this service but could not be determined from the builder or the environment. Please set a project ID using the builder.

There is a known issue when running dialect tests from the Connections page, where Subclass must implement kill_query_stmt method is returned. This result can safely be ignored:

If you are using a Cloud Spanner JDBC driver prior to 1.0.6:

Feature support

For Looker to support some features, your database dialect must also support them.

In Looker 21.6, Google Cloud Spanner supports the following Looker features:


Next Steps

After you have connected your database to Looker, configure sign-in options for your users.