task-pigeon/docs/cloudflare-d1.md

Small SQLite task queue CLI for people and coding agents.

# Cloudflare D1 Remote

Pigeon uses Bun SQLite locally by default. Use the D1 Worker only when several
computers need one shared board and running `pigeon serve` next to a SQLite file
is not practical.

The Worker exposes Pigeon's fixed RPC operations. Clients never receive direct
SQL access and cannot select arbitrary database files. The Worker owns Drizzle,
the D1 binding, and the database migrations.

## Deploy

Create a small deployment directory and install Pigeon there:

```sh
mkdir pigeon-d1
cd pigeon-d1
bun add task-pigeon
cp node_modules/task-pigeon/dist/pigeon-d1.wrangler.example.jsonc wrangler.jsonc
bunx wrangler d1 create pigeon
```

Copy the `database_id` printed by Wrangler into `wrangler.jsonc`. The template
already points `main` and `migrations_dir` at the installed package.

Apply Pigeon's migrations, set a token, then deploy:

```sh
bunx wrangler d1 migrations apply PIGEON_DB --remote
bunx wrangler secret put PIGEON_TOKEN
bunx wrangler deploy
```

Wrangler prints the Worker URL. Configure every Pigeon client to use that URL:

```sh
pigeon config \
  --remote-url https://pigeon-d1.<your-subdomain>.workers.dev \
  --remote-token <the-token-you-set>
pigeon status
pigeon monitor --by andrew
```

`PIGEON_TOKEN` is optional in the Worker runtime, but it should be configured
for every internet-reachable deployment. Treat it like a shared private-board
secret.

## Updates

When updating Pigeon, update the Worker dependency, apply any new migrations,
then deploy the bundled Worker again:

```sh
bun update task-pigeon
bunx wrangler d1 migrations apply PIGEON_DB --remote
bunx wrangler deploy
```

The client and server use a versioned RPC envelope. If a client reports a
protocol mismatch, update and redeploy the Worker before retrying.

## Scope

This is one shared SQLite-compatible database, not a local-replica or sync
system. Local snapshots and `pigeon db` tools continue to operate on the local
Bun SQLite database. Set `PIGEON_LOCAL_ONLY=1` when you intentionally need a
local-only command while a remote URL is configured.

Use `pigeon serve` over a private network when you already have one always-on
machine with the SQLite file. It remains the lower-operations remote option.