Cloud Firestore Enterprise edition in Native mode is now available! Learn more.

Get started with Cloud Firestore Standard edition using server client libraries

This quickstart shows you how to set up Cloud Firestore Enterprise edition, add data, then view the data you just added in the Firebase console using server client libraries for C#, Go, Java, Node.js, PHP, Python, and Ruby.

Use these client libraries to set up privileged server environments with full access to your database.

Create a Cloud Firestore database

If you haven't already, create a Firebase project: In the Firebase console , click Add project, then follow the on-screen instructions to create a Firebase project or to add Firebase services to an existing Google Cloud project.
Open your project in the Firebase console. In the left panel, expand Buildand then select Firestore database .
Click Create database.
Select a location for your database.

If you aren't able to select a location, then your project's "location for default Google Cloud resources" has already been set. Some of your project's resources (like the default Cloud Firestore instance) share a common location dependency, and their location can be set either during project creation or when setting up another service that shares this location dependency.
Select a starting mode for your Cloud Firestore Security Rules :

Test mode

Good for getting started with the mobile and web client libraries, but allows anyone to read and overwrite your data. After testing, make sure to review the Secure your data section.

To get started with the web, Apple platforms, or Android SDK, select test mode.

Production mode

Denies all reads and writes from mobile and web clients. Your authenticated application servers (C#, Go, Java, Node.js, PHP, Python, or Ruby) can still access your database.

To get started with the C#, Go, Java, Node.js, PHP, Python, or Ruby server client library, select production mode.

Your initial set of Cloud Firestore Security Rules will apply to your default Cloud Firestore database. If you create multiple databases for your project, you can deploy Cloud Firestore Security Rules for each database.
Click Create.

Cloud Firestore and App Engine :With support for multiple databases, you can use both Cloud Firestore and Datastore in the same project. If you use App Engine , note that only the (default) database in standard mode with Datastore or Firestore Native APIs can be used with App Engine .

When you enable Cloud Firestore , it also enables the API in the Cloud API Manager .

Set up your development environment

Add the required dependencies and client libraries to your app.

Java

Add the Firebase Admin SDK to your app:

Using Gradle:

 implementation 
  
 ' 
 com 
 . 
 google 
 . 
 firebase 
 : 
 firebase 
 - 
 admin 
 : 
 9.7.0 
 '

Using Maven:

< dependency 
 > 
  
< groupId 
 > 
 com 
 . 
 google 
 . 
 firebase 
< / 
 groupId 
 > 
  
< artifactId 
 > 
 firebase 
 - 
 admin 
< / 
 artifactId 
 > 
  
< version 
 > 
 9.7.0 
< / 
 version 
 > 
< / 
 dependency 
 >

Follow the instructions below to initialize Cloud Firestore with the proper credentials in your environment.

Python

Add the Firebase Admin SDK to your Python app:

 pip 
 install 
 -- 
 upgrade 
 firebase 
 - 
 admin

Follow the instructions below to initialize Cloud Firestore with the proper credentials in your environment.

Node.js

Add the Firebase Admin SDK to your app:

 npm 
  
 install 
  
 firebase 
 - 
 admin 
  
 -- 
 save

Follow the instructions below to initialize Cloud Firestore with the proper credentials in your environment.

Go

Add the Firebase Admin SDK to your Go app:

 go 
  
 get 
  
 firebase 
 . 
 google 
 . 
 com 
 / 
 go

Follow the instructions below to initialize Cloud Firestore with the proper credentials in your environment.

PHP

The Cloud Firestore server client libraries (Java, Node.js, Python, Go, PHP, C#, and Ruby) use Google Application Default Credentials for authentication.
- To authenticate from your development environment, set the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to a JSON service account key file. You can create a key file on the API Console Credentials page .
```
 export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json" 
```
- In your production environment, you do not need to authenticate if you run your application on App Engine or Compute Engine, using the same project that you use for Cloud Firestore . Otherwise, set up a service account .
Install and enable the gRPC extension for PHP, which you will need to use the client library.
Add the Cloud Firestore PHP library to your app:
```
 composer require google/cloud-firestore 
```

Ruby

The Cloud Firestore server client libraries (Java, Node.js, Python, Go, PHP, C#, and Ruby) use Google Application Default Credentials for authentication.
- To authenticate from your development environment, set the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to a JSON service account key file. You can create a key file on the API Console Credentials page .
```
 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 "path/to/your/keyfile.json" 
```
- In your production environment, you do not need to authenticate if you run your application on App Engine or Compute Engine, using the same project that you use for Cloud Firestore . Otherwise, set up a service account .
Add the Cloud Firestore Ruby library to your app in your Gemfile :
```
 gem 
  
 "google-cloud-firestore" 
```
Install dependencies from your Gemfile using:
```
 bundle 
  
 install 
```

(Optional) Prototype and test with Firebase Local Emulator Suite

For mobile developers, before talking about how your app writes to and reads from Cloud Firestore , let's introduce a set of tools you can use to prototype and test Cloud Firestore functionality: Firebase Local Emulator Suite . If you're trying out different data models, optimizing your security rules, or working to find the most cost-effective way to interact with the back-end, being able to work locally without deploying live services can be a great idea.

A Cloud Firestore emulator is part of the Local Emulator Suite , which enables your app to interact with your emulated database content and config, as well as optionally your emulated project resources (functions, other databases, and security rules).

Using the Cloud Firestore emulator involves just a few steps:

Adding a line of code to your app's test config to connect to the emulator.
From the root of your local project directory, running firebase emulators:start .
Making calls from your app's prototype code using a Cloud Firestore platform SDK as usual.

A detailed walkthrough involving Cloud Firestore and Cloud Functions is available. You should also have a look at the Local Emulator Suite introduction .

Initialize Cloud Firestore

Initialize an instance of Cloud Firestore :

Java

The Cloud Firestore SDK is initialized in different ways depending on your environment. Below are the most common methods. For a complete reference, see Initialize the Admin SDK .

Initialize on Google Cloud

 import 
  
 com.google.auth.oauth2.GoogleCredentials 
 ; 
 import 
  
 com.google.cloud.firestore.Firestore 
 ; 
 import 
  
 com.google.firebase.FirebaseApp 
 ; 
 import 
  
 com.google.firebase.FirebaseOptions 
 ; 
 // Use the application default credentials 
 GoogleCredentials 
  
 credentials 
  
 = 
  
 GoogleCredentials 
 . 
 getApplicationDefault 
 (); 
 FirebaseOptions 
  
 options 
  
 = 
  
 new 
  
 FirebaseOptions 
 . 
 Builder 
 () 
  
 . 
 setCredentials 
 ( 
 credentials 
 ) 
  
 . 
 setProjectId 
 ( 
 projectId 
 ) 
  
 . 
 build 
 (); 
 FirebaseApp 
 . 
 initializeApp 
 ( 
 options 
 ); 
 Firestore 
  
 db 
  
 = 
  
 FirestoreClient 
 . 
 getFirestore 
 ();

Initialize on your own server

To use the Firebase Admin SDK on your own server, use a service account .

Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the SDK:

 import 
  
 com.google.auth.oauth2.GoogleCredentials 
 ; 
 import 
  
 com.google.cloud.firestore.Firestore 
 ; 
 import 
  
 com.google.firebase.FirebaseApp 
 ; 
 import 
  
 com.google.firebase.FirebaseOptions 
 ; 
 // Use a service account 
 InputStream 
  
 serviceAccount 
  
 = 
  
 new 
  
 FileInputStream 
 ( 
 " path/to/serviceAccount.json 
" 
 ); 
 GoogleCredentials 
  
 credentials 
  
 = 
  
 GoogleCredentials 
 . 
 fromStream 
 ( 
 serviceAccount 
 ); 
 FirebaseOptions 
  
 options 
  
 = 
  
 new 
  
 FirebaseOptions 
 . 
 Builder 
 () 
  
 . 
 setCredentials 
 ( 
 credentials 
 ) 
  
 . 
 build 
 (); 
 FirebaseApp 
 . 
 initializeApp 
 ( 
 options 
 ); 
 Firestore 
  
 db 
  
 = 
  
 FirestoreClient 
 . 
 getFirestore 
 ();

Python

The Cloud Firestore SDK is initialized in different ways depending on your environment. Below are the most common methods. For a complete reference, see Initialize the Admin SDK .

Initialize on Google Cloud

 import 
  
 firebase_admin 
 from 
  
 firebase_admin 
  
 import 
 firestore 
 # Application Default credentials are automatically created. 
 app 
 = 
 firebase_admin 
 . 
 initialize_app 
 () 
 db 
 = 
 firestore 
 . 
 client 
 () 
   firestore 
 . 
 py

An existing application default credential can also be used to initialize the SDK.

 import 
  
 firebase_admin 
 from 
  
 firebase_admin 
  
 import 
 credentials 
 from 
  
 firebase_admin 
  
 import 
 firestore 
 # Use the application default credentials. 
 cred 
 = 
 credentials 
 . 
 ApplicationDefault 
 () 
 firebase_admin 
 . 
 initialize_app 
 ( 
 cred 
 ) 
 db 
 = 
 firestore 
 . 
 client 
 () 
   firestore 
 . 
 py

Initialize on your own server

To use the Firebase Admin SDK on your own server, use a service account .

Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the SDK:

 import 
  
 firebase_admin 
 from 
  
 firebase_admin 
  
 import 
 credentials 
 from 
  
 firebase_admin 
  
 import 
 firestore 
 # Use a service account. 
 cred 
 = 
 credentials 
 . 
 Certificate 
 ( 
 'path/to/serviceAccount.json' 
 ) 
 app 
 = 
 firebase_admin 
 . 
 initialize_app 
 ( 
 cred 
 ) 
 db 
 = 
 firestore 
 . 
 client 
 () 
   firestore 
 . 
 py

Python

The Cloud Firestore SDK is initialized in different ways depending on your environment. Below are the most common methods. For a complete reference, see Initialize the Admin SDK .

Initialize on Google Cloud

 import 
  
 firebase_admin 
 from 
  
 firebase_admin 
  
 import 
 firestore_async 
 # Application Default credentials are automatically created. 
 app 
 = 
 firebase_admin 
 . 
 initialize_app 
 () 
 db 
 = 
 firestore_async 
 . 
 client 
 () 
   firestore_async 
 . 
 py

An existing application default credential can also be used to initialize the SDK.

 import 
  
 firebase_admin 
 from 
  
 firebase_admin 
  
 import 
 credentials 
 from 
  
 firebase_admin 
  
 import 
 firestore_async 
 # Use the application default credentials. 
 cred 
 = 
 credentials 
 . 
 ApplicationDefault 
 () 
 firebase_admin 
 . 
 initialize_app 
 ( 
 cred 
 ) 
 db 
 = 
 firestore_async 
 . 
 client 
 () 
   firestore_async 
 . 
 py

Initialize on your own server

To use the Firebase Admin SDK on your own server, use a service account .

Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the SDK:

 import 
  
 firebase_admin 
 from 
  
 firebase_admin 
  
 import 
 credentials 
 from 
  
 firebase_admin 
  
 import 
 firestore_async 
 # Use a service account. 
 cred 
 = 
 credentials 
 . 
 Certificate 
 ( 
 'path/to/serviceAccount.json' 
 ) 
 app 
 = 
 firebase_admin 
 . 
 initialize_app 
 ( 
 cred 
 ) 
 db 
 = 
 firestore_async 
 . 
 client 
 () 
   firestore_async 
 . 
 py

Node.js

The Cloud Firestore SDK is initialized in different ways depending on your environment. Below are the most common methods. For a complete reference, see Initialize the Admin SDK .

Initialize on Cloud Functions

 const 
  
 { 
  
 initializeApp 
 , 
  
 applicationDefault 
 , 
  
 cert 
  
 } 
  
 = 
  
 require 
 ( 
 'firebase-admin/app' 
 ); 
 const 
  
 { 
  
 getFirestore 
 , 
  
 Timestamp 
 , 
  
 FieldValue 
 , 
  
 Filter 
  
 } 
  
 = 
  
 require 
 ( 
 'firebase-admin/firestore' 
 );

 initializeApp 
 (); 
 const 
  
 db 
  
 = 
  
 getFirestore 
 (); 
   index 
 . 
 js

Initialize on Google Cloud

 const 
  
 { 
  
 initializeApp 
 , 
  
 applicationDefault 
 , 
  
 cert 
  
 } 
  
 = 
  
 require 
 ( 
 'firebase-admin/app' 
 ); 
 const 
  
 { 
  
 getFirestore 
 , 
  
 Timestamp 
 , 
  
 FieldValue 
 , 
  
 Filter 
  
 } 
  
 = 
  
 require 
 ( 
 'firebase-admin/firestore' 
 );

 initializeApp 
 ({ 
  
 credential 
 : 
  
 applicationDefault 
 () 
 }); 
 const 
  
 db 
  
 = 
  
 getFirestore 
 (); 
   index 
 . 
 js

Initialize on your own server

To use the Firebase Admin SDK on your own server (or any other Node.js environment), use a service account . Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the SDK:

 const 
  
 { 
  
 initializeApp 
 , 
  
 applicationDefault 
 , 
  
 cert 
  
 } 
  
 = 
  
 require 
 ( 
 'firebase-admin/app' 
 ); 
 const 
  
 { 
  
 getFirestore 
 , 
  
 Timestamp 
 , 
  
 FieldValue 
 , 
  
 Filter 
  
 } 
  
 = 
  
 require 
 ( 
 'firebase-admin/firestore' 
 );

 const 
  
 serviceAccount 
  
 = 
  
 require 
 ( 
 './path/to/serviceAccountKey.json' 
 ); 
 initializeApp 
 ({ 
  
 credential 
 : 
  
 cert 
 ( 
 serviceAccount 
 ) 
 }); 
 const 
  
 db 
  
 = 
  
 getFirestore 
 (); 
   index 
 . 
 js

Go

The Cloud Firestore SDK is initialized in different ways depending on your environment. Below are the most common methods. For a complete reference, see Initialize the Admin SDK .

Initialize on Google Cloud

 import 
  
 ( 
  
 "log" 
  
 firebase 
  
 "firebase.google.com/go" 
  
 "google.golang.org/api/option" 
 ) 
 // Use the application default credentials 
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
 conf 
  
 := 
  
 & 
 firebase 
 . 
 Config 
 { 
 ProjectID 
 : 
  
 projectID 
 } 
 app 
 , 
  
 err 
  
 := 
  
 firebase 
 . 
 NewApp 
 ( 
 ctx 
 , 
  
 conf 
 ) 
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatalln 
 ( 
 err 
 ) 
 } 
 client 
 , 
  
 err 
  
 := 
  
 app 
 . 
 Firestore 
 ( 
 ctx 
 ) 
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatalln 
 ( 
 err 
 ) 
 } 
 defer 
  
 client 
 . 
 Close 
 ()

Initialize on your own server

To use the Firebase Admin SDK on your own server, use a service account .

Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the SDK:

 import 
  
 ( 
  
 "log" 
  
 firebase 
  
 "firebase.google.com/go" 
  
 "google.golang.org/api/option" 
 ) 
 // Use a service account 
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
 sa 
  
 := 
  
 option 
 . 
 WithCredentialsFile 
 ( 
 "path/to/serviceAccount.json" 
 ) 
 app 
 , 
  
 err 
  
 := 
  
 firebase 
 . 
 NewApp 
 ( 
 ctx 
 , 
  
 nil 
 , 
  
 sa 
 ) 
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatalln 
 ( 
 err 
 ) 
 } 
 client 
 , 
  
 err 
  
 := 
  
 app 
 . 
 Firestore 
 ( 
 ctx 
 ) 
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatalln 
 ( 
 err 
 ) 
 } 
 defer 
  
 client 
 . 
 Close 
 ()

PHP

For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .

  use Google\Cloud\Firestore\FirestoreClient; 
 /** 
 * Initialize Cloud Firestore with default project ID. 
 */ 
 function setup_client_create(string $projectId = null) 
 { 
 // Create the Cloud Firestore client 
 if (empty($projectId)) { 
 // The `projectId` parameter is optional and represents which project the 
 // client will act on behalf of. If not supplied, the client falls back to 
 // the default project inferred from the environment. 
 $db = new FirestoreClient(); 
 printf('Created Cloud Firestore client with default project ID.' . PHP_EOL); 
 } else { 
 $db = new FirestoreClient([ 
 'projectId' => $projectId, 
 ]); 
 printf('Created Cloud Firestore client with project ID: %s' . PHP_EOL, $projectId); 
 } 
 }  setup_client_create.php

Get started with Cloud Firestore Standard edition using server client libraries Stay organized with collections Save and categorize content based on your preferences.

Create a Cloud Firestore database

Set up your development environment

Java

Python

Node.js

Go

PHP

Ruby

(Optional) Prototype and test with Firebase Local Emulator Suite

Initialize Cloud Firestore

Java

Python

Python

Node.js

Go

PHP

PHP

C#

C#

Ruby

Add data

Java

Python

Python

Node.js

Go

PHP

PHP

C#

Ruby

Java

Python

Python

Node.js

Go

PHP

PHP

C#

Ruby

Read data

Java

Python

Python

Node.js

Go

PHP

PHP

C#

Ruby

Next steps

Get started with Cloud Firestore Standard edition using server client libraries