Cloudflare Workers

When you type example.com into a browser and press Enter, your computer asks another computer, somewhere else in the world, for a page. That other computer sends the page back, and the browser draws it. Everything on the web is this exchange: someone asks, someone answers.

This course teaches you to write the computer on the right: the one that answers. With Cloudflare Workers, you write a small program that receives each question and decides the answer. Before any code, the next slides name the parts of the conversation.

The side that asks is the client: usually a browser, but also a phone app or another program. The side that answers is the server. The word means both the program that answers and the computer it runs on. A server waits, all day, for questions to arrive.

Client

The program that asks: a browser, an app, a script.

Server

The program (or computer) that waits for questions and answers them.

Request

The question a client sends.

Response

The answer a server sends back. Every request gets exactly one.

Computers on the internet find each other by IP address, a number such as 203.0.113.7. People prefer names like example.com, called domain names. The DNS (Domain Name System) is the internet’s phone book: the browser first asks DNS which number a name belongs to, then talks to that number.

A full web address is a URL (Uniform Resource Locator). Each part tells the server something different. Your Worker will read these parts to decide what to answer.

1https://go.example.com/recipes?from=email#top

Browsers and servers speak HTTP (Hypertext Transfer Protocol): a set of rules for writing requests and responses. A request is text with a method (what you want to do), a path, some headers, and sometimes a body (data you send along).

1GET /recipes?from=email HTTP/1.12Host: go.example.com3User-Agent: Mozilla/5.0 (a browser)4Accept: text/html

The response starts with a status code: a three-digit number that says how the request went. Then come headers, then the body (the page, the image, the data).

1HTTP/1.1 200 OK2Content-Type: text/html; charset=utf-83Content-Length: 12564
5<!doctype html><html>…</html>

Headers are Name: value lines that travel with a request or a response. They describe the message without being the message: what kind of data the body is, how long to keep it, where to go next. Names are not case sensitive: content-type and Content-Type are the same header.

Through this course you will build a link shortener: a service that turns a long address into a short one, like go.example.com/soup. When someone visits the short link, the server answers with a redirect: a 3xx status and a Location header pointing at the long address. The browser then goes there on its own.

• First it answers redirects from a list in the code.
• Then it keeps its links in a store (KV), counts clicks in a database (D1), keeps images (R2).
• Later it cleans up old links on a schedule, sends analytics through a queue, and more.

• A client sends a request; a server sends back exactly one response.
• DNS turns a domain name into the IP address of a server.
• A URL has a scheme, host, path, query and fragment.
• A request has a method, a path, headers and maybe a body.
• A response has a status code, headers and a body; 2xx worked, 3xx redirect, 4xx client error, 5xx server error.
• A redirect is a 3xx status with a Location header.

A server can be any computer that stays on and connected. You could run one at home. Then you would have to keep it on day and night, install updates, replace a broken disk, cope when a thousand people arrive at once, and accept that visitors on the other side of the world wait longer for every answer.

• Always on: if it switches off, your site is gone.
• Upkeep: an operating system to update and secure.
• Size: too small and it falls over when busy; too big and you pay for idle time.
• Distance: one computer in one city is far from most people.

Each idea in this module removes one of these chores.

“The cloud” means computers in large buildings called data centres, owned by a company that rents them out. You do not buy hardware; you rent a slice of a machine by the hour. The company handles power, cooling, cables and broken parts.

Data centre

A building full of servers, with power and fast internet links.

Virtual machine

A pretend computer carved out of a real one, rented to you.

Provider

The company renting out the computers: Cloudflare is one.

With serverless, you never see a machine. You hand the provider a piece of code. When a request arrives, the provider runs your code to answer it; when no one is asking, nothing runs and you pay nothing. There are still servers, of course: they are just not yours to look after.

Messages over the internet travel fast, but not instantly: a request from Sydney to a server in London and back takes a noticeable fraction of a second. That delay is called latency. The edge means running code in many cities at once, so each request is answered by a computer near the person who sent it.

Latency

The time a message takes to travel there and back.

Edge

Computers spread across many cities, close to users.

Cloudflare runs data centres in hundreds of cities. Cloudflare Workers lets you deploy a small program to all of them at once. Each request that reaches Cloudflare for your address runs your program, in the city nearest the visitor, and your program writes the response. It is serverless and on the edge at the same time.

Many serverless services start a whole small computer (a container) for your code, which can take seconds the first time: a cold start. Workers instead run each program in an isolate: a sealed-off space inside one shared JavaScript engine, the same engine (V8) that runs JavaScript in Chrome. Thousands of isolates share one process, and a new one starts in a few milliseconds.

A program that only computes answers is limited. Real services remember things, store files and do work later. Cloudflare offers storage and helpers that a Worker plugs into, and this course covers each one with the link shortener.

JavaScript is the language of the web. TypeScript is JavaScript with types: labels that say what kind of value each thing is (string, number, a Request), checked before the code runs, so many mistakes show up in your editor instead of in front of visitors. This course uses TypeScript; Wrangler, Cloudflare’s tool, turns it into JavaScript for you.

1// JavaScript would accept this and fail later.2// TypeScript underlines it at once: 42 is not a string.3const shortCode: string = 42

• The cloud is rented computers in data centres.
• Serverless: you give code, the provider runs it per request; idle costs nothing.
• The edge: code runs in many cities, close to each visitor, to cut latency.
• A Worker is serverless code deployed to all of Cloudflare’s locations.
• Workers run in isolates, which start in milliseconds.
• Storage and helpers (KV, D1, R2, Durable Objects, Queues, Cron) plug into a Worker.

A terminal is a window where you type instructions to your computer as text, instead of clicking. Each instruction is a command: a program’s name, then options. On macOS open Terminal, on Windows PowerShell or Windows Terminal, on Linux your terminal app. In this course, lines in a bash block are commands to type, one at a time, pressing Enter after each.

1# A line starting with # is a comment: don't type it.2node --version     # prints something like v22.12.03cd projects        # "change directory": move into a folder4ls                 # list the files here (dir on Windows)

Terminal

A text window for running commands.

Command

A program name plus options, run by pressing Enter.

Directory

Another word for a folder.

Your Worker runs on Cloudflare, but the tools that build and test it run on your computer, in Node.js: a program that runs JavaScript outside a browser. Install the current LTS (long-term support) version from nodejs.org. It comes with npm, which downloads code libraries (called packages), and npx, which runs a package’s command.

Sign up at dash.cloudflare.com. The dashboard is the website where you see and manage everything you have on Cloudflare. The Free plan includes Workers, with a daily allowance of requests, which is plenty to learn on. You do not need to own a domain name: every account gets a free address ending in workers.dev.

npm create cloudflare runs Cloudflare’s project maker, called C3. It asks a few questions, then writes a folder with a working Worker, installs its packages and can set up git (a tool that keeps the history of your files).

1npm create cloudflare@latest -- link-shortener2# What would you like to start with?  Hello World example3# Which template?                     Worker only4# Which language?                     TypeScript5# Do you want to deploy?              No (not yet)6cd link-shortener

1npm  cloudflare@latest -- link-shortener2 link-shortener

Wrangler runs your Worker on your computer, creates storage, deploys and shows logs. C3 installs it into the project, so you run it with npx wrangler. Before it can act on your account, log in once: it opens the browser and asks you to allow access.

1npx wrangler --version   # this course uses Wrangler 42npx wrangler login       # opens the browser to allow access3npx wrangler whoami      # which account you are logged in to

1npx  2npx wrangler 

JSON is a text format for data: names in double quotes, values after colons, { } around groups, [ ] around lists. JSONC is JSON that also allows // comments. Wrangler 4 reads wrangler.jsonc (recommended for new projects) or the older wrangler.toml.

1{2  "$schema": "node_modules/wrangler/config-schema.json",3  "name": "link-shortener",4  "main": "src/index.ts",5  "compatibility_date": "2026-11-01",6  "observability": { "enabled": true }7}

Errors are normal and they are information. Read the first line that says error and the last line of the output: one usually names the problem, the other the file and line. Most early errors are one of three kinds: the command was run in the wrong folder, a tool is missing, or you are not logged in.

• A terminal runs commands; cd moves between folders.
• Node.js runs the tools on your computer; npm installs packages; npx runs them.
• A free Cloudflare account gives you a workers.dev address.
• npm create cloudflare@latest makes a working project.
• Wrangler runs, deploys and manages Workers; wrangler login connects it to your account.
• wrangler.jsonc names the Worker, its entry file and its compatibility date.

A Worker uses only a few language features at first. If you have written JavaScript before, skim this slide.

Function

A named set of steps you can run, with inputs (parameters) and an output (return).

Object

A group of named values in { }, such as { name: 'soup', clicks: 3 }.

Method

A function that lives inside an object.

Promise

A value that is not ready yet, like a ticket for a coat. await waits for it; a function that awaits is marked async.

Module

A file of code. export makes something in it available to other code.

1const link = { code: 'soup', clicks: 3 }   // an object2function double(n: number) {               // a function3  return n * 24}5double(link.clicks)                        // 6

A Worker’s fetch is a plain function, so you can call it yourself: build a Request, call fetch with it, and read the Response that comes back. That is all the runtime does for each visitor. Cloudflare’s own types (ExportedHandler, Env) are not on this page, so the argument is typed by hand as a Request.

1const worker = {2  async fetch(request: Request): Promise<Response> {3    return new Response('Hello from the edge')4  }5}6
7// What the runtime does for each visitor, by hand:8const request = new Request('https://go.example.com/soup')9worker.fetch(request).then(async (response) => {10  console.log(response.status)         // 20011  console.log(await response.text())   // Hello from the edge12})

npx wrangler dev starts a local copy of the Workers runtime and serves your Worker at http://localhost:8787. localhost means “this computer”, and 8787 is the port, a numbered door on it. Save a change to src/index.ts and the Worker reloads by itself. Press x (or Ctrl+C) to stop.

1npx wrangler dev2# Ready on http://localhost:87873
4# in a second terminal, ask it something:5curl http://localhost:8787/6# Hello from the edge

A shortener answers with a redirect. Response.redirect(url, status) builds one: it sets the status and the Location header for you. Use 302 (Found, temporary) while you are still changing things; browsers remember a 301 (Moved Permanently) and may never ask again.

1export default {2  async fetch(request, env, ctx) {3    return Response.redirect('https://example.com/soup', 302)4  }5} satisfies ExportedHandler<Env>

npx wrangler deploy turns your TypeScript into JavaScript, bundles it (joins your code and its packages into one file), uploads it with the settings from wrangler.jsonc, and switches the Worker to the new code everywhere, usually within seconds.

1npx wrangler deploy2# Uploaded link-shortener3# Deployed link-shortener triggers4#   https://link-shortener.<your-subdomain>.workers.dev

Env is a type that lists what is on env. Wrangler writes it for you into worker-configuration.d.ts when you run npx wrangler types (the template’s npm run cf-typegen script does the same).

1export  {2  async (request, env, ctx) {3    return new ('ok')4  }5}  ExportedHandler<Env>

An exception is an error raised while code runs: reading a property of undefined, a failed network call. If fetch throws and nothing catches it, the visitor gets a Cloudflare error page (error 1101, “Worker threw exception”). Locally, wrangler dev prints the error and a stack trace: the list of functions that were running, with file and line, newest first.

1✘ [ERROR] TypeError: Cannot read properties of undefined2  (reading 'url')3    at Object.fetch (src/index.ts:3:25)

• A Worker is a module whose default export holds handlers.
• fetch(request, env, ctx) runs once per request and returns a Response.
• Response.redirect(url, 302) builds a redirect.
• npx wrangler dev runs it at localhost:8787; npx wrangler deploy publishes it.
• An uncaught exception becomes Cloudflare’s error 1101 page; the stack trace says where.

Workers use web standard APIs: objects defined once for the whole web, the same ones a browser offers. Request, Response, URL, Headers and the fetch function work the same in a Worker as in browser code. What you learn here works in many other places too.

API

Application Programming Interface: the functions and objects a system offers to code.

Web standard

An API agreed for the whole web, behaving the same everywhere it exists.

Property

A named value on an object, read with a dot: request.method.

1export default {2  async fetch(request, env, ctx) {3    request.method                     // "GET"4    request.url                        // "https://go.example.com/soup"5    request.headers.get('user-agent')  // "Mozilla/5.0 ..."6    request.headers.get('x-missing')   // null: no such header7    return new Response('ok')8  }9} satisfies ExportedHandler<Env>

request.url is the full address as one string. To pull out the path or the query, turn it into a URL object, next.

Time to write a handler. The tests play the runtime: they build a Request and call worker.fetch, then read the Response you return.

1const worker = {2  async fetch(request: Request): Promise<Response> {3    const url = new URL(request.url)4    // TODO: answer /hello, using url.searchParams5    return new Response('Not found', { status: 404 })6  }7}

A POST request usually carries a body. Read it with await request.json() (data in JSON), await request.text() (plain text) or await request.formData() (an HTML form). The body is a stream: data that arrives in pieces and is used up as it is read. A second read throws.

1// a client sends: {"code":"soup","url":"https://example.com/soup"}2const data = await request.json<{ code: string; url: string }>()3data.code   // "soup"

1const text = await request.text()2const data = await request.json()

In a Worker, request.json<NewLink>() takes a type. That is a Workers addition: the standard json() on this page returns any, so the code below names the type with as. Either way, nothing checks that the body really has that shape.

1type NewLink = { code: string }2
3const worker = {4  async fetch(request: Request): Promise<Response> {5    // TODO: read the body, then answer 201 with the short URL6    return new Response('Not done yet', { status: 501 })7  }8}

A Headers object has get, set, has and delete. On a response you build, you can change them. A response that came back from fetch is immutable (cannot be changed): to change its headers, copy it first with new Response(old.body, old), which keeps the status, the headers and the body stream.

const res = await fetch('https://example.com/')res.headers.set('X-Served-By', 'shortener')return res

const upstream = await fetch('https://example.com/')const res = new Response(upstream.body, upstream)res.headers.set('X-Served-By', 'shortener')return res

A Worker can be a client too. The global fetch(url, options) sends a request and gives back a promise of a Response. A request your Worker makes is a subrequest. While your Worker waits for the answer, it uses no CPU time (more on that in the limits module).

1// Does the long link still work?2const check = await fetch('https://example.com/soup', {3  method: 'HEAD',          // headers only, no body4  redirect: 'manual'       // don't follow redirects5})6check.ok        // true for any 2xx status7check.status    // 200

Cloudflare adds facts about each visitor. request.cf is an object with the visitor’s country, city, the colo (the Cloudflare location that took the request) and more. The CF-Connecting-IP header holds the visitor’s IP address. Locally, wrangler dev fills these with sample values.

1const country = request.cf?.country ?? 'unknown'   // "PE"2const ip = request.headers.get('cf-connecting-ip')

• Workers use web standard objects: Request, Response, URL, Headers, fetch.
• new URL(request.url) gives pathname and searchParams.
• A body is a stream: read it once with json(), text() or formData().
• new Response(body, { status, headers }), Response.json and Response.redirect build answers.
• Fetched responses are immutable: copy with new Response(res.body, res) to change headers.
• fetch rejects only when no response arrives; check ok and status.

Routing is choosing which piece of code answers a request. A route pairs a method and a path pattern with the code that answers it. The shortener needs a few routes; each is a different job.

Route

A method and path pattern, plus the code that answers it.

Path parameter

A part of the path that varies, written :code in a pattern.

Checks run top to bottom and the first match answers. A catch-all route like /:code matches almost anything, so it must come after specific ones like /health, or health would be treated as a short code.

1const code = pathname.slice(1)2if (code) return redirectOrNotFound(code)   // any /something3if (pathname === '/health') return new Response('ok')

Some characters cannot appear raw in a URL, so browsers percent-encode them: a space becomes %20, é becomes %C3%A9. pathname gives you the encoded form. decodeURIComponent turns it back, and throws on broken encodings like %E0%A4%A, so catch that and answer 400.

1new URL('https://go.example.com/caf%C3%A9').pathname  // "/caf%C3%A9"2decodeURIComponent('caf%C3%A9')                       // "café"3
4function codeFrom(pathname: string): string | null {5  try {6    return decodeURIComponent(pathname.slice(1))7  } catch {8    return null   // a broken encoding: answer 4009  }10}

1const code = (pathname.(1))

If the path exists but the method does not fit (a DELETE on a page that only reads), the right answer is 405 Method Not Allowed, with an Allow header listing what would work. A 404 would wrongly say the path does not exist.

1if (pathname === '/api/links') {2  if (request.method === 'POST') return createLink(request, env)3  return new Response('Method not allowed', {4    status: 405,5    headers: { Allow: 'POST' }6  })7}

Put the last three slides together: specific routes first, the right status for a wrong method, the catch-all last.

1const LINKS: Record<string, string> = {2  soup: 'https://example.com/recipes/tomato-soup'3}4
5const worker = {6  async fetch(request: Request): Promise<Response> {7    const { pathname } = new URL(request.url)8    if (pathname === '/health') return new Response('ok')9    // TODO: /api/links (POST only), then GET /<code>10    return new Response('Not found', { status: 404 })11  }12}

URLPattern is a web standard built into Workers. You write a pattern with named parts, and exec tells you whether a URL matches and what each part was.

1const linkStats = new URLPattern({2  pathname: '/api/links/:code/stats'3})4
5const match = linkStats.exec(request.url)6if (match) {7  const code = match.pathname.groups.code   // "soup"8  return Response.json(await statsFor(env, code))9}

Wrap the routing in try/catch so an unexpected error becomes your own 500 response, and gets logged, instead of Cloudflare’s error page. Mind the await: without it, a promise that fails later escapes the try.

Routing by hand is fine for a handful of routes, and it shows you what any router does. With dozens, you want parameters, shared steps (logging, auth) before many routes, and one place for errors. Libraries like Hono give you that, and their app is still a fetch handler underneath.

1import { Hono } from 'hono'2
3const app = new Hono<{ Bindings: Env }>()4app.get('/health', (c) => c.text('ok'))5app.get('/:code', (c) => redirectFor(c.env, c.req.param('code')))6
7export default app   // app.fetch is the fetch handler

• A route pairs a method and a path pattern with code.
• Checks run in order: specific routes before catch-alls.
• decodeURIComponent reverses percent-encoding and can throw.
• Wrong method on a real path: 405 with an Allow header.
• URLPattern matches paths with named parameters.
• return await inside try so failures reach your catch.

Some values change between your laptop and the real site, or between today and next month: the public address of the service, a limit, a key for another company’s API. If they are written into the code, changing one means changing code. Workers keep them in the config and hand them to your code on env.

Environment variable (var)

A named setting given to the program from outside its code.

Secret

A setting that must stay private, such as a password or API key: stored encrypted, never shown again.

`env`

The second argument of fetch: every var, secret and connection the Worker has.

wrangler.jsonc is usually kept in git and visible in the dashboard, so it must never hold a secret. Set secrets with wrangler secret put: it asks for the value (so it never lands in your terminal history), stores it encrypted, and gives the Worker a new version with it. Your code reads it on env like any var.

1npx wrangler secret put ADMIN_TOKEN2# ? Enter a secret value: ********3npx wrangler secret list      # names only, never the values4npx wrangler secret delete ADMIN_TOKEN

1npx wrangler   ADMIN_TOKEN

wrangler dev does not read your production secrets. It reads a file named .dev.vars (or .env; use one, not both) in the project folder, one NAME=value per line. Add it to .gitignore, the list of files git must not save, and commit a .dev.vars.example with harmless placeholders so others know what to fill in.

1# Copy to .dev.vars and fill in. Never commit .dev.vars.2ADMIN_TOKEN=pick-any-long-local-value

Only the owner should create links. A simple guard: the client sends the token in the Authorization header, as Bearer <token>, and the Worker compares it with the secret.

Code that reads env is easy to test: hand it a fake env with harmless values. Here Env is written by hand; in a project, wrangler types writes it.

1interface Env {2  ADMIN_TOKEN?: string3}4
5function isAdmin(request: Request, env: Env): boolean {6  // TODO: compare the Authorization header with the secret7  return false8}

npx wrangler types reads the config (and the names in .dev.vars) and writes worker-configuration.d.ts: an Env type listing every var, secret and binding, plus the types of the runtime itself for your compatibility date. Run it again whenever the config changes.

1interface Env {2  PUBLIC_BASE: "https://go.example.com";3  MAX_CODE_LENGTH: "32";4  SIGNUPS_OPEN: "true";5  ADMIN_TOKEN: string;6}

Cloudflare keeps improving the runtime. Changes that could break existing code are tied to a date: compatibility_date says “behave as the runtime did on this day”. Time passing never changes your Worker. Single changes can also be switched on early with compatibility_flags.

1. Move the date forward on purpose, not by accident.
2. Read what changed between the old and new dates in Cloudflare’s compatibility dates page.
3. Run your tests, then deploy.

• Vars are plain settings in wrangler.jsonc, read on env.
• A quoted "false" is a truthy string: compare explicitly.
• Secrets are set with wrangler secret put, never in config or code.
• Locally, secrets come from a git-ignored .dev.vars.
• wrangler types writes the Env type; rerun it when config changes.
• compatibility_date freezes runtime behaviour until you move it.

Normally, to use a database you need its address, a username and a password in your code. Workers use bindings instead: you declare in wrangler.jsonc that the Worker may use a resource, give it a name, and the runtime puts a ready-made object on env under that name. No address, no keys, nothing to leak.

Binding

A named connection to a resource, declared in config and found on env.

Resource

Something the Worker uses: a store, a database, a bucket, another Worker.

Workers KV stores values under keys, like a dictionary: you look up soup and get back its long link. Values are copied to Cloudflare’s locations as they are read, so popular keys come back in a few milliseconds anywhere in the world. It is made for data read often and written rarely, which is exactly what links are.

Key-value store

Storage where each value is saved and fetched by a unique key.

Namespace

One KV store: its own set of keys, bound to Workers by id.

Real KV is not on this page, so the tests hand your Worker a stand-in: an object with the same get and delete as a KVNamespace, keeping its keys in a Map (a key-value collection in memory). Your code cannot tell the difference, which is the point of a binding.

1// The part of KVNamespace this Worker uses2interface KV {3  get(key: string): Promise<string | null>4  delete(key: string): Promise<void>5}6interface Env {7  LINKS: KV8}9
10const worker = {11  async fetch(request: Request, env: Env): Promise<Response> {12    const code = new URL(request.url).pathname.slice(1)13    // TODO: DELETE removes the key; GET redirects to it14    return new Response('Not found', { status: 404 })15  }16}

Values are stored as text (or bytes). To keep more than a URL, store JSON and ask get to parse it. A key can also expire: expirationTtl is a lifetime in seconds (at least 60), expiration an exact moment in seconds since 1970. Expired keys disappear by themselves.

1type Link = { url: string; createdAt: number }2
3const link: Link = { url, createdAt: Date.now() }4await env.LINKS.put(code, JSON.stringify(link), {5  expirationTtl: 60 * 60 * 24 * 30          // 30 days6})7
8const saved = await env.LINKS.get<Link>(code, 'json')9saved?.url

KV keeps copies of values at many locations. A write goes to a central store first, and other locations keep serving their copy for a while. Changes can take 60 seconds or more to be seen everywhere. This is called eventual consistency: every location will agree, but not instantly. KV also allows only about one write per second to the same key.

list returns key names (not values), in alphabetical order, up to 1,000 per call. If there are more, list_complete is false and cursor is a bookmark to pass to the next call. A common trick is a prefix: name keys link:soup, link:docs, and list only link:.

1let cursor: string | undefined2do {3  const page = await env.LINKS.list({ prefix: 'link:', cursor })4  for (const key of page.keys) console.log(key.name)5  cursor = page.list_complete ? undefined : page.cursor6} while (cursor)

Now POST /api/links can write to KV. The Worker checks the token, reads the body, refuses a code that is already taken (409 Conflict), saves the link and answers 201 Created.

The route checks the token and reads { code, url } from the body, as in earlier modules, then hands the link to createLink. The tests give it a stand-in for KV with the real get and put shapes.

1// The part of KVNamespace this code uses2interface KV {3  get(key: string): Promise<string | null>4  put(5    key: string,6    value: string,7    options?: { expirationTtl?: number }8  ): Promise<void>9}10type NewLink = { code: string; url: string }11
12async function createLink(link: NewLink, env: { LINKS: KV }) {13  // TODO: 409 if taken; else save for 30 days and answer 20114  return new Response('Not done yet', { status: 501 })15}

wrangler dev gives your Worker a local KV, saved in the project’s .wrangler/state folder, separate from the real one. Wrangler’s kv key commands can write to either: say which with --local or --remote.

1npx wrangler kv key put soup "https://example.com/soup" \2  --binding LINKS --local3npx wrangler kv key get soup --binding LINKS --remote4npx wrangler kv key list --binding LINKS --local

• A binding is declared in config and appears on env: no addresses or keys in code.
• KV stores values by key, fast to read everywhere, made for read-heavy data.
• get returns null for a missing key; put and delete must be awaited.
• Store JSON with JSON.stringify and read it with get(key, 'json').
• expirationTtl makes keys expire; list pages through keys with a cursor.
• KV is eventually consistent: changes take up to a minute or more to spread.

A relational database keeps data in tables, like spreadsheets with strict rules. Each column has a name and a type; each row is one record. You talk to it in SQL (Structured Query Language), a language for asking and changing data: “give me the rows where…”, “add this row”.

1SELECT day, clicks FROM daily_clicks2WHERE code = 'soup'3ORDER BY day DESC;

D1 is a database built on SQLite, a small and very widely used SQL database. Cloudflare runs it for you; your Worker reaches it through a binding. Writes go to one primary copy, so a write is seen by the next query: no waiting for copies to agree, unlike KV.

A migration is a numbered SQL file that changes the database’s shape: create a table, add a column. Wrangler records which ones a database has had, and applies only the new ones, in order. The same files build your local database and the real one, so they always match.

1CREATE TABLE daily_clicks (2  code   TEXT    NOT NULL,3  day    TEXT    NOT NULL,       -- '2026-11-10'4  clicks INTEGER NOT NULL DEFAULT 0,5  PRIMARY KEY (code, day)        -- one row per link per day6);

1const stmt = env.DB.prepare(2  'SELECT day, clicks FROM daily_clicks WHERE code = ?1'3).bind(code)4
5const { results } = await stmt.all<{ day: string; clicks: number }>()6const row = await stmt.first<{ day: string; clicks: number }>()7const total = await env.DB8  .prepare('SELECT SUM(clicks) AS n FROM daily_clicks WHERE code = ?')9  .bind(code)10  .first<number>('n')

For statements that change data, use run(): its result has meta.changes, the number of rows affected.

If you paste user input into SQL text, a visitor can type SQL of their own, and the database will run it. This attack is SQL injection. With bind, values travel separately from the SQL and are never read as SQL.

env.DB.prepare(  `SELECT * FROM daily_clicks WHERE code = '${code}'`).all()// code = "x' OR '1'='1" returns every row

env.DB.prepare(  'SELECT * FROM daily_clicks WHERE code = ?').bind(code).all()

Reading the count, adding one in JavaScript and writing it back breaks when two clicks arrive together: both read 41, both write 42. Let the database do it in one atomic statement (one that happens all at once or not at all). ON CONFLICT … DO UPDATE inserts the row, or adds one if it is already there.

1await env.DB.prepare(`2  INSERT INTO daily_clicks (code, day, clicks) VALUES (?, ?, 1)3  ON CONFLICT (code, day) DO UPDATE SET clicks = clicks + 14`).bind(code, new Date().toISOString().slice(0, 10)).run()

env.DB.batch([...]) sends several statements in one trip and runs them as a transaction: if one fails, none of them take effect. It is also faster than awaiting statements one at a time, because each await is a round trip to the database.

1const [, totals] = await env.DB.batch([2  env.DB.prepare('DELETE FROM daily_clicks WHERE code = ?')3    .bind(oldCode),4  env.DB.prepare('SELECT COUNT(*) AS n FROM daily_clicks')5])6totals.results   // [{ n: 1204 }]

• Tables have columns and rows; SQL asks and changes them.
• D1 is SQLite run by Cloudflare: a write is seen by the next query.
• Migrations are numbered SQL files, applied locally first, then with --remote.
• prepare(sql).bind(values), then all, first or run.
• Never paste input into SQL: bind it.
• Let the database update counts atomically; batch runs statements as one transaction.

Each time you deploy, Cloudflare stores a version: your code plus its config (bindings, vars, compatibility date), never changed afterwards. A deployment says which version receives traffic. wrangler deploy does both at once: it makes a version and sends it 100% of the traffic.

1npx wrangler deployments list   # recent deployments, newest last2npx wrangler versions list      # recent versions and their ids3npx wrangler rollback           # back to the previous version

Version

An immutable snapshot of a Worker’s code and config.

Deployment

Which version (or versions) gets traffic, and in what share.

Rollback

Sending traffic back to an earlier version.

A rollback is fast because the old version still exists: Cloudflare only switches traffic. But data is not part of a version. Rows written to D1, keys in KV and files in R2 stay as the new version left them, and a migration already applied stays applied.

You want somewhere to try changes that is not the real site. An environment is a block under env in wrangler.jsonc that deploys as a separate Worker (named link-shortener-staging here) with --env staging. Watch out: bindings and vars are not inherited. An environment that does not list them has none.

1{2  "name": "link-shortener",3  "main": "src/index.ts",4  "compatibility_date": "2026-11-01",5  "vars": { "PUBLIC_BASE": "https://go.example.com" },6  "kv_namespaces": [{ "binding": "LINKS", "id": "<prod id>" }],7  "env": {8    "staging": {9      "vars": { "PUBLIC_BASE": "https://staging.example.com" },10      "kv_namespaces": [{ "binding": "LINKS", "id": "<staging id>" }]11    }12  }13}