cloudthinker-ai Firestore Skill
Manage and analyze Google Cloud Firestore using gcloud firestore commands.
Discovery-First Rule
ALWAYS discover before acting. Never assume database names, collection names, or index configurations.
# Discover Firestore databases
gcloud firestore databases list --format=json \
| jq '[.[] | {name: .name, type: .type, locationId: .locationId, concurrencyMode: .concurrencyMode, appEngineIntegrationMode: .appEngineIntegrationMode, deleteProtectionState: .deleteProtectionState}]'
Parallel Execution Requirement
ALL independent operations MUST run in parallel using background jobs (&) and wait.
for db in $(gcloud firestore databases list --format="value(name)" | xargs -I{} basename {}); do
{
gcloud firestore indexes composite list --database="$db" --format=json
} &
done
wait
Helper Functions
# List composite indexes
list_composite_indexes() {
local db="${1:-(default)}"
gcloud firestore indexes composite list --database="$db" --format=json \
| jq '[.[] | {name: .name | split("/") | last, collection: .collectionGroup, state: .state, fields: [.fields[] | {path: .fieldPath, order: .order // .arrayConfig}]}]'
}
# List field indexes (overrides)
list_field_overrides() {
local db="${1:-(default)}"
gcloud firestore indexes fields list --database="$db" --format=json \
| jq '[.[] | select(.indexConfig.indexes) | {field: .name, indexes: .indexConfig.indexes}]'
}
# Export database
export_database() {
local db="$1" bucket="$2"
gcloud firestore export "gs://$bucket" --database="$db" --format=json
}
# Get database usage metrics
get_firestore_metrics() {
local project="$1"
gcloud monitoring time-series list \
--filter="metric.type=starts_with(\"firestore.googleapis.com/\")" \
--interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
--format=json --limit=100
}
Common Operations
1. Database Overview
# List databases and their configuration
gcloud firestore databases list --format=json \
| jq '[.[] | {name: .name | split("/") | last, type: .type, location: .locationId, concurrencyMode: .concurrencyMode, pointInTimeRecovery: .pointInTimeRecoveryEnablement, deleteProtection: .deleteProtectionState}]'
2. Index Management
# Composite indexes with build status
list_composite_indexes "(default)"
# Find indexes that are still building
gcloud firestore indexes composite list --database="(default)" --format=json \
| jq '[.[] | select(.state != "READY") | {collection: .collectionGroup, state: .state, fields: [.fields[] | .fieldPath]}]'
# Field-level index overrides
list_field_overrides "(default)"
3. Collection Analysis
# Document count and storage metrics
gcloud monitoring time-series list \
--filter="metric.type=\"firestore.googleapis.com/document/count\"" \
--interval-start-time="$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)" \
--format=json
# Read/write operation metrics
gcloud monitoring time-series list \
--filter="metric.type=\"firestore.googleapis.com/api/request_count\"" \
--interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
--format=json
4. Security Rules Review
# Get current security rules (requires Firebase CLI or REST API)
# Using REST API via gcloud
PROJECT=$(gcloud config get-value project)
gcloud rest firestore.projects.databases.documents --method=GET \
"https://firestore.googleapis.com/v1/projects/$PROJECT/databases/(default)/documents" 2>/dev/null
# Check rules release history
gcloud firestore databases describe --database="(default)" --format=json
5. Usage and Performance Monitoring
# Active connections
gcloud monitoring time-series list \
--filter="metric.type=\"firestore.googleapis.com/network/active_connections\"" \
--interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
--format=json
# Snapshot listeners
gcloud monitoring time-series list \
--filter="metric.type=\"firestore.googleapis.com/network/snapshot_listeners\"" \
--interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
--format=json
# Rule evaluation metrics
gcloud monitoring time-series list \
--filter="metric.type=\"firestore.googleapis.com/rules/evaluation_count\"" \
--interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
--format=json
Output Format
Present results as a structured report:
Gcp Firestore Deep Report
═════════════════════════
Resources discovered: [count]
Resource Status Key Metric Issues
──────────────────────────────────────────────
[name] [ok/warn] [value] [findings]
Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]
Target ≤50 lines of output. Use tables for multi-resource comparisons.
Anti-Hallucination Rules
- NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
- NEVER fabricate metric names or dimensions — verify against the service documentation or
--helpoutput. - NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
- ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
- ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.
Counter-Rationalizations
| Shortcut | Counter | Why |
|---|---|---|
| "I'll skip discovery and check known resources" | Always run Phase 1 discovery first | Resource names change, new resources appear — assumed names cause errors |
| "The user only asked for a quick check" | Follow the full discovery → analysis flow | Quick checks miss critical issues; structured analysis catches silent failures |
| "Default configuration is probably fine" | Audit configuration explicitly | Defaults often leave logging, security, and optimization features disabled |
| "Metrics aren't needed for this" | Always check relevant metrics when available | API/CLI responses show current state; metrics reveal trends and intermittent issues |
| "I don't have access to that" | Try the command and report the actual error | Assumed permission failures prevent useful investigation; actual errors are informative |
Common Pitfalls
- Database naming: The default database is named
(default)with parentheses. Always quote it in commands to avoid shell interpretation. - Index build time: Composite index creation can take minutes to hours depending on data volume. Check
statefield before querying with new indexes. - Hot spots: Sequential document IDs (timestamps, auto-increment) cause write hot spots. Check for monotonically increasing key patterns.
- Read-after-write: In multi-region databases, strong consistency is only guaranteed within a single document. Cross-document reads may see stale data.
- Cost model: Firestore charges per document read/write/delete, not per query. A query returning 1000 documents costs 1000 read operations.