Skip to content

D1 Operations

Purpose

Inspecting and, when genuinely necessary, mutating the production D1 database - with the blast radius of each command made explicit.

Architecture/context

Single production database, akshaya-group-global, shared by the API Worker and three app Workers (Corporate, Software, Admin) - see Cloudflare → D1 for the full binding picture and Architecture → Data Platform for the schema.

Safe read commands

npx wrangler d1 execute akshaya-group-global --remote \
  --command "SELECT COUNT(*) FROM freelancer_profiles;" \
  --config workers/api/wrangler.jsonc                                    # [REMOTE, READ-ONLY: SELECT only]

npx wrangler d1 migrations list akshaya-group-global --remote \
  --config workers/api/wrangler.jsonc                                    # [REMOTE, READ-ONLY]
Any SELECT is safe to run against --remote - it still counts as a remote network call against production infrastructure, but changes no data.

Mutating commands - require explicit justification

npx wrangler d1 migrations apply akshaya-group-global --remote \
  --config workers/api/wrangler.jsonc                                    # [REMOTE / MUTATING]

npx wrangler d1 execute akshaya-group-global --remote \
  --command "UPDATE ... " --config workers/api/wrangler.jsonc            # [REMOTE / MUTATING]
Both deploy workflows already run the migrations-apply command automatically as part of a normal deploy (see CI/CD → Deployment) - running it by hand is only needed outside that flow (e.g., re-syncing after a manual bootstrap step).

A hand-written UPDATE/DELETE against --remote should be treated the same as a production database change in any other system: understand exactly which rows it affects, have a SELECT first to confirm the row set, and know there is no automated backup to restore from if it's wrong (see below).

Backup / recovery

No automated D1 backup exists in this repository - verified by inspecting scripts/ in full; no export/backup script is present. docs/DEPLOYMENT.md does not describe one either. If you need a point-in-time export before a risky manual change:

npx wrangler d1 export akshaya-group-global --remote --output backup-$(date +%Y%m%d).sql \
  --config workers/api/wrangler.jsonc                                    # [REMOTE, READ-ONLY]
This is a manual, ad-hoc step - not automated anywhere in CI. Store the resulting file outside the repository (never commit a database export).

Troubleshooting

Symptom Check
database not found database_id mismatch - see Cloudflare → Troubleshooting
Migration reports already-applied objects wrangler d1 migrations list --remote before applying again
A query returns unexpected empty results Confirm you're on --remote, not accidentally --local (opposite is also possible - always specify explicitly)

Rollback/recovery

No automated migration rollback - migrations in this repository are additive by convention (see Deployment → Release Checklist). Reversing a bad migration means writing and applying a new, corrective migration - not un-applying the old one.

Security considerations

--remote D1 commands use the same CLOUDFLARE_API_TOKEN as any deploy - see Infrastructure → Security.