Build a link shortener with D1 and KV on Cloudflare

URL shorteners look trivial until you care about correctness under load: unique codes, fast redirects, analytics, and abuse controls. A proven Cloudflare pattern is:

• D1 as the source of truth for mappings
• KV as a hot cache for redirects
• A Worker that creates links and resolves them at the edge

The Link Shortener experiment implements that split so you can deploy a working shortener instead of reinventing the schema.

Cloudflare products in this patternCopy Anchor Link

Why D1 + KV togetherCopy Anchor Link

KV alone is awkward for “list my links” and uniqueness constraints. D1 alone is fine for low QPS, but KV shines when the same slug is hit constantly worldwide. Official primers: D1 get started, KV get started.

Request flowsCopy Anchor Link

CreateCopy Anchor Link

POST { url } → validate → insert D1 → optionally warm KV → return code

Use transactions / unique constraints in D1 so two creates cannot race the same custom code (D1 API).

ResolveCopy Anchor Link

GET /:code → KV get → on miss, D1 select → fill KV → 302 Location

Always validate destination URLs (http/https only) to avoid open redirects into dangerous schemes - same discipline as other catalog URL APIs.

Schema sketchCopy Anchor Link

Minimum viable tables:

• links(code PRIMARY KEY, url TEXT NOT NULL, created_at, expires_at, owner_id)
• Optional clicks(code, ts, colo, asn) or push clicks to Analytics Engine / Queues

Explore SQL interactively with D1 SQL Playground while you iterate. For simpler key/value notes without SQL, see KV Notes.

Abuse and product extrasCopy Anchor Link

• Rate-limit creates (Rate Limiter Demo, WAF rate limiting)
• Turnstile on public create forms (Turnstile Verify)
• Expiration columns in D1 + KV TTLs that match
• Custom codes with reservation rules
• Soft-delete vs hard-delete for audit trails
• Strongly consistent counters via Durable Counter patterns when KV increments are too lossy

Consistency notesCopy Anchor Link

KV is eventually consistent (KV consistency). After create:

• Warm KV immediately from the create path
• Accept that a redirect MISS may hit D1 briefly after write
• On update/delete, delete the KV key explicitly

D1 read replicas and latency characteristics are covered in D1 read replication - design list UIs accordingly.

Deploy Link ShortenerCopy Anchor Link

1. Provision D1 + KV (bindings)
2. Deploy Link Shortener
3. Create a link, resolve it twice, confirm cache behavior
4. Add Turnstile / auth before exposing create publicly
5. Add analytics when product metrics matter

You get a real two-storage edge pattern - not a toy in-memory map - that matches how many production Cloudflare apps actually split durability (D1) and speed (KV).

Production checklistCopy Anchor Link

1. Unique constraint on codes in D1.
2. Warm KV on create; delete KV keys on update/delete.
3. Validate destinations (http/https only).
4. Protect create with auth + Turnstile.
5. Align KV TTLs with link expiration columns.
6. Decide analytics path (D1 rows vs Analytics Engine vs Queues).

FAQCopy Anchor Link

KV said miss right after create - is D1 wrong?Copy Anchor Link

KV is eventually consistent. Warm on write and tolerate a brief D1 fallback.