Firebase Integration Guide

Overview

Firebase is Google's platform for building web and mobile applications. Firestore is a NoSQL, document-oriented database with real-time synchronization.

Integration Type: Firestore NoSQL Database + Authentication
Authentication: Service Account JSON credentials
Connection Method: REST API with OAuth2 JWT tokens
Data Model: Collections containing Documents with key-value fields

Getting Started

Prerequisites:

• A Google account
• Access to Google Cloud Console
• A Firebase project created
• Firestore database initialized

Steps to Create a Firebase Project:

1. Go to https://console.firebase.google.com
2. Click "Add project" or "Create a project"
3. Enter your project name
4. Accept the terms and click "Continue"
5. Choose analytics settings
6. Click "Create project"
7. Go to "Firestore Database" and click "Create database"
8. Choose test mode for development
9. Select your region (closest to your users)
10. Click "Create"

Obtaining Credentials

Firebase uses a Service Account JSON file for secure authentication.

Steps to Get Service Account Credentials:

1. Go to Firebase Console: https://console.firebase.google.com
2. Click your project
3. Click the gear icon (⚙️) at the top left
4. Select "Project settings"
5. Click "Service accounts" tab
6. Click "Generate a new private key" button
7. A JSON file will download - this is your Service Account
8. Keep this file safe and secure!

Required Information:

• Service Account JSON: The complete JSON file from Firebase Console
• Project ID: Found in the JSON file as "project_id"
• Database ID: You must use "(default)" database - Firebase automatically creates this when you initialize Firestore

⚠️ Important - Default Database Requirement: When connecting Firebase to Tellus, you must use the default Firestore database. Do NOT try to use a named database unless you created a separate Firestore instance. The default database ID is always "(default)".

Configuration in Dashboard

1. Click "Add Project"
2. Select "Firebase" as Database Provider
3. Choose Upload Method:
   • Option A: Upload JSON file directly
   • Option B: Copy and paste JSON content
4. Fill in Firebase Details:
   • Project ID: Your Firebase project ID (auto-filled from JSON)
   • Database ID: Usually "(default)"
5. Click "Test Connection" to validate
6. Click "Save Project"

Tellus Integration

Tellus bridges the NoSQL document world of Firebase with standard unified queries. To connect Tellus to Firebase, configure your service account in tellus.config.js:

import { Tellus } from '@tellus/client';

const tellus = new Tellus({
  databases: {
    mobileApp: {
      provider: 'firebase',
      projectId: process.env.FIREBASE_PROJECT_ID,
      clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
      privateKey: process.env.FIREBASE_PRIVATE_KEY
    }
  }
});

Basic Operations (CRUD)

Tellus simplifies Firestore's complex document referencing into a clean, chainable API.

1. Create (Insert)

// Create a new post document. Firestore auto-generates the ID.
const newPost = await tellus.db('mobileApp').collection('posts').insert({
  title: 'Hello Tellus',
  content: 'Firebase is great!',
  tags: ['welcome', 'intro'],
  publishedAt: new Date()
});

2. Read (Select)

// Find documents with complex array-contains queries
const taggedPosts = await tellus.db('mobileApp').collection('posts')
  .find({ tags: { $contains: 'intro' } })
  .orderBy('publishedAt', 'desc')
  .limit(10)
  .execute();

3. Update

// Update specific fields without overwriting the document
await tellus.db('mobileApp').collection('posts')
  .where('id', '==', newPost.id)
  .update({ 'stats.views': 150 });

4. Delete

// Delete a post
await tellus.db('mobileApp').collection('posts')
  .where('id', '==', newPost.id)
  .delete();

Using Firebase in the Dashboard

• Browse Collections - View all Firestore collections and document count
• View Documents - Click a collection to see documents in JSON format
• Search and Filter - Find documents by ID or field values
• Create Documents - Add new documents with custom fields and data types
• Edit Documents - Modify existing document fields
• Query Documents - Create filters and query combinations
• View Users - See Firebase Authentication users

Example Setup: Blog Application

Step 1: Create Collections

Create a "posts" collection with documents:

{
  "title": "Getting Started with Firebase",
  "author": "John Doe",
  "content": "Firebase is a great platform...",
  "published": true,
  "createdAt": Timestamp.now(),
  "views": 0,
  "tags": ["firebase", "guide"]
}

Step 2: Create "comments" collection

{
  "postId": "post-document-id",
  "author": "Jane Smith",
  "content": "Great tutorial!",
  "createdAt": Timestamp.now(),
  "likes": 5
}

Step 3: Configure Security Rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /posts/{document=**} {
      allow read: if true;
      allow create, update: if request.auth != null;
    }
    match /comments/{document=**} {
      allow read: if true;
      allow create: if request.auth != null;
    }
  }
}

Firestore Data Types

• String: Text data - "Hello, World!"
• Number: Integers or decimals - 42, 3.14
• Boolean: True or False
• Timestamp: Date and time - Timestamp.now()
• GeoPoint: Latitude/longitude coordinates
• Reference: Link to another document
• Array: Lists of values - ["apple", "banana"]
• Map: Nested objects - {name: "John", age: 30}
• Null: Empty/no value

Security Best Practices

• Service Account Keys: Keep JSON files secure. Don't commit to version control. Rotate keys regularly.
• Security Rules: Define detailed Firestore security rules. Never use "allow read, write: if true" in production.
• Data Validation: Validate data at application level and in security rules.
• Access Control: Use Firebase Auth for user identification. Implement role-based access control.
• Encryption: Encrypt sensitive data at application level. Use field-level security rules.

Useful Links

• Firebase Console
• Firebase Documentation
• Firestore Guide
• Security Rules Documentation