Spanner client libraries

This page shows how to get started with the Cloud Client Libraries for the Cloud Spanner API. Client libraries make it easier to access Google Cloud APIs from a supported language. Although you can use Google Cloud APIs directly by making raw requests to the server, client libraries provide simplifications that significantly reduce the amount of code you need to write.

Read more about the Cloud Client Libraries and the older Google API Client Libraries in Client libraries explained .

Spanner provides client libraries for popular programming languages, including C++, C#, Go, Java, Node.js, PHP, Python, and Ruby. The client libraries connect to the Spanner service using gRPC over a TLS-encrypted HTTP/2 connection, so you don't need to manually configure SSL or TLS.

The Spanner client libraries are supported on Compute Engine, App Engine flexible environment, Google Kubernetes Engine, and Cloud Run functions. The Spanner client library for Java is also supported on App Engine standard environment with Java 8.

If you are using the App Engine standard environment with Go, PHP, or Python, use the REST interface to access Spanner.

Install the client library

C++

For more information about installing the C++ library, see the Setting up a C++ development environment guide.

C#

To install the Google.Cloud.Spanner.Data client library in Visual Studio, do the following:

Right-click your solution in Visual Studio and select Manage Nuget packages for solution.
Select the Include prereleasecheckbox.
Search for and install the package named Google.Cloud.Spanner.Data .

For more information, see Setting Up a C# Development Environment .

Go

go get cloud.google.com/go/spanner/...

For more information, see Setting Up a Go Development Environment .

Java

If you are using Maven , add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM .

 < dependencyManagement 
>  
< dependencies 
>  
< dependency 
>  
< groupId>com 
 . 
 google 
 . 
 cloud 
< / 
 groupId 
>  
< artifactId>libraries 
 - 
 bom 
< / 
 artifactId 
>  
< version>26 
 . 
 62 
 . 
 0 
< / 
 version 
>  
< type>pom 
< / 
 type 
>  
< scope>import 
< / 
 scope 
>  
< /dependency 
> </ 
 dependencies 
>
< /dependencyManagement 
>

< dependencies 
> <dependency> 
 <groupId>com.google.cloud</ 
 groupId 
>  
< artifactId>google 
 - 
 cloud 
 - 
 spanner 
< / 
 artifactId 
>  
< /dependency 
>

If you are using Gradle , add the following to your dependencies:

  implementation 
  
 platform 
 ( 
 'com.google.cloud:libraries-bom:26.66.0' 
 ) 
 implementation 
  
 'com.google.cloud:google-cloud-spanner'

If you are using sbt , add the following to your dependencies:

  libraryDependencies 
  
 += 
  
 "com.google.cloud" 
  
 % 
  
 "google-cloud-spanner" 
  
 % 
  
 "6.99.0"

If you're using Visual Studio Code, IntelliJ, or Eclipse, you can add client libraries to your project using the following IDE plugins:

The plugins provide additional functionality, such as key management for service accounts. Refer to each plugin's documentation for details.

For more information, see Setting Up a Java Development Environment .

Node.js

npm install @google-cloud/spanner

For more information, see Setting Up a Node.js Development Environment .

PHP

composer require google/cloud-spanner

For more information, see Using PHP on Google Cloud .

Python

pip install --upgrade google-cloud-spanner

For more information, see Setting Up a Python Development Environment .

Ruby

gem install google-cloud-spanner

For more information, see Setting Up a Ruby Development Environment .

Set up authentication

To authenticate calls to Google Cloud APIs, client libraries support Application Default Credentials (ADC) ; the libraries look for credentials in a set of defined locations and use those credentials to authenticate requests to the API. With ADC, you can make credentials available to your application in a variety of environments, such as local development or production, without needing to modify your application code.

For production environments, the way you set up ADC depends on the service and context. For more information, see Set up Application Default Credentials .

For a local development environment, you can set up ADC with the credentials that are associated with your Google Account:

Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
```
gcloud  
init
```
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:
```
gcloud  
auth  
application-default  
login
```
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 .

A sign-in screen appears. After you sign in, your credentials are stored in the local credential file used by ADC .

Use the client library

The following example shows how to use the client library.

C++

  #include 
  
 "google/cloud/spanner/client.h" 
 void 
  
 Quickstart 
 ( 
 std 
 :: 
 string 
  
 const 
&  
 project_id 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 instance_id 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 database_id 
 ) 
  
 { 
  
 namespace 
  
 spanner 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 spanner 
 ; 
  
 auto 
  
 database 
  
 = 
  
 spanner 
 :: 
 Database 
 ( 
 project_id 
 , 
  
 instance_id 
 , 
  
 database_id 
 ); 
  
 auto 
  
 connection 
  
 = 
  
 spanner 
 :: 
 MakeConnection 
 ( 
 database 
 ); 
  
 auto 
  
 client 
  
 = 
  
 spanner 
 :: 
 Client 
 ( 
 connection 
 ); 
  
 auto 
  
 rows 
  
 = 
  
 client 
 . 
 ExecuteQuery 
 ( 
 spanner 
 :: 
 SqlStatement 
 ( 
 "SELECT 'Hello World'" 
 )); 
  
 using 
  
 RowType 
  
 = 
  
 std 
 :: 
 tuple<std 
 :: 
 string 
> ; 
  
 for 
  
 ( 
 auto 
&  
 row 
  
 : 
  
 spanner 
 :: 
 StreamOf<RowType> 
 ( 
 rows 
 )) 
  
 { 
  
 if 
  
 ( 
 ! 
 row 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 row 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 std 
 :: 
 get<0> 
 ( 
 * 
 row 
 ) 
 << 
 " 
 \n 
 " 
 ; 
  
 } 
 }

C#

  using 
  
  Google.Cloud.Spanner.Data 
 
 ; 
 using 
  
 System 
 ; 
 using 
  
 System.Threading.Tasks 
 ; 
 namespace 
  
 GoogleCloudSamples.Spanner 
 { 
  
 public 
  
 class 
  
 QuickStart 
  
 { 
  
 static 
  
 async 
  
 Task 
  
 MainAsync 
 () 
  
 { 
  
 string 
  
 projectId 
  
 = 
  
 "YOUR-PROJECT-ID" 
 ; 
  
 string 
  
 instanceId 
  
 = 
  
 "my-instance" 
 ; 
  
 string 
  
 databaseId 
  
 = 
  
 "my-database" 
 ; 
  
 string 
  
 connectionString 
  
 = 
  
 $"Data Source=projects/{projectId}/instances/{instanceId}/" 
  
 + 
  
 $"databases/{databaseId}" 
 ; 
  
 // Create connection to Cloud Spanner. 
  
 using 
  
 ( 
 var 
  
 connection 
  
 = 
  
 new 
  
  SpannerConnection 
 
 ( 
 connectionString 
 )) 
  
 { 
  
 // Execute a simple SQL statement. 
  
 var 
  
 cmd 
  
 = 
  
 connection 
 . 
  CreateSelectCommand 
 
 ( 
  
 @"SELECT ""Hello World"" as test" 
 ); 
  
 using 
  
 ( 
 var 
  
 reader 
  
 = 
  
 await 
  
 cmd 
 . 
  ExecuteReaderAsync 
 
 ()) 
  
 { 
  
 while 
  
 ( 
 await 
  
 reader 
 . 
  ReadAsync 
 
 ()) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
  
 reader 
 . 
 GetFieldValue<string> 
 ( 
 "test" 
 )); 
  
 } 
  
 } 
  
 } 
  
 } 
  
 public 
  
 static 
  
 void 
  
 Main 
 ( 
 string 
 [] 
  
 args 
 ) 
  
 { 
  
 MainAsync 
 (). 
 Wait 
 (); 
  
 } 
  
 } 
 }

Go

  // Sample spanner_quickstart is a basic program that uses Cloud Spanner. 
 package 
  
 main 
 import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "log" 
  
 "cloud.google.com/go/spanner" 
  
 "google.golang.org/api/iterator" 
 ) 
 func 
  
 main 
 () 
  
 { 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 // This database must exist. 
  
 databaseName 
  
 := 
  
 "projects/your-project-id/instances/your-instance-id/databases/your-database-id" 
  
 client 
 , 
  
 err 
  
 := 
  
 spanner 
 . 
 NewClient 
 ( 
 ctx 
 , 
  
 databaseName 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatalf 
 ( 
 "Failed to create client %v" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 stmt 
  
 := 
  
 spanner 
 . 
  Statement 
 
 { 
 SQL 
 : 
  
 "SELECT 1" 
 } 
  
 iter 
  
 := 
  
 client 
 . 
  Single 
 
 (). 
 Query 
 ( 
 ctx 
 , 
  
 stmt 
 ) 
  
 defer 
  
 iter 
 . 
 Stop 
 () 
  
 for 
  
 { 
  
 row 
 , 
  
 err 
  
 := 
  
 iter 
 . 
 Next 
 () 
  
 if 
  
 err 
  
 == 
  
 iterator 
 . 
 Done 
  
 { 
  
 fmt 
 . 
 Println 
 ( 
 "Done" 
 ) 
  
 return 
  
 } 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatalf 
 ( 
 "Query failed with %v" 
 , 
  
 err 
 ) 
  
 } 
  
 var 
  
 i 
  
 int64 
  
 if 
  
 row 
 . 
  Columns 
 
 ( 
& i 
 ) 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatalf 
 ( 
 "Failed to parse row %v" 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Printf 
 ( 
 "Got value %v\n" 
 , 
  
 i 
 ) 
  
 } 
 }

Java

  // Imports the Google Cloud client library 
 import 
  
 com.google.cloud.spanner. DatabaseClient 
 
 ; 
 import 
  
 com.google.cloud.spanner. DatabaseId 
 
 ; 
 import 
  
 com.google.cloud.spanner. ResultSet 
 
 ; 
 import 
  
 com.google.cloud.spanner. Spanner 
 
 ; 
 import 
  
 com.google.cloud.spanner. SpannerOptions 
 
 ; 
 import 
  
 com.google.cloud.spanner. Statement 
 
 ; 
 /** 
 * A quick start code for Cloud Spanner. It demonstrates how to setup the Cloud Spanner client and 
 * execute a simple query using it against an existing database. 
 */ 
 public 
  
 class 
 QuickstartSample 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 ... 
  
 args 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 if 
  
 ( 
 args 
 . 
 length 
  
 != 
  
 2 
 ) 
  
 { 
  
 System 
 . 
 err 
 . 
 println 
 ( 
 "Usage: QuickStartSample <instance_id> <database_id>" 
 ); 
  
 return 
 ; 
  
 } 
  
 // Instantiates a client 
  
  SpannerOptions 
 
  
 options 
  
 = 
  
  SpannerOptions 
 
 . 
 newBuilder 
 (). 
 build 
 (); 
  
  Spanner 
 
  
 spanner 
  
 = 
  
  options 
 
 . 
 getService 
 (); 
  
 // Name of your instance & database. 
  
 String 
  
 instanceId 
  
 = 
  
 args 
 [ 
 0 
 ] 
 ; 
  
 String 
  
 databaseId 
  
 = 
  
 args 
 [ 
 1 
 ] 
 ; 
  
 try 
  
 { 
  
 // Creates a database client 
  
  DatabaseClient 
 
  
 dbClient 
  
 = 
  
 spanner 
 . 
  getDatabaseClient 
 
 ( 
 DatabaseId 
 . 
 of 
 ( 
 options 
 . 
 getProjectId 
 (), 
  
 instanceId 
 , 
  
 databaseId 
 )); 
  
 // Queries the database 
  
  ResultSet 
 
  
 resultSet 
  
 = 
  
 dbClient 
 . 
  singleUse 
 
 (). 
 executeQuery 
 ( 
  Statement 
 
 . 
 of 
 ( 
 "SELECT 1" 
 )); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "\n\nResults:" 
 ); 
  
 // Prints the results 
  
 while 
  
 ( 
 resultSet 
 . 
  next 
 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "%d\n\n" 
 , 
  
 resultSet 
 . 
 getLong 
 ( 
 0 
 )); 
  
 } 
  
 } 
  
 finally 
  
 { 
  
 // Closes the client which will free up the resources used 
  
 spanner 
 . 
  close 
 
 (); 
  
 } 
  
 } 
 }

Node.js

  // Imports the Google Cloud client library 
 const 
  
 { 
 Spanner 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/spanner 
' 
 ); 
 // Creates a client 
 const 
  
 spanner 
  
 = 
  
 new 
  
  Spanner 
 
 ({ 
 projectId 
 }); 
 // Gets a reference to a Cloud Spanner instance and database 
 const 
  
 instance 
  
 = 
  
 spanner 
 . 
 instance 
 ( 
 instanceId 
 ); 
 const 
  
 database 
  
 = 
  
 instance 
 . 
 database 
 ( 
 databaseId 
 ); 
 // The query to execute 
 const 
  
 query 
  
 = 
  
 { 
  
 sql 
 : 
  
 'SELECT 1' 
 , 
 }; 
 // Execute a simple SQL statement 
 const 
  
 [ 
 rows 
 ] 
  
 = 
  
 await 
  
 database 
 . 
 run 
 ( 
 query 
 ); 
 console 
 . 
 log 
 ( 
 `Query: 
 ${ 
 rows 
 . 
 length 
 } 
 found.` 
 ); 
 rows 
 . 
 forEach 
 ( 
 row 
  
 = 
>  
 console 
 . 
 log 
 ( 
 row 
 ));

PHP

  # Includes the autoloader for libraries installed with composer 
 require __DIR__ . '/vendor/autoload.php'; 
 # Imports the Google Cloud client library 
 use Google\Cloud\Spanner\SpannerClient; 
 # Your Google Cloud Platform project ID 
 $projectId = 'YOUR_PROJECT_ID'; 
 # Instantiates a client 
 $spanner = new SpannerClient([ 
 'projectId' => $projectId 
 ]); 
 # Your Cloud Spanner instance ID. 
 $instanceId = 'your-instance-id'; 
 # Get a Cloud Spanner instance by ID. 
 $instance = $spanner->instance($instanceId); 
 # Your Cloud Spanner database ID. 
 $databaseId = 'your-database-id'; 
 # Get a Cloud Spanner database by ID. 
 $database = $instance->database($databaseId); 
 # Execute a simple SQL statement. 
 $results = $database->execute('SELECT "Hello World" as test'); 
 foreach ($results as $row) { 
 print($row['test'] . PHP_EOL); 
 }

Python

  # Imports the Google Cloud Client Library. 
 from 
  
 google.cloud 
  
 import 
  spanner 
 
 # Your Cloud Spanner instance ID. 
 # instance_id = "my-instance-id" 
 # 
 # Your Cloud Spanner database ID. 
 # database_id = "my-database-id" 
 # Instantiate a client. 
 spanner_client 
 = 
  spanner 
 
 . 
  Client 
 
 () 
 # Get a Cloud Spanner instance by ID. 
 instance 
 = 
 spanner_client 
 . 
  instance 
 
 ( 
 instance_id 
 ) 
 # Get a Cloud Spanner database by ID. 
 database 
 = 
 instance 
 . 
 database 
 ( 
 database_id 
 ) 
 # Execute a simple SQL statement. 
 with 
 database 
 . 
 snapshot 
 () 
 as 
 snapshot 
 : 
 results 
 = 
 snapshot 
 . 
 execute_sql 
 ( 
 "SELECT 1" 
 ) 
 for 
 row 
 in 
 results 
 : 
 print 
 ( 
 row 
 )

Ruby

  # Imports the Google Cloud client library 
 require 
  
 "google/cloud/spanner" 
 # Your Google Cloud Platform project ID 
 project_id 
  
 = 
  
 "YOUR_PROJECT_ID" 
 # Instantiates a client 
 spanner 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Spanner 
 
 . 
 new 
  
 project 
 : 
  
 project_id 
 # Your Cloud Spanner instance ID 
 instance_id 
  
 = 
  
 "my-instance" 
 # Your Cloud Spanner database ID 
 database_id 
  
 = 
  
 "my-database" 
 # Gets a reference to a Cloud Spanner instance database 
 database_client 
  
 = 
  
 spanner 
 . 
  client 
 
  
 instance_id 
 , 
  
 database_id 
 # Execute a simple SQL statement 
 results 
  
 = 
  
 database_client 
 . 
 execute_query 
  
 "SELECT 1" 
 results 
 . 
 rows 
 . 
  each 
 
  
 do 
  
 | 
 row 
 | 
  
 puts 
  
 row 
 end

Use the client library for administrator operations

The following list contains links to all the administrator operations you can use in the Spanner client library:

Use Spanner Graph with client libraries

You can use client libraries to setup, modify, and query property graphs in Spanner Graph. The following list contains links to learn about and get started with Spanner Graph using client libraries:

Additional resources

C++

The following list contains links to more resources related to the client library for C++:

C#

The following list contains links to more resources related to the client library for C#:

Go

The following list contains links to more resources related to the client library for Go:

Java

The following list contains links to more resources related to the client library for Java:

Node.js

The following list contains links to more resources related to the client library for Node.js:

PHP

The following list contains links to more resources related to the client library for PHP:

Python

The following list contains links to more resources related to the client library for Python:

Ruby

The following list contains links to more resources related to the client library for Ruby:

Additional client libraries

In addition to the libraries shown above, a Spring Data module is available for Java applications. Spring Data Spanner helps you use Spanner in any application that's built with the Spring Framework .

To get started, learn how to add Spring Data Spanner to your application .

Spanner client libraries Stay organized with collections Save and categorize content based on your preferences.

Install the client library

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Set up authentication

Use the client library

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Use the client library for administrator operations

Use Spanner Graph with client libraries

Additional resources

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Additional client libraries

Spanner client libraries