gcp-firestore-deep

name	gcp-firestore-deep
description	Use when working with Gcp Firestore Deep — google Cloud Firestore document and collection analysis, index management, security rules review, usage monitoring, and performance diagnostics via gcloud CLI.
connection_type	gcp
preload	false

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

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. 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

1. Database naming: The default database is named (default) with parentheses. Always quote it in commands to avoid shell interpretation.
2. Index build time: Composite index creation can take minutes to hours depending on data volume. Check state field before querying with new indexes.
3. Hot spots: Sequential document IDs (timestamps, auto-increment) cause write hot spots. Check for monotonically increasing key patterns.
4. Read-after-write: In multi-region databases, strong consistency is only guaranteed within a single document. Cross-document reads may see stale data.
5. Cost model: Firestore charges per document read/write/delete, not per query. A query returning 1000 documents costs 1000 read operations.