> Cloudflare D1: what your AI agent should know — from The Handover, the-handover.org/services/cloudflare-d1
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

# Cloudflare D1

What we tell an AI agent working on a project that uses Cloudflare D1: 1 rule, 0 learned the hard way.

Build a full rootnote set for a Cloudflare D1 project: https://the-handover.org/build?areas=working-agreement,database&database=d1

The vendor's own file for agents (what Cloudflare D1 is, where its documentation lives): https://developers.cloudflare.com/llms.txt. This page covers where it catches agents out.

### D1: check whether a command targets local or remote before running it

> General guidance · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-19

- **Check whether each command targets the local or the remote database before
  running it.** The flag decides, and the two diverge without telling you — a
  migration that "worked" may have run only locally.
- **Apply schema changes through migrations, never ad-hoc execute commands**, so
  local and remote stay in step and the history says what ran where.

Also applies to every database choice, so not repeated here: An instruction is not a control: keep production out of the agent's reach, and check recovery yourself; Never run a migration or a write against production that has not run against a copy.