codewhale-hq/codewhale-plugin-marketplace/cloudflare-storage

Cloudflare KV, R2 and D1 basics

Local first: cf dev simulates the project's bindings through its adapter. Resource commands are remote unless a supported --local mode is explicitly selected. Consult cf cli search with an anonymous action/resource query and inspect the discovered command's help/schema; beta command names and flags are not interchangeable with Wrangler's. Remote writes require approval (cloudflare-deploy). Vite development data and cf local API data are separate stores; check the actual persistence directory before comparing results.

Pick the store by access pattern:

KV

Declare CACHE in worker.env with the current bindings.kv helper from cf/config, preserving the existing namespace ID. Validate typed options against the cf configuration reference and inspect dry-run bindings.

await env.CACHE.put("user:1", JSON.stringify(user), { expirationTtl: 3600 });
const user = await env.CACHE.get("user:1", "json"); // null when missing
const page = await env.CACHE.list({ prefix: "user:", limit: 100 });

• Writes can take a while (60 seconds or more) to be visible in other

locations; do not use KV where staleness is a bug.

• expirationTtl has a documented minimum of 60 seconds.
• Use cf cli search "create a key value namespace" or an equivalent

anonymous query, then inspect the returned help/schema. Namespace creation is remote and needs approval; local KV writes require explicit --local.

R2

Declare FILES with the current bindings.r2 helper in worker.env; retain the existing bucket identity and check generated bindings.

await env.FILES.put(key, request.body, { httpMetadata: { contentType: "image/png" } });
const obj = await env.FILES.get(key); // null when missing
if (!obj) return new Response("Not found", { status: 404 });
return new Response(obj.body, { headers: { etag: obj.httpEtag } });
// elsewhere: await env.FILES.delete(key);

• Stream request.body into put; do not buffer large uploads in memory.
• Validate keys from user input (no path tricks, enforce a prefix per user).
• Discover cf R2 bucket/object commands through anonymous command search;

creating a bucket or writing/deleting an object remotely requires approval.

D1

Declare DB using the current bindings.d1 helper in worker.env, keeping the existing database ID and generated environment types. Verify the helper's schema before adding migration options; do not copy legacy snake_case keys.

const { results } = await env.DB.prepare("SELECT id, email FROM users WHERE org = ?1 LIMIT ?2")
  .bind(orgId, 50)
  .all();
const row = await env.DB.prepare("SELECT * FROM users WHERE id = ?1").bind(id).first();
await env.DB.batch([
  env.DB.prepare("INSERT INTO audit(event) VALUES (?1)").bind("signup"),
  env.DB.prepare("UPDATE users SET active = 1 WHERE id = ?1").bind(id),
]);

• Always bind() user input; never concatenate it into SQL.
• Schema changes stay in reviewed, numbered SQL migration files. Keep the

framework's migration tool if it already owns ordering and receipts; inspect its generated SQL, apply it only to the local test store and run the tests.

• Discover cf D1 query/migration commands and exact input shape with anonymous

command search and help/schema. Never assume a Wrangler migration command exists in cf under the same name.

• Production application is a data change: show SQL, database and account,

get approval, and keep a restore plan. Prefer additive migrations. A DROP, table rebuild or unrestricted DELETE requires explicit data-loss approval. Check current D1 recovery/Time Travel availability rather than promising a retention window from memory. Always bind user values, even in CLI queries.

Checklist

• [ ] binding names are valid JS identifiers and match Env
• [ ] generated binding types and project type check current
• [ ] code handles null / missing results
• [ ] local test ran against simulated storage
• [ ] no remote write happened without a yes

References: cf local resources, typed bindings.