Skip to content

jeremylongshore/tons-of-skills-marketplace / plugins/community/jeremy-firestore/skills/firestore-operations-manager

firestore-operations-manager

Verified

Manage Firebase/Firestore operations including CRUD, queries, batch processing, and index/rule guidance. Use when you need to create/update/query Firestore documents, run batch writes, troubleshoot missing indexes, or plan migrations. Trigger with phrases like "firestore operations", "create firestore document", "batch write", "missing index", or "fix firestore query".

FileKindSize
ARD.mdmarkdown9.8 KB
PRD.mdmarkdown6.7 KB
SKILL.mdskill md2.9 KB
references/errors.mdmarkdown7.7 KB
references/examples.mdmarkdown7.0 KB
references/implementation.mdmarkdown7.0 KB
scripts/setup-firestore.shexecutablescript1.6 KB
# PRD: Firestore Operations Manager Skill

## Problem Statement

Firestore operations at scale require deep knowledge of batch write mechanics, composite index design, security rules authoring, and migration strategies. Developers routinely hit production issues -- missing composite indexes that crash queries, write contention on hot documents, security rules that silently block legitimate operations, and data migrations that lose documents or corrupt fields.

These problems share a root cause: Firestore's document model and operational constraints (500-write batch limit, 1-write-per-second-per-document sustained, mandatory composite indexes for multi-field queries) are well documented but poorly surfaced at development time. Errors appear only at runtime, often in production.

## Target Users

| Persona | Description | Key Need |
|---------|-------------|----------|
| Firebase developer | Building apps on Firestore, intermediate skill | Correct CRUD patterns, query optimization, index guidance |
| Backend engineer | Migrating data or building ingestion pipelines | Safe batch operations with checkpoints and rollback |
| Data team | Managing production Firestore data at scale | Migration strategies, schema evolution, cost control |
| Security-conscious developer | Writing or auditing Firestore security rules | Rules that pass emulator tests and enforce least privilege |

## Success Criteria

1. **Zero data loss on migrations**: Batch operations include checkpointing so that a failure at document 50,000 of 100,000 resumes from 50,000, not from 0.
2. **Correct indexes on first deploy**: Composite indexes are identified before deployment, not discovered via runtime FAILED_PRECONDITION errors.
3. **Rules pass emulator tests**: Security rules generated by this skill pass `@firebase/rules-unit-testing` validation against expected access patterns.
4. **Batch operations under limits**: All batch writes stay within the 500-operation limit per commit; all transactions complete within the 270-second server-side deadline.
5. **Paginated reads by default**: Queries returning potentially large result sets use cursor-based pagination, not unbounded `.get()`.

## Scope

### In Scope

- Document CRUD (create, read, update, delete) with proper error handling
- Batch writes (up to 500 operations per commit) with retry logic
- Transactions for multi-document atomic operations
- Composite index detection and `firestore.indexes.json` generation
- Security rules authoring with helper functions and field-level validation
- Emulator-first testing workflow for rules and queries
- Data migrations: backfill new fields, transform existing fields, move between collections
- Cursor-based pagination for large result sets
- Write contention mitigation (distributed counters, sharding)
- Cost estimation for read/write patterns

### Out of Scope

- Firestore-to-BigQuery export streaming (use Firestore Extensions)
- Real-time listener architecture design
- Firestore in Datastore mode
- Cross-database replication or multi-region configuration
- Vertex AI vector search in Firestore (covered by firebase-vertex-ai skill)

## Functional Requirements

### FR-1: Schema-Aware CRUD

The skill must detect the existing collection schema (by reading sample documents) before proposing writes. New fields added via `update()` must not overwrite existing data unless explicitly requested.

### FR-2: Batch Write Management

Batch writes must:

- Chunk operations into groups of 500 (Firestore limit per `batch.commit()`)
- Log progress every N documents (configurable, default 1,000)
- Write a checkpoint document after each successful batch so the operation can resume
- Retry failed batches with exponential backoff (3 attempts, 1s/2s/4s delays)

### FR-3: Composite Index Generation

When the skill generates a query with multiple `where()` clauses or a `where()` + `orderBy()` combination, it must also produce the corresponding composite index entry for `firestore.indexes.json`.

### FR-4: Security Rules

Generated rules must:

- Deny all access by default (no `match /{document=**} { allow read, write: if true }`)
- Use helper functions for authentication and ownership checks
- Include field-level validation for create and update operations
- Be testable with `@firebase/rules-unit-testing`

### FR-5: Migration Operations

Migrations must:

- Support backfill (add field to existing documents) and transform (modify field values)
- Write a checkpoint after each batch to a `_migrations/{migrationId}` document
- Support dry-run mode that reads but does not write
- Produce a summary (documents processed, skipped, failed)

### FR-6: Pagination

Queries that may return more than 100 documents must use `startAfter()` cursor-based pagination. The skill must produce both the query code and the pagination cursor management logic.

## Non-Functional Requirements

- **Throughput**: Batch operations must sustain 500 writes per second against Firestore without triggering rate limits (using staggered batch commits).
- **Idempotency**: Migrations must be idempotent -- running the same migration twice produces the same result without duplicating data.
- **Cost transparency**: For operations affecting > 1,000 documents, the skill must estimate Firestore read/write costs using current pricing ($0.06/100k reads, $0.18/100k writes).
- **Emulator compatibility**: All generated code must work against the Firestore emulator (`localhost:8080`) with no modification.

## Dependencies

| Dependency | Version | Purpose |
|------------|---------|---------|
| firebase-admin | >= 12.0 | Server-side Firestore access |
| @firebase/rules-unit-testing | >= 3.0 | Security rules testing |
| Firebase CLI | >= 13.0 | Emulator, rules deploy, index deploy |
| Node.js | >= 18 LTS | Runtime for Admin SDK scripts |

## Risks and Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Hot document write contention | Writes to same doc > 1/sec cause ABORTED errors | Use distributed counters or sharded writes for high-throughput paths |
| Composite index build time | New indexes take minutes to hours for large collections | Deploy indexes before code that depends on them; use `firebase firestore:indexes` to check status |
| Security rules too restrictive | Legitimate operations blocked in production | Test all access patterns against emulator before deploy |
| Migration halfway failure | Partial data state if script crashes mid-batch | Checkpoint after each batch; resume from last checkpoint |
| Unbounded reads | Forgetting `.limit()` on a million-doc collection | Enforce pagination for any query without a known small result set |
| Stale reads in transactions | Reading outside transaction sees older data | Always read within `runTransaction()` when consistency matters |
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall