Set up your environment

This page walks you through the setup steps required to use the Cloud Spanner APIwith theGoogle Cloud CLI,clientlibraries, andSpannerdrivers.

If you want to use Spanner with the Google Cloud console, seeQuickstart using the console.

Required roles

To get the permissions that you need to use and interact with Spanner databases, ask your administrator to grant you the following IAM roles:

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Set up a Google Cloud project

  1. Go to theProjects page in the Google Cloud console.

    Go to the Projects page

  2. Create a new Google Cloud project, or open an existing project by clicking on the project name.
    3. Important: The name you use must be between 4 and 30 characters. When you type the name, the form will suggest a project ID, which you can edit. The project ID you use must be between 6 and 30 characters, with a lowercase letter as the first character. You can use a dash, lowercase letter, or digit for the remaining characters, but the last character cannot be a dash. You should be aware that some resource identifiers (such as project IDs) might be retained beyond the life of your project. For this reason, avoid storing sensitive information in resource identifiers....see naming guidelines

  3. Open a terminal window, and set your project as the default project for the Google Cloud CLI, replacingMY_PROJECT_ID with your project ID (not your project name):

    gcloudconfigsetprojectMY_PROJECT_ID

  4. Verify that billing is enabled for your Google Cloud project.

    5. You can alsolearn about Spanner pricing.

  5. Enable the Cloud Spanner API for the project.

    Enable the Cloud Spanner API

    Note: If you use a service account in a different project to access your Spanner instance, you need to enable the Spanner API in both projects.

Set up authentication

Select the tabs for how you plan to access the API:

Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

gcloud

Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

gcloudinit

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To set up the gcloud CLI to use service account impersonation to authenticate to Google APIs, rather than your user credentials, run the following command:

gcloudconfigsetauth/impersonate_service_accountSERVICE_ACCT_EMAIL

For more information, seeService account impersonation.

Terraform

To use Terraform code in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

    Install the Google Cloud CLI.

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    If you're using a local shell, then create local authentication credentials for your user account:

    gcloudauthapplication-defaultlogin

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

For more information, see Set up authentication for a local development environment.

Client libraries

To use client libraries in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

    Install the Google Cloud CLI.

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    If you're using a local shell, then create local authentication credentials for your user account:

    gcloudauthapplication-defaultlogin

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

For more information, see Set up authentication for a local development environment.

To set up your local ADC file to use service account impersonation to authenticate to Google APIs, rather than your user credentials, run the following command:

gcloudauthapplication-defaultlogin--impersonate-service-account=SERVICE_ACCT_EMAIL

For more information, seeService account impersonation.

REST

To use the REST API in a local development environment, you use the credentials you provide to the gcloud CLI.

    Install the Google Cloud CLI.

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

You can use service account impersonation to generate an access token for REST API requests. For more information, seeImpersonated service account.

Run the Google Cloud CLI

Now that you've set up your development environment and authentication, run thegcloud command-line tool to interact withSpanner:

gcloudspannerinstance-configslist

You should see a list of the Spanner instance configurations thatyour project can access, including regional, dual-region, and multi-regionconfigurations. For more information, see theInstancesoverview.

You've completed the setup!

What's next

Learn how to use the Cloud Client Libraries and drivers to create aSpanner instance, database, tables, and indexes. Then store,query, and read data in Spanner.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.