This API is deprecated and will be turned down in January 2019. Migrate to Cloud Firestore or another data store as soon as possible to avoid disruptions to your application.

Migrating Realtime Data

This guide provides instructions on how to export Realtime document data. It also shows how that data can be imported into Cloud Firestore.

Exporting Realtime data

Realtime document data can be exported using the Google Drive v2 Realtime get API request:

GET https://www.googleapis.com/drive/v2/files/fileId/realtime

This request must be authorized with one of the following scopes:

  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.readonly
  • https://www.googleapis.com/auth/drive.file

The following JavaScript sample code shows how to export Realtime document data:

function retrieveRealtimeJson(docId, revision) {
  gapi.client.drive.realtime.get({
      'fileId': docId,
      'revision': revision
    }).then(function(response) {
      return response.data;
    });
  return null;
}

Realtime document export format

A successful Realtime.get request returns a JSON representation of the document. Due to the flexible nature of the Realtime data model, the exact layout of the response depends on the specific document retrieved. However the top layer of the document is always the same. It contains the appId, the revision of the export, and data that begins with the root map of the model. This example shows a possible arrangment of the top-level parameters in a response:

{
  "appId":"123465",
  "revision":"12",
  "data":{
    "id":"root",
    "type":"Map",
    "value":{...}
  }
}

You can find more details abou the structure of exported data in the Realtime API import and export guide.

Importing Realtime data to Cloud Firestore

Every application currently using the Realtime API must migrate to another data store. In many cases apps can use Cloud Firestore in place of the Realtime API.

Cloud Firestore is a scalable NoSQL database designed to store and sync data for client and server-side applications. It is designed to integrate seamlessly with other Firebase and Google Cloud Platform products. You can find more details in the Cloud Firestore documentation.

This section describes how you can take exported Realtime document data and import it into Cloud Firestore.

Key data store differences

There are some key differences between Google Realtime API and Cloud Firestore that you should be aware of prior to beginning your migration.

Google Realtime API Cloud Firestore
Data Sync Automatically syncs data.
Provides conflict resolution.
Uses Realtime collaboration.
Provides eventual consistency.
Automatically syncs data.
No conflict resolution.
Uses NoSQL database transactions.
Provides strong consistency.
Pricing Free Priced per transaction and data stored.
Data Location Stored in a user's Google Drive. Stored in a single database.
Data Limits Realtime document size limited to 10MB. Firestore document size limited to 1MB.
Transaction size limited to 10MB.
See the Firestore quota guide for more details.

Cloud Firestore data format

Firestore data is organized as collections of documents, which are essentially JSON objects. Firestore documents can have sub-collections that contain additional documents as well.

If the documents managed by your Google Realtime app are generally under 1MB, you can simply create a Firestore document for each Realtime document using the exported JSON data.

For documents larger than 1MB, you must break down the Realtime data into sub-collections and reorganize them into two or more Firestore documents.

Firestore security

Firestore does not support the Drive access control lists (ACLs) that the Google Realtime API uses to control access to document data. To prevent unauthorized access to your Firestore data, you can use the Firestore security model instead.

You can set up the security model by storing read/write access lists in the database and configuring the Firestore security rules to use those lists as part of the authorization scheme. For more details, see the Cloud Firestore security rules guide.

Below is an example on how a simple read/write membership model can be enforced for individual fileID documents within a single Firestore database. This model is defined in the Firebase console, under the Rules tab for your Firebase project.

service cloud.firestore {
  match /databases/{database}/documents {
    match /files/{fileID} {
      function canUserWrite() {
        return request.auth.userID in value(/databases/$(database)/documents/files/$(fileID)).writeAccessMembers;
      }

      function canUserRead() {
        return request.auth.userID in value(/databases/$(database)/documents/files/$(fileID)).readAccessMembers;
      }

      allow write: if canUserWrite();
      allow read: if canUserWrite() || canUserRead();

      match /{allChildren=**} {
        allow write: if canUserWrite();
        allow read: if canUserWrite() || canUserRead();
      }
    }
  }
}

Converting an exported document to Firestore

Once you have exported your Realtime document data, you can import it into an existing Firestore project. The following JavaScript sample code imports a single Google Realtime API document into a matching document in the Cloud Firestore. Your web app can use this code to migrate the Realtime document the first time a user attempts to access it:

const firebase = require("firebase");
// Required for side-effects
require("firebase/firestore");

firebase.initializeApp({
  apiKey: '### FIREBASE API KEY ###',
  authDomain: '### FIREBASE AUTH DOMAIN ###',
  projectId: '### CLOUD FIRESTORE PROJECT ID ###'
});

// Initialize Cloud Firestore through Firebase.
const db = firebase.firestore();

// Make a Google Drive v2 Realtime.get() request to extract the
// Realtime document data into a JSON object.
const realtimeJson = retrieveRealtimeJson(docId);

// Import the JSON data into Firestore.
const docRef = db.collection('documents').doc(docId);
docRef.set(realtimeJson.data);

Send feedback about...

Realtime API
Realtime API