/firebase-database

name: firebase-database
description: "Use when syncing real-time data, structuring JSON trees, reading/writing, creating listeners, enabling offline persistence, managing presence, sharding, or writing security rules."
license: MIT

Firebase Realtime Database Skill

This skill defines how to correctly implement Firebase Realtime Database in Flutter applications, covering data modeling, queries, real-time sync, offline support, and security rules.

When to Use

Use this skill when working with Firebase Realtime Database for **simple data models**, **low-latency sync**, or **presence functionality**. For rich data models requiring complex queries and high scalability, use Cloud Firestore instead.

---

1. Database Selection

Choose **Realtime Database** when the app needs:

• Simple data models with simple lookups.
• Extremely low-latency synchronization (typical response times under 10ms).
• Deep queries that return an entire subtree by default.
• Access to data at any granularity, down to individual leaf-node values.
• Frequent state-syncing with built-in presence functionality.

Choose **Cloud Firestore** instead for rich data models requiring queryability, scalability, and high availability.

---

2. Setup and Configuration

flutter pub add firebase_database

import 'package:firebase_database/firebase_database.dart';

// After Firebase.initializeApp():
final DatabaseReference ref = FirebaseDatabase.instance.ref();

• Select the database location closest to users.
• Enable persistence for offline capabilities:

FirebaseDatabase.instance.setPersistenceEnabled(true);
FirebaseDatabase.instance.setPersistenceCacheSizeBytes(10000000); // 10MB

Setup Checklist

1. Confirm `Firebase.initializeApp()` completes before accessing `FirebaseDatabase.instance`. 2. Set persistence **before** any read/write operations. 3. Verify connectivity by writing a test value and reading it back.

---

3. Data Structure

• Structure data as a **flattened JSON tree** — avoid deep nesting.
• Maximum nesting depth is **32 levels**.
• Design the data structure to support the most common queries.
• Use **push IDs** for unique identifiers in list-type data:

final newPostKey = FirebaseDatabase.instance.ref().child('posts').push().key;

• **Denormalize** data when necessary — Realtime Database does not support joins.
• Custom keys must be UTF-8 encoded, max 768 bytes, and cannot contain `.` `$` `#` `[` `]` `/` or ASCII control characters 0-31 or 127.

Flattened Structure Example

// Instead of nesting chat messages inside rooms:
// rooms/roomId/messages/messageId/...

// Flatten into separate top-level paths:
// rooms/roomId: { name: "General", createdBy: "uid1" }
// room-members/roomId: { uid1: true, uid2: true }
// room-messages/roomId/messageId: { text: "Hello", sender: "uid1", timestamp: ... }

This pattern allows reading room metadata without downloading all messages.

---

4. Indexing and Querying

• Queries can sort **or** filter on a property, but not both in the same query.
• Use `.indexOn` in security rules to index frequently queried fields:

{
  "rules": {
    "dinosaurs": {
      ".indexOn": ["height", "length"]
    }
  }
}

• Queries are **deep** by default and return the entire subtree.
• Sort with `orderByChild()`, `orderByKey()`, or `orderByValue()`:

final query = FirebaseDatabase.instance.ref("dinosaurs").orderByChild("height");

• Limit results with `limitToFirst()` or `limitToLast()`:

final query = ref.orderByChild("height").limitToFirst(10);

• Range queries using `startAt()`, `endAt()`, and `equalTo()`:

// Find users whose name starts with "A"
final query = ref.child("users")
    .orderByChild("name")
    .startAt("A")
    .endAt("A\uf8ff");

---

5. Read and Write Operations

**Read once:**

final snapshot = await FirebaseDatabase.instance.ref('users/123').get();
if (snapshot.exists) {
  print(snapshot.value);
}

**Real-time listener:**

final subscription = FirebaseDatabase.instance
    .ref('users/123')
    .onValue
    .listen((event) {
      final data = event.snapshot.value;
      print(data);
    });

// Cancel when no longer needed:
subscription.cancel();

A `DatabaseEvent` fires every time data changes at the reference, including changes to children.

**Write (replace):**

await ref.set({
  "name": "John",
  "age": 18,
  "created_at": ServerValue.timestamp,
});

**Update (partial):**

await ref.update({"age": 19});

**Atomic transaction:**

final result = await FirebaseDatabase.instance
    .ref('posts/123/likes')
    .runTransaction((currentValue) {
      return Transaction.success((currentValue as int? ?? 0) + 1);
    });
print('Likes: ${result.snapshot.value}');

**Multi-path atomic update:**

final updates = <String, dynamic>{
  'posts/$postId': postData,
  'user-posts/$uid/$postId': postData,
};
await FirebaseDatabase.instance.ref().update(updates);

• Keep individual write operations under **256KB**.
• Use listeners for real-time updates rather than polling.

---

6. Designing for Scale

• Realtime Database scales to ~200,000 concurrent connections and 1,000 writes/second per database. For higher scale, **shard** data across multiple database instances.
• Avoid storing large blobs — use **Firebase Storage** for files.
• Use **server timestamps** for consistent time tracking:

await FirebaseDatabase.instance.ref('posts/123/timestamp').set(ServerValue.timestamp);

• Implement **fan-out patterns** for data accessed from multiple paths.
• Avoid deep nesting — it leads to performance issues when retrieving data.

---

7. Offline Capabilities and Presence

FirebaseDatabase.instance.setPersistenceEnabled(true);

// Keep critical paths synced when offline
FirebaseDatabase.instance.ref('important-data').keepSynced(true);

Connection State and Presen