Cloudflare Deploy
OpenAIOfficialPublished by OpenAI
- Skill
- Tool integration
- Cloud and DevOps
- Apache-2.0
- Medium risk
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
Cloudflare Deploy provides a centralized framework for developers to build, host, and manage projects on Cloudflare. It covers the entire ecosystem, including serverless compute (Workers), full-stack web hosting (Pages), persistent storage (D1, R2, KV), and AI-powered agent development. The skill includes decision trees to help select the right product for specific needs, authentication guidance, and troubleshooting steps for deployment issues.
What it does
- Provides decision trees to select the appropriate Cloudflare product for compute, storage, AI, or networking.
- Offers guidance on authenticating with the Cloudflare platform via CLI or CI/CD.
- Includes a comprehensive product index for quick reference to documentation.
- Provides specific patterns and API references for building stateful AI agents using the Agents SDK.
- Offers troubleshooting steps for network-related deployment failures.
- Supports infrastructure-as-code integration with tools like Pulumi and Terraform.
When to use it
- When you need to deploy, host, or publish a project to Cloudflare.
- When you are unsure which Cloudflare service (e.g., Workers vs. Pages) best fits your application requirements.
- When you need to build stateful, globally distributed AI agents.
- When you encounter network errors or timeouts during the deployment process.
- When setting up persistent storage or database solutions within the Cloudflare ecosystem.
Advantages
- Consolidates fragmented documentation into a single, navigable resource.
- Simplifies product selection through clear, use-case-driven decision trees.
- Provides actionable code patterns for complex tasks like AI agent development.
- Addresses common deployment friction points like authentication and network sandboxing.
Usage examples
- “I need to deploy a full-stack web application to Cloudflare. Which service should I use?”
- The agent will guide you to use Cloudflare Pages for full-stack web apps with Git-based deployments.
- “How do I build an AI chat agent on Cloudflare?”
- The agent will provide the Agents SDK reference, including the AIChatAgent class and examples for streaming responses and managing message history.
- “My deployment is failing with a network timeout error. What should I do?”
- The agent will advise you to rerun the deployment command with the sandbox_permissions=require_escalated flag to bypass network restrictions.
- “How do I store relational data for my worker?”
- The agent will recommend using D1 for SQLite-based relational storage or Hyperdrive for connecting to existing Postgres/MySQL databases.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/openai/cloudflare-deploy/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip cloudflare-deploy.zip -d .agents/skills
Documentation by OpenAI
Cloudflare Deploy
Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.
Prerequisites
When sandboxing blocks the deployment network calls, rerun with
sandbox_permissions=require_escalated.The deployment might take a few minutes. Use appropriate timeout values.
Authentication (Required Before Deploy)
Verify auth before wrangler deploy, wrangler pages deploy, or npm run deploy:
npx wrangler whoami # Shows account if authenticatedNot authenticated? → references/wrangler/auth.md
Interactive/local:
wrangler login(one-time OAuth)CI/CD: Set
CLOUDFLARE_API_TOKENenv var
Quick Decision Trees
"I need to run code"
Need to run code?
├─ Serverless functions at the edge → workers/
├─ Full-stack web app with Git deploys → pages/
├─ Stateful coordination/real-time → durable-objects/
├─ Long-running multi-step jobs → workflows/
├─ Run containers → containers/
├─ Multi-tenant (customers deploy code) → workers-for-platforms/
├─ Scheduled tasks (cron) → cron-triggers/
├─ Lightweight edge logic (modify HTTP) → snippets/
├─ Process Worker execution events (logs/observability) → tail-workers/
└─ Optimize latency to backend infrastructure → smart-placement/"I need to store data"
Need storage?
├─ Key-value (config, sessions, cache) → kv/
├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
├─ Object/file storage (S3-compatible) → r2/
├─ Message queue (async processing) → queues/
├─ Vector embeddings (AI/semantic search) → vectorize/
├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
├─ Secrets management → secrets-store/
├─ Streaming ETL to R2 → pipelines/
└─ Persistent cache (long-term retention) → cache-reserve/"I need AI/ML"
Need AI?
├─ Run inference (LLMs, embeddings, images) → workers-ai/
├─ Vector database for RAG/search → vectorize/
├─ Build stateful AI agents → agents-sdk/
├─ Gateway for any AI provider (caching, routing) → ai-gateway/
└─ AI-powered search widget → ai-search/"I need networking/connectivity"
Need networking?
├─ Expose local service to internet → tunnel/
├─ TCP/UDP proxy (non-HTTP) → spectrum/
├─ WebRTC TURN server → turn/
├─ Private network connectivity → network-interconnect/
├─ Optimize routing → argo-smart-routing/
├─ Optimize latency to backend (not user) → smart-placement/
└─ Real-time video/audio → realtimekit/ or realtime-sfu/"I need security"
Need security?
├─ Web Application Firewall → waf/
├─ DDoS protection → ddos/
├─ Bot detection/management → bot-management/
├─ API protection → api-shield/
├─ CAPTCHA alternative → turnstile/
└─ Credential leak detection → waf/ (managed ruleset)"I need media/content"
Need media?
├─ Image optimization/transformation → images/
├─ Video streaming/encoding → stream/
├─ Browser automation/screenshots → browser-rendering/
└─ Third-party script management → zaraz/"I need infrastructure-as-code"
Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)Product Index
Compute & Runtime
| Product | Reference |
|---|---|
| Workers | references/workers/ |
| Pages | references/pages/ |
| Pages Functions | references/pages-functions/ |
| Durable Objects | references/durable-objects/ |
| Workflows | references/workflows/ |
| Containers | references/containers/ |
| Workers for Platforms | references/workers-for-platforms/ |
| Cron Triggers | references/cron-triggers/ |
| Tail Workers | references/tail-workers/ |
| Snippets | references/snippets/ |
| Smart Placement | references/smart-placement/ |
Storage & Data
| Product | Reference |
|---|---|
| KV | references/kv/ |
| D1 | references/d1/ |
| R2 | references/r2/ |
| Queues | references/queues/ |
| Hyperdrive | references/hyperdrive/ |
| DO Storage | references/do-storage/ |
| Secrets Store | references/secrets-store/ |
| Pipelines | references/pipelines/ |
| R2 Data Catalog | references/r2-data-catalog/ |
| R2 SQL | references/r2-sql/ |
AI & Machine Learning
| Product | Reference |
|---|---|
| Workers AI | references/workers-ai/ |
| Vectorize | references/vectorize/ |
| Agents SDK | references/agents-sdk/ |
| AI Gateway | references/ai-gateway/ |
| AI Search | references/ai-search/ |
Networking & Connectivity
| Product | Reference |
|---|---|
| Tunnel | references/tunnel/ |
| Spectrum | references/spectrum/ |
| TURN | references/turn/ |
| Network Interconnect | references/network-interconnect/ |
| Argo Smart Routing | references/argo-smart-routing/ |
| Workers VPC | references/workers-vpc/ |
Security
| Product | Reference |
|---|---|
| WAF | references/waf/ |
| DDoS Protection | references/ddos/ |
| Bot Management | references/bot-management/ |
| API Shield | references/api-shield/ |
| Turnstile | references/turnstile/ |
Media & Content
| Product | Reference |
|---|---|
| Images | references/images/ |
| Stream | references/stream/ |
| Browser Rendering | references/browser-rendering/ |
| Zaraz | references/zaraz/ |
Real-Time Communication
| Product | Reference |
|---|---|
| RealtimeKit | references/realtimekit/ |
| Realtime SFU | references/realtime-sfu/ |
Developer Tools
| Product | Reference |
|---|---|
| Wrangler | references/wrangler/ |
| Miniflare | references/miniflare/ |
| C3 | references/c3/ |
| Observability | references/observability/ |
| Analytics Engine | references/analytics-engine/ |
| Web Analytics | references/web-analytics/ |
| Sandbox | references/sandbox/ |
| Workerd | references/workerd/ |
| Workers Playground | references/workers-playground/ |
Infrastructure as Code
| Product | Reference |
|---|---|
| Pulumi | references/pulumi/ |
| Terraform | references/terraform/ |
| API | references/api/ |
Other Services
| Product | Reference |
|---|---|
| Email Routing | references/email-routing/ |
| Email Workers | references/email-workers/ |
| Static Assets | references/static-assets/ |
| Bindings | references/bindings/ |
| Cache Reserve | references/cache-reserve/ |
Troubleshooting
Escalated Network Access
If deployment fails due to network issues (timeouts, DNS errors, connection resets), rerun the deploy with escalated permissions (use sandbox_permissions=require_escalated). The deploy requires escalated network access when sandbox networking blocks outbound requests.
Example guidance to the user:
The deploy needs escalated network access to deploy to Cloudflare. I can rerun the command with escalated permissions—want me to proceed?Files
- ATTRIBUTION.mdAdded by AutoGineer894 B
- LICENSE.txt10.5 KiB
- SKILL.md7.2 KiB
- agents/openai.yaml331 B
- assets/cloudflare-small.svg1.2 KiB
- assets/cloudflare.png1.2 KiB
- references/agents-sdk/README.md2.7 KiB
- references/agents-sdk/api.md5.7 KiB
- references/agents-sdk/configuration.md3.5 KiB
- references/agents-sdk/gotchas.md5.0 KiB
- references/agents-sdk/patterns.md5.5 KiB
- references/ai-gateway/README.md6.2 KiB
- references/ai-gateway/configuration.md2.9 KiB
- references/ai-gateway/dynamic-routing.md1.8 KiB
- references/ai-gateway/features.md2.7 KiB
- references/ai-gateway/sdk-integration.md2.6 KiB
- references/ai-gateway/troubleshooting.md2.4 KiB
- references/ai-search/README.md4.4 KiB
- references/ai-search/api.md2.5 KiB
- references/ai-search/configuration.md1.7 KiB
- references/ai-search/gotchas.md2.1 KiB
- references/ai-search/patterns.md2.0 KiB
- references/analytics-engine/README.md3.1 KiB
- references/analytics-engine/api.md3.1 KiB
- references/analytics-engine/configuration.md2.3 KiB
- references/analytics-engine/gotchas.md2.0 KiB
- references/analytics-engine/patterns.md2.3 KiB
- references/api-shield/README.md1.8 KiB
- references/api-shield/api.md3.8 KiB
- references/api-shield/configuration.md4.9 KiB
- references/api-shield/gotchas.md4.8 KiB
- references/api-shield/patterns.md5.7 KiB
- references/api/README.md2.3 KiB
- references/api/api.md4.2 KiB
- references/api/configuration.md3.7 KiB
- references/api/gotchas.md5.3 KiB
- references/api/patterns.md4.5 KiB
- references/argo-smart-routing/README.md4.0 KiB
- references/argo-smart-routing/api.md6.4 KiB
- references/argo-smart-routing/configuration.md4.4 KiB
- references/argo-smart-routing/gotchas.md4.2 KiB
- references/argo-smart-routing/patterns.md3.0 KiB
- references/bindings/README.md3.9 KiB
- references/bindings/api.md5.1 KiB
- references/bindings/configuration.md4.4 KiB
- references/bindings/gotchas.md6.0 KiB
- references/bindings/patterns.md4.9 KiB
- references/bot-management/README.md3.7 KiB
- references/bot-management/api.md5.7 KiB
- references/bot-management/configuration.md5.6 KiB
- references/bot-management/gotchas.md5.5 KiB
- references/bot-management/patterns.md4.9 KiB
- references/browser-rendering/README.md3.0 KiB
- references/browser-rendering/api.md2.9 KiB
- references/browser-rendering/configuration.md1.8 KiB
- references/browser-rendering/gotchas.md2.5 KiB
- references/browser-rendering/patterns.md2.6 KiB
- references/c3/README.md3.3 KiB
- references/c3/api.md2.2 KiB
- references/c3/configuration.md1.6 KiB
- references/c3/gotchas.md2.3 KiB
- references/c3/patterns.md2.2 KiB
- references/cache-reserve/README.md5.5 KiB
- references/cache-reserve/api.md5.9 KiB
- references/cache-reserve/configuration.md3.6 KiB
- references/cache-reserve/gotchas.md5.7 KiB
- references/cache-reserve/patterns.md6.1 KiB
- references/containers/README.md3.4 KiB
- references/containers/api.md4.2 KiB
- references/containers/configuration.md5.3 KiB
- references/containers/gotchas.md4.4 KiB
- references/containers/patterns.md4.8 KiB
- references/cron-triggers/README.md2.9 KiB
- references/cron-triggers/api.md5.7 KiB
- references/cron-triggers/configuration.md4.2 KiB
- references/cron-triggers/gotchas.md6.2 KiB
- references/cron-triggers/patterns.md6.8 KiB
- references/d1/README.md4.6 KiB
- references/d1/api.md6.6 KiB
- references/d1/configuration.md5.3 KiB
- references/d1/gotchas.md4.2 KiB
- references/d1/patterns.md7.1 KiB
- references/ddos/README.md2.0 KiB
- references/ddos/api.md4.1 KiB
- references/ddos/configuration.md2.9 KiB
- references/ddos/gotchas.md3.8 KiB
- references/ddos/patterns.md5.5 KiB
- references/do-storage/README.md2.7 KiB
- references/do-storage/api.md3.5 KiB
- references/do-storage/configuration.md2.2 KiB
- references/do-storage/gotchas.md5.1 KiB
- references/do-storage/patterns.md5.2 KiB
- references/do-storage/testing.md4.8 KiB
- references/durable-objects/README.md6.5 KiB
- references/durable-objects/api.md6.0 KiB
- references/durable-objects/configuration.md4.2 KiB
- references/durable-objects/gotchas.md7.1 KiB
- references/durable-objects/patterns.md6.5 KiB
- references/email-routing/README.md3.4 KiB
- references/email-routing/api.md5.2 KiB
- references/email-routing/configuration.md3.5 KiB
- references/email-routing/gotchas.md4.0 KiB
- references/email-routing/patterns.md5.4 KiB
- references/email-workers/README.md5.2 KiB
- references/email-workers/api.md5.9 KiB
- references/email-workers/configuration.md2.7 KiB
- references/email-workers/gotchas.md3.0 KiB
- references/email-workers/patterns.md2.7 KiB
- references/hyperdrive/README.md2.8 KiB
- references/hyperdrive/api.md3.8 KiB
- references/hyperdrive/configuration.md3.8 KiB
- references/hyperdrive/gotchas.md3.8 KiB
- references/hyperdrive/patterns.md5.8 KiB
- references/images/README.md2.8 KiB
- references/images/api.md2.5 KiB
- references/images/configuration.md4.0 KiB
- references/images/gotchas.md2.4 KiB
- references/images/patterns.md3.5 KiB
- references/kv/README.md2.8 KiB
- references/kv/api.md4.2 KiB
- references/kv/configuration.md3.0 KiB
- references/kv/gotchas.md4.4 KiB
- references/kv/patterns.md4.6 KiB
- references/miniflare/README.md2.9 KiB
- references/miniflare/api.md4.5 KiB
- references/miniflare/configuration.md3.4 KiB
- references/miniflare/gotchas.md3.6 KiB
- references/miniflare/patterns.md4.2 KiB
- references/network-interconnect/README.md3.2 KiB
- references/network-interconnect/api.md5.5 KiB
- references/network-interconnect/configuration.md4.2 KiB
- references/network-interconnect/gotchas.md5.4 KiB
- references/network-interconnect/patterns.md3.9 KiB
- references/observability/README.md3.8 KiB
- references/observability/api.md3.4 KiB
- references/observability/configuration.md3.5 KiB
- references/observability/gotchas.md3.7 KiB
- references/observability/patterns.md2.4 KiB
- references/pages-functions/README.md3.2 KiB
- references/pages-functions/api.md4.6 KiB
- references/pages-functions/configuration.md2.9 KiB
- references/pages-functions/gotchas.md3.8 KiB
- references/pages-functions/patterns.md4.1 KiB
- references/pages/README.md2.8 KiB
- references/pages/api.md5.8 KiB
- references/pages/configuration.md5.7 KiB
- references/pages/gotchas.md7.8 KiB
- references/pages/patterns.md5.9 KiB
- references/pipelines/README.md3.3 KiB
- references/pipelines/api.md5.0 KiB
- references/pipelines/configuration.md2.7 KiB
- references/pipelines/gotchas.md2.4 KiB
- references/pipelines/patterns.md2.0 KiB
- references/pulumi/README.md3.2 KiB
- references/pulumi/api.md5.6 KiB
- references/pulumi/configuration.md5.5 KiB
- references/pulumi/gotchas.md6.4 KiB
- references/pulumi/patterns.md6.8 KiB
- references/queues/README.md3.0 KiB
- references/queues/api.md5.4 KiB
- references/queues/configuration.md3.7 KiB
- references/queues/gotchas.md7.1 KiB
- references/queues/patterns.md5.4 KiB
- references/r2-data-catalog/README.md6.9 KiB
- references/r2-data-catalog/api.md5.9 KiB
- references/r2-data-catalog/configuration.md5.2 KiB
- references/r2-data-catalog/gotchas.md6.0 KiB
- references/r2-data-catalog/patterns.md5.7 KiB
- references/r2-sql/README.md5.1 KiB
- references/r2-sql/api.md3.9 KiB
- references/r2-sql/configuration.md3.7 KiB
- references/r2-sql/gotchas.md6.1 KiB
- references/r2-sql/patterns.md6.6 KiB
- references/r2/README.md2.8 KiB
- references/r2/api.md5.5 KiB
- references/r2/configuration.md3.6 KiB
- references/r2/gotchas.md4.9 KiB
- references/r2/patterns.md5.7 KiB
- references/realtime-sfu/README.md3.0 KiB
- references/realtime-sfu/api.md3.7 KiB
- references/realtime-sfu/configuration.md3.4 KiB
- references/realtime-sfu/gotchas.md4.8 KiB
- references/realtime-sfu/patterns.md5.3 KiB
- references/realtimekit/README.md4.0 KiB
- references/realtimekit/api.md8.2 KiB
- references/realtimekit/configuration.md5.1 KiB
- references/realtimekit/gotchas.md6.7 KiB
- references/realtimekit/patterns.md7.5 KiB
- references/sandbox/README.md3.0 KiB
- references/sandbox/api.md4.9 KiB
- references/sandbox/configuration.md3.3 KiB
- references/sandbox/gotchas.md5.3 KiB
- references/sandbox/patterns.md5.1 KiB
- references/secrets-store/README.md2.2 KiB
- references/secrets-store/api.md4.3 KiB
- references/secrets-store/configuration.md3.8 KiB
- references/secrets-store/gotchas.md3.7 KiB
- references/secrets-store/patterns.md5.5 KiB
- references/smart-placement/README.md4.9 KiB
- references/smart-placement/api.md5.4 KiB
- references/smart-placement/configuration.md6.0 KiB
- references/smart-placement/gotchas.md5.5 KiB
- references/smart-placement/patterns.md5.6 KiB
- references/snippets/README.md3.1 KiB
- references/snippets/api.md5.0 KiB
- references/snippets/configuration.md6.2 KiB
- references/snippets/gotchas.md2.2 KiB
- references/snippets/patterns.md3.3 KiB
- references/spectrum/README.md2.3 KiB
- references/spectrum/api.md4.8 KiB
- references/spectrum/configuration.md4.2 KiB
- references/spectrum/gotchas.md3.7 KiB
- references/spectrum/patterns.md4.7 KiB
- references/static-assets/README.md2.1 KiB
- references/static-assets/api.md4.3 KiB
- references/static-assets/configuration.md4.7 KiB
- references/static-assets/gotchas.md4.0 KiB
- references/static-assets/patterns.md4.8 KiB
- references/stream/README.md3.8 KiB
- references/stream/api-live.md5.1 KiB
- references/stream/api.md5.1 KiB
- references/stream/configuration.md3.1 KiB
- references/stream/gotchas.md4.2 KiB
- references/stream/patterns.md6.2 KiB
- references/tail-workers/README.md2.9 KiB
- references/tail-workers/api.md5.0 KiB
- references/tail-workers/configuration.md3.4 KiB
- references/tail-workers/gotchas.md4.5 KiB
- references/tail-workers/patterns.md3.9 KiB
- references/terraform/README.md3.6 KiB
- references/terraform/api.md3.9 KiB
- references/terraform/configuration.md7.4 KiB
- references/terraform/gotchas.md5.1 KiB
- references/terraform/patterns.md6.5 KiB
- references/tunnel/README.md3.7 KiB
- references/tunnel/api.md4.3 KiB
- references/tunnel/configuration.md3.6 KiB
- references/tunnel/gotchas.md3.8 KiB
- references/tunnel/networking.md3.9 KiB
- references/tunnel/patterns.md3.8 KiB
- references/turn/README.md3.6 KiB
- references/turn/api.md5.1 KiB
- references/turn/configuration.md4.1 KiB
- references/turn/gotchas.md6.9 KiB
- references/turn/patterns.md6.0 KiB
- references/turnstile/README.md3.5 KiB
- references/turnstile/api.md6.3 KiB
- references/turnstile/configuration.md6.6 KiB
- references/turnstile/gotchas.md6.1 KiB
- references/turnstile/patterns.md4.6 KiB
- references/vectorize/README.md4.2 KiB
- references/vectorize/api.md2.3 KiB
- references/vectorize/configuration.md1.9 KiB
- references/vectorize/gotchas.md2.1 KiB
- references/vectorize/patterns.md2.5 KiB
- references/waf/README.md3.4 KiB
- references/waf/api.md5.7 KiB
- references/waf/configuration.md4.7 KiB
- references/waf/gotchas.md6.1 KiB
- references/waf/patterns.md5.2 KiB
- references/web-analytics/README.md5.1 KiB
- references/web-analytics/configuration.md2.0 KiB
- references/web-analytics/gotchas.md2.0 KiB
- references/web-analytics/integration.md1.7 KiB
- references/web-analytics/patterns.md2.2 KiB
- references/workerd/README.md2.7 KiB
- references/workerd/api.md4.8 KiB
- references/workerd/configuration.md5.1 KiB
- references/workerd/gotchas.md4.7 KiB
- references/workerd/patterns.md4.8 KiB
- references/workers-ai/README.md5.9 KiB
- references/workers-ai/api.md2.7 KiB
- references/workers-ai/configuration.md1.9 KiB
- references/workers-ai/gotchas.md2.6 KiB
- references/workers-ai/patterns.md3.0 KiB
- references/workers-for-platforms/README.md3.8 KiB
- references/workers-for-platforms/api.md5.4 KiB
- references/workers-for-platforms/configuration.md3.8 KiB
- references/workers-for-platforms/gotchas.md5.3 KiB
- references/workers-for-platforms/patterns.md5.5 KiB
- references/workers-playground/README.md3.9 KiB
- references/workers-playground/api.md2.2 KiB
- references/workers-playground/configuration.md4.4 KiB
- references/workers-playground/gotchas.md2.0 KiB
- references/workers-playground/patterns.md3.2 KiB
- references/workers-vpc/README.md5.4 KiB
- references/workers-vpc/api.md5.2 KiB
- references/workers-vpc/configuration.md3.8 KiB
- references/workers-vpc/gotchas.md4.4 KiB
- references/workers-vpc/patterns.md5.9 KiB
- references/workers/README.md3.4 KiB
- references/workers/api.md5.0 KiB
- references/workers/configuration.md4.3 KiB
- references/workers/frameworks.md4.2 KiB
- references/workers/gotchas.md4.6 KiB
- references/workers/patterns.md5.3 KiB
- references/workflows/README.md2.4 KiB
- references/workflows/api.md6.3 KiB
- references/workflows/configuration.md3.6 KiB
- references/workflows/gotchas.md4.5 KiB
- references/workflows/patterns.md6.5 KiB
- references/wrangler/README.md4.6 KiB
- references/wrangler/api.md4.5 KiB
- references/wrangler/auth.md2.1 KiB
- references/wrangler/configuration.md4.6 KiB
- references/wrangler/gotchas.md5.7 KiB
- references/wrangler/patterns.md4.8 KiB
- references/zaraz/IMPLEMENTATION_SUMMARY.md3.4 KiB
- references/zaraz/README.md3.8 KiB
- references/zaraz/api.md3.1 KiB
- references/zaraz/configuration.md1.8 KiB
- references/zaraz/gotchas.md2.0 KiB
- references/zaraz/patterns.md2.1 KiB
references/d1/patterns.md
D1 Patterns & Best Practices
Pagination
async function getUsers({ page, pageSize }: { page: number; pageSize: number }, env: Env) {
const offset = (page - 1) * pageSize;
const [countResult, dataResult] = await env.DB.batch([
env.DB.prepare('SELECT COUNT(*) as total FROM users'),
env.DB.prepare('SELECT * FROM users ORDER BY created_at DESC LIMIT ? OFFSET ?').bind(pageSize, offset)
]);
return { data: dataResult.results, total: countResult.results[0].total, page, pageSize, totalPages: Math.ceil(countResult.results[0].total / pageSize) };
}Conditional Queries
async function searchUsers(filters: { name?: string; email?: string; active?: boolean }, env: Env) {
const conditions: string[] = [], params: (string | number | boolean | null)[] = [];
if (filters.name) { conditions.push('name LIKE ?'); params.push(`%${filters.name}%`); }
if (filters.email) { conditions.push('email = ?'); params.push(filters.email); }
if (filters.active !== undefined) { conditions.push('active = ?'); params.push(filters.active ? 1 : 0); }
const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
return await env.DB.prepare(`SELECT * FROM users ${whereClause}`).bind(...params).all();
}Bulk Insert
async function bulkInsertUsers(users: Array<{ name: string; email: string }>, env: Env) {
const stmt = env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)');
const batch = users.map(user => stmt.bind(user.name, user.email));
return await env.DB.batch(batch);
}Caching with KV
async function getCachedUser(userId: number, env: { DB: D1Database; CACHE: KVNamespace }) {
const cacheKey = `user:${userId}`;
const cached = await env.CACHE?.get(cacheKey, 'json');
if (cached) return cached;
const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
if (user) await env.CACHE?.put(cacheKey, JSON.stringify(user), { expirationTtl: 300 });
return user;
}Query Optimization
// ✅ Use indexes in WHERE clauses
const users = await env.DB.prepare('SELECT * FROM users WHERE email = ?').bind(email).all();
// ✅ Limit result sets
const recentPosts = await env.DB.prepare('SELECT * FROM posts ORDER BY created_at DESC LIMIT 100').all();
// ✅ Use batch() for multiple independent queries
const [user, posts, comments] = await env.DB.batch([
env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId),
env.DB.prepare('SELECT * FROM posts WHERE user_id = ?').bind(userId),
env.DB.prepare('SELECT * FROM comments WHERE user_id = ?').bind(userId)
]);
// ❌ Avoid N+1 queries
for (const post of posts) {
const author = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(post.user_id).first(); // Bad: multiple round trips
}
// ✅ Use JOINs instead
const postsWithAuthors = await env.DB.prepare(`
SELECT posts.*, users.name as author_name
FROM posts
JOIN users ON posts.user_id = users.id
`).all();Multi-Tenant SaaS
// Each tenant gets own database
export default {
async fetch(request: Request, env: { [key: `TENANT_${string}`]: D1Database }) {
const tenantId = request.headers.get('X-Tenant-ID');
const data = await env[`TENANT_${tenantId}`].prepare('SELECT * FROM records').all();
return Response.json(data.results);
}
}Session Storage
async function createSession(userId: number, token: string, env: Env) {
const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();
return await env.DB.prepare('INSERT INTO sessions (user_id, token, expires_at) VALUES (?, ?, ?)').bind(userId, token, expiresAt).run();
}
async function validateSession(token: string, env: Env) {
return await env.DB.prepare('SELECT s.*, u.email FROM sessions s JOIN users u ON s.user_id = u.id WHERE s.token = ? AND s.expires_at > CURRENT_TIMESTAMP').bind(token).first();
}Analytics/Events
async function logEvent(event: { type: string; userId?: number; metadata: object }, env: Env) {
return await env.DB.prepare('INSERT INTO events (type, user_id, metadata) VALUES (?, ?, ?)').bind(event.type, event.userId || null, JSON.stringify(event.metadata)).run();
}
async function getEventStats(startDate: string, endDate: string, env: Env) {
return await env.DB.prepare('SELECT type, COUNT(*) as count FROM events WHERE timestamp BETWEEN ? AND ? GROUP BY type ORDER BY count DESC').bind(startDate, endDate).all();
}Read Replication Pattern (Paid Plans)
interface Env { DB: D1Database; DB_REPLICA: D1Database; }
export default {
async fetch(request: Request, env: Env) {
if (request.method === 'GET') {
// Reads: use replica for lower latency
const users = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE active = 1').all();
return Response.json(users.results);
}
if (request.method === 'POST') {
const { name, email } = await request.json();
const result = await env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)').bind(name, email).run();
// Read-after-write: use primary for consistency (replication lag <100ms-2s)
const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(result.meta.last_row_id).first();
return Response.json(user, { status: 201 });
}
}
}Use replicas for: Analytics dashboards, search results, public queries (eventual consistency OK)
Use primary for: Read-after-write, financial transactions, authentication (consistency required)
Sessions API Pattern (Paid Plans)
// Migration with long-running session (up to 15 min)
async function runMigration(env: Env) {
const session = env.DB.withSession({ timeout: 600 }); // 10 min
try {
await session.prepare('CREATE INDEX idx_users_email ON users(email)').run();
await session.prepare('CREATE INDEX idx_posts_user ON posts(user_id)').run();
await session.prepare('ANALYZE').run();
} finally {
session.close(); // Always close to prevent leaks
}
}
// Bulk transformation with batching
async function transformLargeDataset(env: Env) {
const session = env.DB.withSession({ timeout: 900 }); // 15 min max
try {
const BATCH_SIZE = 1000;
let offset = 0;
while (true) {
const rows = await session.prepare('SELECT id, data FROM legacy LIMIT ? OFFSET ?').bind(BATCH_SIZE, offset).all();
if (rows.results.length === 0) break;
const updates = rows.results.map(row =>
session.prepare('UPDATE legacy SET new_data = ? WHERE id = ?').bind(transform(row.data), row.id)
);
await session.batch(updates);
offset += BATCH_SIZE;
}
} finally { session.close(); }
}Time Travel & Backups
wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z" # Point-in-time
wrangler d1 time-travel info <db-name> # List restore points (7 days free, 30 days paid)
wrangler d1 export <db-name> --remote --output=./backup.sql # Full export
wrangler d1 export <db-name> --remote --no-schema --output=./data.sql # Data only
wrangler d1 execute <db-name> --remote --file=./backup.sql # ImportRequirements and compatibility
Written for: OpenAI Codex
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs Node.js
Security
What our scanner noticed· Medium risk
- Possible data-exfiltration endpoints
- Instructions that use the network
- Downloads piped into a shell
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- OpenAI
- Publisher
- OpenAI (Official)
- Source
- openai/skills · skills/.curated/cloudflare-deploy · commit 49f948f
- Licence
- Apache License 2.0 (redistribution allowed)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by OpenAI.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cloudflare-deploy.zip