D1 SQL Playground

Run safe, read-only SELECT queries against a seeded Cloudflare D1 database. Returns JSON rows, inferred column metadata, and query timing.

FeaturesCopy Anchor Link

• POST /query - Execute a validated SELECT and receive rows plus column types
• Seeded schema - products catalog and experiments table from this repo
• Read-only guardrails - Rejects writes, DDL, semicolons, comments, UNION, and disallowed tables
• GET / - Lists queryable tables

API ReferenceCopy Anchor Link

POST /queryCopy Anchor Link

Execute a single read-only SELECT against the seeded database.

Example RequestCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/query" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT name, price FROM products WHERE in_stock = 1 ORDER BY price DESC LIMIT 5"}'

Success ResponseCopy Anchor Link

{
  "columns": [
    { "name": "name", "type": "text" },
    { "name": "price", "type": "number" }
  ],
  "rows": [
    { "name": "Browser Rendering Frame", "price": 59.99 },
    { "name": "Workers AI Prompt Pack", "price": 49.99 }
  ],
  "rowCount": 2,
  "durationMs": 3
}

Error CodesCopy Anchor Link

• 400 - Invalid JSON (INVALID_BODY) or disallowed SQL (INVALID_SQL)
• 502 - D1 execution error (QUERY_ERROR)

GET /Copy Anchor Link

Returns app metadata and the list of allowed tables (products, experiments).

Seeded TablesCopy Anchor Link

Example queries:

SELECT category, COUNT(*) AS total FROM products GROUP BY category
SELECT slug, name FROM experiments WHERE category = 'Storage & Data'
SELECT p.name, e.name FROM products p JOIN experiments e ON p.category LIKE '%' || e.category || '%' LIMIT 5

Use CasesCopy Anchor Link

• Learn D1 query patterns without provisioning your own schema
• Prototype read-only analytics APIs over SQLite at the edge
• Teach SQL safely with guardrails against writes and injection
• Explore JOINs and aggregations on realistic sample data

LimitationsCopy Anchor Link

• Read-only: INSERT, UPDATE, DELETE, DDL, and UNION are rejected
• Only products and experiments tables are queryable
• Column types are inferred from the first result row (empty results return no column metadata)
• Requires D1 migrations before first use (local and remote)

Use in your projectCopy Anchor Link

import type { ColumnMeta, QueryResponse } from "../types/query";import { inferColumnType } from "./sql";export async function runSelectQuery(db: D1Database, sql: string): Promise<QueryResponse> {  const started = Date.now();  const result = await db.prepare(sql).all<Record<string, unknown>>();  const rows = result.results ?? [];  return {    columns: buildColumnMetadata(rows),    rows,    rowCount: rows.length,    durationMs: Date.now() - started,  };}function buildColumnMetadata(rows: Record<string, unknown>[]): ColumnMeta[] {  if (rows.length === 0) {    return [];  }  return Object.keys(rows[0]).map((name) => ({    name,    type: inferColumnType(rows[0][name]),  }));}

DeploymentCopy Anchor Link

npm run db:migrate

curl -X POST "https://your-worker.workers.dev/query" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM products LIMIT 3"}'

Local DevelopmentCopy Anchor Link

cd apps/experiments/d1-sql-playground
npm install
npm run db:migrate:local
npm run dev

Test locally:

curl -X POST "http://localhost:8787/query" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM experiments LIMIT 5"}'

ConfigurationCopy Anchor Link

Migrations live in migrations/0000_init.sql. Apply with npm run db:migrate:local (dev) or npm run db:migrate (remote).

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• D1 - SQLite database at the edge with seeded read-only playground data