firebase-database

name	firebase-database
description	Integrates Firebase Realtime Database into Flutter apps. Use when setting up Realtime Database, structuring JSON data, querying, performing read/write operations, implementing offline capabilities, or applying security rules.
metadata	{"author":"evanca"}

Firebase Realtime Database Skill

This skill defines how to correctly use Firebase Realtime Database in Flutter applications.

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 your 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 your users.
• Enable persistence for offline capabilities:

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

---

3. Data Structure

• Structure data as a flattened JSON tree — avoid deep nesting.
• Maximum nesting depth is 32 levels.
• Design your data structure to support your 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 doesn't support joins.
• Custom keys must be UTF-8 encoded, max 768 bytes, and cannot contain . $ # [ ] / or ASCII control characters 0–31 or 127.

---

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);

---

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:

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

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

Write (replace):

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

Update (partial):

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

Atomic transaction:

FirebaseDatabase.instance.ref('posts/123/likes').runTransaction((currentValue) {
  return (currentValue as int? ?? 0) + 1;
});

Multi-path atomic update:

final updates = <String, dynamic>{
  'posts/$postId': postData,
  'user-posts/$uid/$postId': postData,
};
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:

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

FirebaseDatabase.instance.setPersistenceEnabled(true);

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

// Detect connection state
FirebaseDatabase.instance.ref('.info/connected').onValue.listen((event) {
  final connected = event.snapshot.value as bool? ?? false;
  print('Connected: $connected');
});

• Use value events (onValue) to read data and get notified of updates — optimized for online/offline transitions.
• Use get() only when you need data once; it probes local cache if the server is unavailable.

---

8. Security

{
  "rules": {
    "users": {
      "$uid": {
        ".read": "$uid === auth.uid",
        ".write": "$uid === auth.uid"
      }
    }
  }
}

• Use .read, .write, .validate, and .indexOn to control access and validate data.
• Read and write rules cascade in Realtime Database.
• Use the auth variable to authenticate users in security rules.
• Test rules thoroughly using the Firebase console's rules simulator.
• Use the Firebase Emulator Suite for local testing.

---

References

• Firebase Realtime Database Flutter documentation
• Structure data
• Read and write data

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.