Firebase Cloud Firestore Skill
This skill defines how to correctly implement Cloud Firestore in Flutter applications, covering data modeling, queries, real-time updates, security rules, and scale optimization.
When to Use
Use this skill when:
- Setting up and configuring Cloud Firestore in a Flutter project.
- Designing document and collection structure or planning subcollections.
- Performing read, write, batch, or transaction operations.
- Implementing real-time listeners or paginated queries.
- Optimizing for scale and avoiding write hotspots.
- Writing or debugging Firestore security rules.
1. Database Selection
Choose Cloud Firestore when the app needs:
- Rich, hierarchical data models with subcollections.
- Complex queries: chaining filters, combining filtering and sorting on a property.
- Transactions that atomically read and write data from any part of the database.
- High availability (typical uptime 99.999%) or critical-level reliability.
- Automatic scaling to millions of concurrent users.
Use Realtime Database instead for simple data models requiring simple lookups and extremely low-latency synchronization (typical response times under 10ms).
2. Setup and Configuration
flutter pub add cloud_firestore
import 'package:cloud_firestore/cloud_firestore.dart';
final db = FirebaseFirestore.instance; // after Firebase.initializeApp()
Location:
- Select the database location closest to users and compute resources.
- Use multi-region locations for critical apps (maximum availability and durability).
- Use regional locations for lower costs and lower write latency.
iOS/macOS: Consider pre-compiled frameworks to improve build times:
pod 'FirebaseFirestore',
:git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
:tag => 'IOS_SDK_VERSION'
Offline persistence is enabled by default on mobile. Configure cache size:
FirebaseFirestore.instance.settings = const Settings(
persistenceEnabled: true,
cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED,
);
3. Document Structure
- Avoid document IDs
. and .. (special meaning in Firestore paths).
- Avoid forward slashes (
/) in document IDs (path separators).
- Do not use monotonically increasing document IDs (e.g.,
Customer1, Customer2) — causes write hotspots.
- Use Firestore's automatic document IDs when possible:
final docRef = await db.collection("users").add({
'name': 'Ada Lovelace',
'email': '[email protected]',
'created_at': FieldValue.serverTimestamp(),
});
print('Created document with ID: ${docRef.id}');
- Avoid these characters in field names (require extra escaping):
. [ ] * `
- Use subcollections within documents to organize complex, hierarchical data rather than deeply nested objects.
4. Indexing
- Firestore queries are indexed by default; query performance is proportional to the result set size, not the dataset size.
- Set collection-level index exemptions to reduce write latency and storage costs.
- Disable Descending and Array indexing for fields that do not need them.
- Exempt string fields with long values that are not used for querying.
- Exempt fields with sequential values (e.g., timestamps) from indexing if not used in queries — avoids the 500 writes/second index limit.
- Add single-field exemptions for TTL fields.
- Exempt large array or map fields not used in queries — avoids the 40,000 index entries per document limit.
5. Read and Write Operations
Read All Documents in a Collection
final querySnapshot = await db.collection("users").get();
for (var doc in querySnapshot.docs) {
print("${doc.id} => ${doc.data()}");
}
Query with Filters
final query = db.collection("users")
.where("age", isGreaterThanOrEqualTo: 18)
.orderBy("age")
.limit(20);
final results = await query.get();
// First page
final first = db.collection("cities").orderBy("name").limit(25);
final firstSnapshot = await first.get();
// Next page using last document as cursor
final lastDoc = firstSnapshot.docs.last;
final next = db.collection("cities")
.orderBy("name")
.startAfterDocument(lastDoc)
.limit(25);
- Do not use offsets for pagination — use cursors to avoid retrieving and being billed for skipped documents.
Write with Server Timestamp
await db.collection("users").doc("user_1").set({
'name': 'Grace Hopper',
'updated_at': FieldValue.serverTimestamp(),
});
Batch Write (Atomic, Up to 500 Operations)
final batch = db.batch();
batch.set(db.collection("cities").doc("LA"), {'name': 'Los Angeles'});
batch.update(db.collection("cities").doc("SF"), {'population': 860000});
batch.delete(db.collection("cities").doc("OLD"));
await batch.commit();
Transaction
await db.runTransaction((transaction) async {
final snapshot = await transaction.get(db.collection("counters").doc("visits"));
final currentCount = snapshot.get("count") as int;
transaction.update(snapshot.reference, {"count": currentCount + 1});
});
- Execute independent operations (e.g., a document lookup and a query) in parallel, not sequentially.
- Be aware of write rate limits: ~1 write per second per document.
- For writing a large number of documents, use a bulk writer instead of the atomic batch writer.
6. Designing for Scale
- Avoid high read or write rates to lexicographically close documents (hotspotting).
- Avoid creating new documents with monotonically increasing fields (like timestamps) at a very high rate.
- Avoid deleting documents in a collection at a high rate.
- Gradually increase traffic when writing to the database at a high rate — ramp up over 5 minutes.
- Avoid queries that skip over recently deleted data — use
start_at to find the correct start point.
- Distribute writes across different document paths to avoid contention.
- Firestore scales automatically to ~1 million concurrent connections and 10,000 writes/second.
7. Real-time Updates
final subscription = db.collection("messages")
.where("room", isEqualTo: "general")
.orderBy("timestamp", descending: true)
.limit(50)
.snapshots()
.listen((querySnapshot) {
for (var change in querySnapshot.docChanges) {
switch (change.type) {
case DocumentChangeType.added:
print("New message: ${change.doc.data()}");
break;
case DocumentChangeType.modified:
print("Modified: ${change.doc.data()}");
break;
case DocumentChangeType.removed:
print("Removed: ${change.doc.id}");
break;
}
}
});
// Detach when no longer needed:
subscription.cancel();
- Limit the number of simultaneous real-time listeners.
- Detach listeners when they are no longer needed to avoid memory leaks and unnecessary reads.
- Use compound queries to filter data server-side rather than filtering on the client.
- For large collections, use queries to limit the data being listened to — never listen to an entire large collection.
8. Security
- Always use Firebase Security Rules to protect Firestore data.
- Security rules do not cascade unless a wildcard is used.
- If a query's results might contain data the user does not have access to, the entire query fails.
Example rules for user-owned documents:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /users/{userId} {
allow read, update, delete: if request.auth != null && request.auth.uid == userId;
allow create: if request.auth != null;
}
}
}
- Validate user input before submitting to Firestore to prevent injection attacks.
- Use transactions for operations that require atomic updates to multiple documents.
- Implement proper error handling for all Firestore operations.
- Never store sensitive information in Firestore without proper access controls.
References
addyosmani/agent-skills103k
