Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
secondsky avatar

Cloudflare D1

secondsky/claude-skills

  • 283 installs
  • 202 repo stars
  • Updated August 4, 2026
  • secondsky/claude-skills

Use cloudflare-d1 for development tasks

About

cloudflare-d1: A skill for development. This provides functionality for development workflows.

  • cloudflare-d1

Cloudflare D1 by the numbers

  • 283 all-time installs (skills.sh)
  • +17 installs in the week ending Aug 5, 2026 (Skillselion tracking)
  • Ranked #1,392 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/secondsky/claude-skills --skill cloudflare-d1

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs283
repo stars★ 202
Last updatedAugust 4, 2026
Repositorysecondsky/claude-skills ↗

What it does

Use cloudflare-d1 for development tasks

Files

SKILL.mdMarkdownGitHub ↗

Cloudflare D1 Database

Status: Production Ready ✅ | Last Verified: 2025-01-15

Table of Contents

1. What Is D1? 2. Quick Start 3. Critical Rules 4. D1 API Methods 5. Top 5 Use Cases 6. Migrations Best Practices 7. Common Patterns 8. SQLite Type Affinity 9. Top 5 Errors Prevented

---

What Is D1?

Cloudflare D1 is serverless SQLite on the edge:

  • SQL database without servers
  • Global distribution
  • Zero cold starts
  • Standard SQLite syntax
  • Read replication for global performance

---

🆕 New in 2025

D1 received major updates throughout 2025:

Performance (January 2025)

  • 40-60% latency reduction globally (P50 query times)
  • Optimized SQLite engine for edge execution
  • Reduced cold start impact for databases <100 MB

Reliability (September 2025)

  • Automatic query retries: Read queries retry up to 2x on transient failures
  • Transparent to application code (logged in wrangler tail)

Scalability (April 2025)

  • Read Replication (Public Beta): Deploy read replicas globally
  • Up to 2x read throughput for read-heavy workloads
  • Sessions API for read-write separation

Compliance (November 2025)

  • Data Localization: Specify EU/US jurisdiction for GDPR/data sovereignty
  • Configure via --jurisdiction flag or wrangler.jsonc

⚠️ Breaking Change (February 10, 2025)

  • Free tier hard limits enforced: 10 DBs, 500 MB each, 50 queries/invocation
  • Exceeding limits = 429 errors (previously warnings only)
  • Action: Review usage with wrangler d1 list and upgrade if needed

Full details: Load references/2025-features.md

---

Quick Start (5 Minutes)

1. Create Database

bunx wrangler d1 create my-database

Save the database_id from output!

2. Configure Binding

Add to wrangler.jsonc:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "d1_databases": [
    {
      "binding": "DB",                    // env.DB
      "database_name": "my-database",
      "database_id": "<UUID>",
      "preview_database_id": "local-db"
    }
  ]
}

3. Create Migration

bunx wrangler d1 migrations create my-database create_users

Edit migrations/0001_create_users.sql:

CREATE TABLE IF NOT EXISTS users (
  user_id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT NOT NULL UNIQUE,
  username TEXT NOT NULL,
  created_at INTEGER NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);

PRAGMA optimize;

4. Apply Migration

# Local
bunx wrangler d1 migrations apply my-database --local

# Production
bunx wrangler d1 migrations apply my-database --remote

5. Query from Worker

import { Hono } from 'hono';

type Bindings = {
  DB: D1Database;
};

const app = new Hono<{ Bindings: Bindings }>();

app.get('/users/:email', async (c) => {
  const { results } = await c.env.DB.prepare(
    'SELECT * FROM users WHERE email = ?'
  )
    .bind(c.req.param('email'))
    .all();

  return c.json(results);
});

export default app;

Load `references/setup-guide.md` for complete walkthrough.

---

Critical Rules

Always Do ✅

1. Use prepared statements with .bind() (never string concatenation) 2. Create indexes for WHERE/JOIN/ORDER BY columns 3. Use migrations for schema changes (never manual SQL) 4. Batch queries for multiple operations (.batch()) 5. Run PRAGMA optimize after schema changes 6. Handle errors explicitly (try/catch) 7. Use INTEGER for timestamps (Date.now()) 8. Test locally before deploying migrations 9. Use read replicas for global read performance 10. Validate input before SQL queries

Never Do ❌

1. Never concatenate user input into SQL 2. Never commit database_id to public repos 3. Never skip migrations for schema changes 4. Never use VARCHAR (use TEXT instead) 5. Never skip indexes for filtered columns 6. Never ignore SQLite type affinity rules 7. Never use SELECT without LIMIT 8. Never run migrations without testing locally 9. Never exceed 1MB per row 10. Never use DATETIME* (use INTEGER for timestamps)

---

D1 API Methods

prepare() - Execute Queries

// Single result
const { results } = await env.DB.prepare(
  'SELECT * FROM users WHERE email = ?'
)
  .bind(email)
  .all();

// First result only
const user = await env.DB.prepare(
  'SELECT * FROM users WHERE user_id = ?'
)
  .bind(userId)
  .first();

// Raw results (faster)
const { results } = await env.DB.prepare(
  'SELECT username FROM users'
)
  .raw();  // Returns arrays instead of objects

batch() - Multiple Queries

const results = await env.DB.batch([
  env.DB.prepare('INSERT INTO users (email, username, created_at) VALUES (?, ?, ?)')
    .bind('user1@example.com', 'user1', Date.now()),
  env.DB.prepare('INSERT INTO users (email, username, created_at) VALUES (?, ?, ?)')
    .bind('user2@example.com', 'user2', Date.now()),
  env.DB.prepare('SELECT COUNT(*) as count FROM users')
]);

console.log('Users count:', results[2].results[0].count);

All queries execute in single transaction (all succeed or all fail).

exec() - Run SQL String

// For migrations/setup only
await env.DB.exec(`
  CREATE TABLE IF NOT EXISTS users (
    user_id INTEGER PRIMARY KEY,
    email TEXT NOT NULL
  );
  CREATE INDEX idx_email ON users(email);
`);

NEVER use for queries with user input!

Load `references/query-patterns.md` for complete API reference.

---

Top 5 Use Cases

Use Case 1: User CRUD

// Create
app.post('/users', async (c) => {
  const { email, username } = await c.req.json();

  const { results } = await c.env.DB.prepare(
    'INSERT INTO users (email, username, created_at) VALUES (?, ?, ?) RETURNING *'
  )
    .bind(email, username, Date.now())
    .all();

  return c.json(results[0]);
});

// Read
app.get('/users/:id', async (c) => {
  const user = await c.env.DB.prepare(
    'SELECT * FROM users WHERE user_id = ?'
  )
    .bind(c.req.param('id'))
    .first();

  if (!user) {
    return c.json({ error: 'Not found' }, 404);
  }

  return c.json(user);
});

// Update
app.patch('/users/:id', async (c) => {
  const { username } = await c.req.json();

  await c.env.DB.prepare(
    'UPDATE users SET username = ?, updated_at = ? WHERE user_id = ?'
  )
    .bind(username, Date.now(), c.req.param('id'))
    .run();

  return c.json({ success: true });
});

// Delete
app.delete('/users/:id', async (c) => {
  await c.env.DB.prepare(
    'DELETE FROM users WHERE user_id = ?'
  )
    .bind(c.req.param('id'))
    .run();

  return c.json({ success: true });
});

Use Case 2: Batch Operations

app.post('/users/bulk', async (c) => {
  const users = await c.req.json();  // Array of users

  const statements = users.map(user =>
    c.env.DB.prepare(
      'INSERT INTO users (email, username, created_at) VALUES (?, ?, ?)'
    ).bind(user.email, user.username, Date.now())
  );

  const results = await c.env.DB.batch(statements);

  return c.json({ inserted: results.length });
});

Use Case 3: Read Replication (Global Reads)

// Configure read replica (any region)
const session = c.env.DB.withSession({
  preferredRegion: 'auto'  // or 'weur', 'wnam', 'enam', 'apac'
});

// Read from nearest replica
const { results } = await session.prepare(
  'SELECT * FROM users WHERE email = ?'
)
  .bind(email)
  .all();

// Check which region served request
console.log('Served by:', results[0].served_by_region);

Load `references/read-replication.md` for complete guide.

Use Case 4: Transactions with Batch

// Transfer credits between users (atomic)
const results = await c.env.DB.batch([
  c.env.DB.prepare(
    'UPDATE users SET credits = credits - ? WHERE user_id = ?'
  ).bind(amount, fromUserId),
  c.env.DB.prepare(
    'UPDATE users SET credits = credits + ? WHERE user_id = ?'
  ).bind(amount, toUserId),
  c.env.DB.prepare(
    'INSERT INTO transactions (from_user, to_user, amount, created_at) VALUES (?, ?, ?, ?)'
  ).bind(fromUserId, toUserId, amount, Date.now())
]);

// All succeed or all fail (transaction)

Use Case 5: Pagination

app.get('/users', async (c) => {
  const page = parseInt(c.req.query('page') || '1');
  const limit = 20;
  const offset = (page - 1) * limit;

  const { results } = await c.env.DB.prepare(
    'SELECT * FROM users ORDER BY created_at DESC LIMIT ? OFFSET ?'
  )
    .bind(limit, offset)
    .all();

  return c.json({
    users: results,
    page,
    limit
  });
});

---

Migrations Best Practices

1. Always Use Migrations

bunx wrangler d1 migrations create my-database add_users_avatar

2. Make Migrations Idempotent

-- ✅ GOOD: Idempotent
CREATE TABLE IF NOT EXISTS users (...);
CREATE INDEX IF NOT EXISTS idx_email ON users(email);
DROP TABLE IF EXISTS old_table;

-- ❌ BAD: Fails on re-run
CREATE TABLE users (...);
CREATE INDEX idx_email ON users(email);

3. Test Locally First

bunx wrangler d1 migrations apply my-database --local
bunx wrangler d1 execute my-database --local --command "SELECT * FROM users"

4. Add PRAGMA optimize

-- End of migration
PRAGMA optimize;

Load `templates/schema-example.sql` for complete schema template.

---

When to Load References

Load references/setup-guide.md when:

  • First-time D1 setup
  • Creating first database
  • Configuring bindings
  • Applying first migration

Load references/query-patterns.md when:

  • Need complete API reference
  • Complex query patterns
  • Batch operations
  • Error handling

Load references/read-replication.md when:

  • Setting up global reads
  • Need low latency worldwide
  • Understanding Sessions API
  • Sequential consistency required

Load references/best-practices.md when:

  • Optimizing query performance
  • Schema design decisions
  • Index strategies
  • Production deployment checklist

Load references/limits.md when:

  • Encountering 429 errors or quota warnings
  • Planning capacity for free vs paid tiers
  • Understanding database/query limits
  • Migrating to paid plan

Load references/metrics-analytics.md when:

  • Investigating performance issues
  • Setting up monitoring and alerts
  • Using wrangler d1 insights command
  • Analyzing query efficiency

Load references/2025-features.md when:

  • Upgrading from v2.x to v3.x
  • Enabling new features (auto-retry, jurisdiction, replication)
  • Understanding breaking changes (Feb 10, 2025 enforcement)
  • Migrating before deadlines

Interactive Tools

Agents (Autonomous diagnostics):

  • `agents/d1-debugger.md`: 9-phase diagnostic (config, migrations, queries, bindings, errors, limits, performance, Time Travel)
  • `agents/d1-query-optimizer.md`: Performance analysis (slow queries, missing indexes, optimization recommendations)

Commands (Interactive wizards):

  • `commands/cloudflare-d1:setup.md`: Interactive first-time setup wizard
  • `commands/d1-create-migration.md`: Guided migration creation with validation

---

Using Bundled Resources

References (references/)

  • setup-guide.md - Complete setup walkthrough
  • query-patterns.md - Complete API reference with examples
  • read-replication.md - Global read replicas setup
  • best-practices.md - Performance and optimization

Templates (templates/)

  • schema-example.sql - Complete schema with indexes
  • d1-worker-queries.ts - All query patterns in Workers
  • cloudflare-d1:setup-migration.sh - Complete setup script

---

Common Patterns

Error Handling

try {
  const { results } = await env.DB.prepare(
    'SELECT * FROM users WHERE email = ?'
  )
    .bind(email)
    .all();

  return c.json(results);
} catch (error) {
  console.error('D1 Error:', error);
  return c.json({ error: 'Database error' }, 500);
}

Raw Mode (Performance)

// Returns arrays instead of objects (faster)
const { results } = await env.DB.prepare(
  'SELECT user_id, email FROM users'
)
  .raw();

// results = [[1, 'user1@example.com'], [2, 'user2@example.com']]

COUNT Queries

const count = await env.DB.prepare(
  'SELECT COUNT(*) as count FROM users'
)
  .first('count');  // Get single column value

console.log('Total users:', count);

---

SQLite Type Affinity

D1 uses SQLite type affinity:

Declared TypeAffinity
INTEGER, INTINTEGER
TEXT, VARCHAR, CHARTEXT
REAL, FLOAT, DOUBLEREAL
BLOBBLOB
(no type)BLOB

Best practices:

  • Use INTEGER for numbers
  • Use TEXT for strings (not VARCHAR)
  • Use INTEGER for timestamps (Date.now())
  • Use BLOB for binary data

---

Top 5 Errors Prevented

1. SQL Injection: Use .bind(), never string concatenation 2. Missing Indexes: Create indexes for WHERE/JOIN columns 3. Migration Failures: Test locally first 4. Type Confusion: Use INTEGER for timestamps 5. Batch Size: Limit batch to <500 statements

Load `references/best-practices.md` for complete error prevention.

---

Secure Installation

When installing D1 driver packages, follow supply chain security best practices:

  • Block post-install scripts — npm config set ignore-scripts true (or Bun: disabled by default)
  • Cooldown period — Wait 7 days for new package versions to be vetted by the community
  • Audit before installing — Run socket package score npm <pkg> or use socket npm install <pkg> to check packages

Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

Official Documentation

  • D1 Overview: https://developers.cloudflare.com/d1/
  • Get Started: https://developers.cloudflare.com/d1/get-started/
  • Client API: https://developers.cloudflare.com/d1/build-with-d1/d1-client-api/
  • Read Replication: https://developers.cloudflare.com/d1/reference/read-replication/

---

Questions? Issues?

1. Check references/setup-guide.md for setup 2. Review references/query-patterns.md for API reference 3. See references/read-replication.md for global reads 4. Load references/best-practices.md for optimization

Related skills

open.feishu.cnLark Openapi ExplorerInstantly explore, test, and generate calls against the full Lark (Feishu) OpenAPI surface without leaving their agent workflow.493klarksuiteLark EventConsume real-time events from Lark/Feishu as structured NDJSON streams inside AI agent workflows.387k16klarksuiteLark Openapi ExplorerWhen an existing Lark/Feishu skill or CLI command cannot fulfill a specific requirement and they need to discover and invoke the exact native OpenAPI endpoint.386k16kscrapegraphaiJust ScrapeQuickly search, crawl, extract structured JSON, or monitor web pages without writing custom scraping code.245k41larksuiteLark AppsQuery the current visibility and permission scope of a Lark (Feishu) app without writing HTTP client code.235k16kmattpocockDesign An InterfaceGenerate multiple radically different interface or API designs in parallel before committing to one.188k198k
Backend & APIsbackendintegrations
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.