davila7/claude-code-templates / cli-tool/components/skills/development/cloudflare-deploy
cloudflare-deploy
FlaggedDeploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.
references/d1/gotchas.md
View on GitHub# D1 Gotchas & Troubleshooting
## Common Errors
### "SQL Injection Vulnerability"
**Cause:** Using string interpolation instead of prepared statements with bind()
**Solution:** ALWAYS use prepared statements: `env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).all()` instead of string interpolation which allows attackers to inject malicious SQL
### "no such table"
**Cause:** Table doesn't exist because migrations haven't been run, or using wrong database binding
**Solution:** Run migrations using `wrangler d1 migrations apply <db-name> --remote` and verify binding name in wrangler.jsonc matches code
### "UNIQUE constraint failed"
**Cause:** Attempting to insert duplicate value in column with UNIQUE constraint
**Solution:** Catch error and return 409 Conflict status code
### "Query Timeout (30s exceeded)"
**Cause:** Query execution exceeds 30 second timeout limit
**Solution:** Break into smaller queries, add indexes to speed up queries, or reduce dataset size
### "N+1 Query Problem"
**Cause:** Making multiple individual queries in a loop instead of single optimized query
**Solution:** Use JOIN to fetch related data in single query or use `batch()` method for multiple queries
### "Missing Indexes"
**Cause:** Queries performing full table scans without indexes
**Solution:** Use `EXPLAIN QUERY PLAN` to check if index is used, then create index with `CREATE INDEX idx_users_email ON users(email)`
### "Boolean Type Issues"
**Cause:** SQLite uses INTEGER (0/1) not native boolean type
**Solution:** Bind 1 or 0 instead of true/false when working with boolean values
### "Date/Time Type Issues"
**Cause:** SQLite doesn't have native DATE/TIME types
**Solution:** Use TEXT (ISO 8601 format) or INTEGER (unix timestamp) for date/time values
## Plan Tier Limits
| Limit | Free Tier | Paid Plans | Notes |
|-------|-----------|------------|-------|
| Database size | 500 MB | 10 GB | Design for multiple DBs per tenant on paid |
| Row size | 1 MB | 1 MB | Store large files in R2, not D1 |
| Query timeout | 30s | 30s (900s with sessions) | Use sessions API for migrations |
| Batch size | 1,000 statements | 10,000 statements | Split large batches accordingly |
| Time Travel | 7 days | 30 days | Point-in-time recovery window |
| Read replicas | ❌ Not available | ✅ Available | Paid add-on for lower latency |
| Sessions API | ❌ Not available | ✅ Up to 15 min | For migrations and heavy operations |
| Concurrent requests | 10,000/min | Higher | Contact support for custom limits |
## Production Gotchas
### "Batch size exceeded"
**Cause:** Attempting to send >1,000 statements on free tier or >10,000 on paid
**Solution:** Chunk batches: `for (let i = 0; i < stmts.length; i += MAX_BATCH) await env.DB.batch(stmts.slice(i, i + MAX_BATCH))`
### "Session not closed / resource leak"
**Cause:** Forgot to call `session.close()` after using sessions API
**Solution:** Always use try/finally block: `try { await session.prepare(...) } finally { session.close() }`
### "Replication lag causing stale reads"
**Cause:** Reading from replica immediately after write - replication lag can be 100ms-2s
**Solution:** Use primary for read-after-write: `await env.DB.prepare(...)` not `env.DB_REPLICA`
### "Migration applied to local but not remote"
**Cause:** Forgot `--remote` flag when applying migrations
**Solution:** Always run `wrangler d1 migrations apply <db-name> --remote` for production
### "Foreign key constraint failed"
**Cause:** Inserting row with FK to non-existent parent, or deleting parent before children
**Solution:** Enable FK enforcement: `PRAGMA foreign_keys = ON;` and use ON DELETE CASCADE in schema
### "BLOB data corrupted on export"
**Cause:** D1 export may not handle BLOB correctly
**Solution:** Store binary files in R2, only store R2 URLs/keys in D1
### "Database size approaching limit"
**Cause:** Storing too much data in single database
**Solution:** Horizontal scale-out: create per-tenant/per-user databases, archive old data, or upgrade to paid plan
### "Local dev vs production behavior differs"
**Cause:** Local uses SQLite file, production uses distributed D1 - different performance/limits
**Solution:** Always test migrations on remote with `--remote` flag before production rollout
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |