Create a Spanner free trial instance and sample application

Note: A Spanner free trial instance supports Standard edition features, and Enterprise edition features, such as KNN vector distance functions, full-text search, and Spanner Graph. For more information, see the Spanner editions overview.

This quickstart shows you how to use a Spanner free trial instance and sample application. For more information, see the Spanner free trial instances overview.

Get started with a free trial instance

A Spanner 90-day free trial instance is available to anyone with a Google Account who has Cloud Billing enabled in their project. You aren't charged unless you choose to upgrade your free trial instance to a paid instance.

You can create a free trial instance using the Google Cloud console or Google Cloud CLI.

Note: You can only create one free trial instance per project lifecycle, and a maximum of five free trial instances per Cloud Billing account.

Create a free trial instance using the Google Cloud console

The following steps explain how to create a free trial instance using the Google Cloud console.

Before you begin

1. In the Google Cloud console, go to the Spanner page.

   Go to Spanner

2. Select or create a Google Cloud project if you haven't done so already.

3. On the Spanner page, click Start a free trial.

   

4. If Cloud Billing is already enabled for your project, proceed to Create free trial instance in the next section.

   If Cloud Billing is not enabled for your project, link an existing Cloud Billing account or create a new Cloud Billing account. Google uses this payment information to verify your identity. We don't charge your Spanner instance unless you explicitly upgrade your Cloud Billing account to a paid account, and you upgrade your Spanner free trial instance to a paid instance.

   a. Click Go to billing.

   

   b. Then, click Link a billing account.

   

   Note: If you're a new Google Cloud customer, you might also be eligible for the Google Cloud 90-day, $300 Free Trial that offers $300 in free Cloud Billing credits to pay for any Google Cloud resources. The Spanner free trial instance is in addition to the $300 Free Trial credits offered by the Google Cloud Free Trial, and you don't need to use any free Cloud Billing credits to create a free trial instance.

   c. Follow the steps to Create billing account, and then link it to your project.

   d. After you enable Cloud Billing for your project, go to the Spanner page.

   Go to Spanner

   e. Click Start a free trial, and proceed to Create free trial instance in the next section.

5. Optional: If you have created a Spanner instance in the project before, you see the following Spanner Instances page.

   Click Start a free trial.

   

Create a free trial instance

On the Create your free trial instance page, follow these steps:

1. In the Name your instance field, enter an instance name such as Trial instance.

2. The instance ID automatically populates based on the instance name, for example, as trial-instance. Change it, if required.

3. In the Choose a configuration section, select a configuration from the drop-down menu.

   Your instance configuration determines the geographic location where your instance is stored and replicated. Note that this configurations list is much smaller than the list available for paid instances. For a list of the regional configurations available to free trial instances, see Available instance configurations. For a full list of all available instance configurations, see Regional, dual-region, and multi-region configurations.

4. Click Create free trial instance.

   After you create your free trial instance, you are prompted to continue learning and exploring Spanner by launching a step-by-step tutorial that teaches you how to create a database using a sample application. For more information, see Get started with a sample application.

Create a free trial instance using the gcloud CLI

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

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

   gcloud auth application-default login

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

7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

10. Make sure that billing is enabled for your Google Cloud project.

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

    gcloud auth application-default login

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

Create a free trial instance

To create a free trial instance, use the gcloud spanner instances create command.

gcloud spanner instances create INSTANCE_ID \
   --instance-type=free-instance --config=INSTANCE_CONFIG \
   --description=INSTANCE_DESCRIPTION

Replace the following:

• INSTANCE_ID: a permanent identifier that is unique within your Google Cloud project. You can't change the instance ID later.

• INSTANCE_CONFIG: a permanent identifier of your instance configuration, which defines the geographic location of the instance. You can create a free trial instance in one of the following regional instance configurations:

  • Americas: regional-us-central1 (Iowa), regional-us-east1 (South Carolina), regional-us-east4 (Northern Virginia), regional-us-east5 (Columbia)
  • Europe: regional-europe-west1 (Belgium), regional-europe-west3 (Frankfurt)
  • Asia: regional-asia-northeast1 (Tokyo), regional-asia-south2 (Delhi), regional-asia-southeast2 (Jakarta)

• INSTANCE_DESCRIPTION: the name to display for the instance in the Google Cloud console. The instance name must be unique within your Google Cloud project.

For example, to create a free trial instance named trial-instance with the display name Trial Instance using the regional instance configuration regional-us-east5:

gcloud spanner instances create trial-instance --config=regional-us-east5 \
    --instance-type=free-instance --description="Trial Instance"

Note: Use the instance ID, not the display name, when referring to an instance in gcloud CLI commands.

Get started with a sample application

Spanner offers an open source sample application to help you get started with the Spanner free trial instance. A sample application consists of a backend gRPC service backed by a Spanner database and a workload generator that drives traffic to the service.

You can access the sample application by using the Google Cloud console or the Google Cloud CLI.

Console

1. Go to the Spanner Instances page in the Google Cloud console.

   Go to the Instances page

2. Click the name of the free trial instance.

3. On the Instance Overview page, click Learn.

4. In the Learn: Tutorial panel, click Create a sample Cloud SQL database or Create a sample PostgreSQL database, depending on which dialect you want to get started with.

5. After you've completed the tutorial, return back to the Learn: Tutorial panel to follow the second tutorial, Query a sample database.

gcloud CLI

1. Complete the steps described in the gcloud CLI set up, which covers creating and setting a default Google Cloud project, enabling the Cloud Spanner API, and setting up OAuth 2.0 to get authentication credentials to use the Cloud Spanner API.

   Ensure that you run gcloud auth application-default login to set up your local development environment with authentication credentials.

2. Run the gcloud spanner samples run command to download the sample application and start the backend gRPC service and workload generator for the given sample application:

   gcloud spanner samples run APPNAME --instance-id INSTANCE_ID
   

3. For more information and a list of other available commands for the sample application, see the gcloud CLI documentation.

Upgrade a free trial instance

The following steps explain how to upgrade your free trial instance.

Use the Google Cloud console

1. In the Google Cloud console, go to the Spanner Instances page.

   Go to the Instances page

2. Click the name of the free trial instance.

3. On the Instance Overview page, click Edit instance or Edit to upgrade.

   

4. In the Update instance name field, enter a more applicable name for your paid instance if applicable.

5. Select your Upgrade option. You can select one of the following:

   • Upgrade now
   • Automatically upgrade to the full version of the Enterprise edition after my trial expires
   • Remind me later

   The Summary section provides a description of compute and storage costs for the upgraded paid instance that you selected.

6. Click Save to upgrade your free trial instance.

Use gcloud CLI

To upgrade your free trial instance to a paid Enterprise edition instance with the same instance configuration, run the following gcloud spanner instances update command:

gcloud spanner instances update INSTANCE_ID --instance-type=provisioned

Delete the instance

Warning: Deleting an instance permanently removes the instance and all its databases. You cannot undo this later. Also, you cannot create another free trial instance after you've deleted your first free trial instance. You can create one free trial instance per project lifecycle.

Console

1. Go to the Spanner Instances page in the Google Cloud console.

   Go to the Instances page

2. Click the name of the instance that you want to delete.

3. On the Instance Overview page, click Delete instance.

4. Follow the instructions to confirm that you want to delete the instance.

5. Click Delete.

gcloud CLI

To delete your free trial instance, use the following gcloud spanner instances delete command:

gcloud spanner instances delete INSTANCE_ID

What's next

• Learn more about Spanner free trial instances.
• Learn more about Spanner instances and databases.
• For details on Spanner pricing after the free trial period, see the Pricing page.