Durable Object storage list prefix support
As of 2020-12-04, Durable Objects storage API supports listing keys by prefix.
Cloudflare Workers · all subjects
bindings
223 notes in this subject, read out of this brain and free to use. This is page 3 of 4.
Durable Object fetch() call from constructor
Durable Object constructors may initiate I/O such as fetch() calls.
Durable Object persistent storage isolation
When a Durable Object's code is updated, only a single instance ever has access to persistent storage for a given Durable Object.
Service Bindings for Worker-to-Worker communication
Use Service Bindings to send requests from one Worker to another on your account without going over the Internet. Using global fetch() to call another Worker on the same zone without service bindings fails. Workers accept requests sent to a Custom Domain.
Workers KV ideal use cases
Workers KV is ideal for projects that require high volumes of reads and/or repeated reads to the same keys, low-latency global reads (typically within 10ms for hot keys), per-object time-to-live (TTL), and distributed configuration and/or session storage.
Workers KV cache latency for hot keys
Repeated reads to 'hot keys' in Workers KV will typically see latencies in the 500µs to 10ms range due to KV's internal cache.
Workers KV session storage best practice
Workers KV is recommended for storing session data, credentials (API keys), and configuration data. These are typically read at high rates (thousands of RPS or more), are not typically modified (within KV's 1 write RPS per unique key limit), and do not need to be immediately consistent.
R2 ideal use cases
R2 is ideal for projects that require storage for files which are infrequently accessed, large object storage (for example, gigabytes or more per object), strong consistency per object, and asset storage for websites.
R2 no egress fees
R2 is S3-compatible blob storage that allows developers to store large amounts of unstructured data without egress fees associated with typical cloud storage services.
Durable Objects global uniqueness
Global Uniqueness in Durable Objects guarantees that there will be a single instance of a Durable Object class with a given ID running at once, across the world. Requests for a Durable Object ID are routed by the Workers runtime to the Cloudflare data center that owns the Durable Object.
Durable Objects transactional storage API
The transactional storage API provides strongly consistent key-value storage to the Durable Object. Each Object can only read and modify keys associated with that Object. Execution of a Durable Object is single-threaded, but multiple request events may still be processed out-of-order from how they arrived at the Object.
Durable Objects ideal use cases
Durable Objects are ideal for projects that require real-time collaboration (such as a chat application or a game server), consistent storage, and data locality.
D1 ideal use cases
D1 is ideal for persistent, relational storage for user data, account data, and other structured datasets; use-cases that require querying across data ad-hoc using SQL; and workloads with a high ratio of reads to writes (most web applications).
D1 maximum database size
The maximum size for a D1 database is 10 GB. If working data size exceeds this limit, consider splitting the database into multiple, smaller D1 databases.
D1 read replication benefit
D1 has read replication that benefits global users.
Hyperdrive ideal use cases
Hyperdrive is ideal if you have an existing Postgres or MySQL database, require large (1TB, 100TB or more) single databases, and/or want to use your existing database tools. You can also connect Hyperdrive to database platforms like PlanetScale or Neon.
Hyperdrive capabilities
Hyperdrive allows you to connect to an existing database from Workers without connection overhead, cache frequent queries across Cloudflare's global network to reduce response times on highly trafficked content, and reduce load on your origin database with connection pooling.
Queues ideal use cases
Cloudflare Queues is ideal for offloading work from a request to schedule later, sending data from Worker to Worker (inter-Service communication), and buffering or batching data before writing to upstream systems, including third-party APIs or Cloudflare R2.
Queues delivery guarantee
Cloudflare Queues offers at-least once delivery, message batching, and does not charge for egress bandwidth.
Pipelines ideal use cases
Pipelines is a streaming ingestion service ideal for ingesting data at extremely high throughput (tens of thousands of records per second or more) and batching and writing data directly to object storage, ready for querying.
Analytics Engine ideal use cases
Analytics Engine is Cloudflare's time-series and metrics database that allows you to expose custom analytics to your own customers, build usage-based billing systems, understand the health of your service on a per-customer or per-user basis, and add instrumentation to frequently called code paths without impacting performance or overwhelming external analytics systems with events.
Vectorize ideal use cases
Vectorize is a globally distributed vector database that enables you to store embeddings from any vector embeddings model (Bring Your Own embeddings) for semantic search and classification tasks, add context to Large Language Model (LLM) queries by using vector search as part of a Retrieval Augmented Generation (RAG) workflow, and filter on vector metadata to reduce the search space and return more relevant results.
SQL database options comparison
Three options for SQL-based databases are available when building applications with Workers: Hyperdrive (for existing Postgres or MySQL databases requiring large single databases or existing database tools), D1 (for lightweight, serverless applications that are read-heavy with global users), and Durable Objects (for stateful serverless workloads, per-user or per-customer SQL state, and distributed systems where strict serializability enables global ordering of requests and storage operations).
Workers KV included in plans
Workers KV is included in both the Workers Free and Workers Paid plans.
Hyperdrive included in plans
Hyperdrive is included in both the Workers Free and Workers Paid plans.
D1 availability
D1 is available on both the Workers Free and Workers Paid plans.
R2 pricing table
R2 pricing is based on total volume of data stored and two classes of operations: | | Free | Standard storage | Infrequent Access storage | |------------------------------------|-----------------------------|--------------------------|---------------------------| | Storage | 10 GB-month / month | $0.015 / GB-month | $0.01 / GB-month | | Class A Operations | 1 million requests / month | $4.50 / million requests | $9.00 / million requests | | Class B Operations | 10 million requests / month | $0.36 / million requests | $0.90 / million requests | | Data Retrieval (processing) | None | None | $0.01 / GB | | Egress (data transfer to Internet) | Free | Free | Free | Class A operations are more expensive and tend to mutate state. Class B operations tend to read existing state. There are no charges for egress bandwidth.
Cache API as ephemeral key-value store
The Cache API can be thought of as an ephemeral key-value store, whereby the Request object (or more specifically, the request URL) is the key, and the Response is the value.
Cache namespaces: caches.default and caches.open()
There are two types of cache namespaces available to the Cloudflare Cache: (1) caches.default – Access the default cache (the same cache shared with fetch requests) by accessing caches.default. This is useful when needing to override content that is already cached after receiving the response. (2) caches.open() – Access a namespaced cache (separate from the cache shared with fetch requests) using let cache = await caches.open(CACHE_NAME). Note that caches.open is an async function, unlike caches.default.
Bindings D1, Workers AI, Vectorize, Workflows, Images only available in ES modules
Bindings for D1, Workers AI, Vectorize, Workflows, and Images can only be used from Workers that use ES modules format.
Service Worker bindings are global scope
In Service Worker syntax, bindings are exposed as globals and are available anywhere in the Worker application code.
ES modules bindings accessed via env parameter
In ES modules format, bindings are only available inside the env parameter provided at the entry point to the Worker. The env parameter must be passed from the fetch handler to functions that need to access bindings.
Accessing KV binding in ES modules
To access a KV namespace binding in ES modules format, the env parameter must be passed to the function. Access the binding via env.BINDING_NAME, for example: env.TODO.get('key').
ASSETS binding configuration
Configure an optional ASSETS binding to access the collection of assets from within a Worker script. Specify the binding name in the wrangler.json file under assets.binding (e.g., "ASSETS"). This allows dynamic fetching of assets using env.ASSETS.fetch(). The binding enables programmatic access to static assets when the Worker script is invoked.
ASSETS binding fetch() method
The ASSETS binding provides a fetch() method with the following signature: fetch(request: Request | URL | string): Promise<Response>. Parameters: request accepts a Request object, URL object, or URL string. Requests made through this method have html_handling and not_found_handling configuration applied to them. Returns a Promise resolving to a static asset Response for the given request. The hostname used in the URL (e.g., assets.local) is not meaningful — any valid hostname works. Only the URL pathname is used to match assets.
ASSETS binding fetch() with RPC methods
When fetching assets from within an RPC method where there is no incoming request, construct a URL using any hostname, for example: this.env.ASSETS.fetch(new Request('https://assets.local/path/to/asset')). This allows RPC methods to access static assets despite having no incoming request context.
ASSETS binding usage example
Example showing how to use the ASSETS binding in a Worker. When a request starts with /api/, return a custom response. Otherwise, pass the incoming request through to the assets binding with env.ASSETS.fetch(request). If no asset matches, the not_found_handling behavior is evaluated. JavaScript example: ```js export default { async fetch(request, env) { const url = new URL(request.url); if (url.pathname.startsWith("/api/")) { return new Response("Ok"); } return env.ASSETS.fetch(request); }, }; ``` TypeScript example: ```ts interface Env { ASSETS: Fetcher; } export default { async fetch(request, env): Promise<Response> { const url = new URL(request.url); if (url.pathname.startsWith("/api/")) { return new Response("Ok"); } return env.ASSETS.fetch(request); }, } satisfies ExportedHandler<Env>; ```
Assets binding for serving files in Worker code
An assets binding allows you to directly fetch and serve assets within your Worker code. The binding is configured in wrangler.json under `assets.binding` and accessed via `env.ASSETS.fetch(request)` in your Worker handler.
Assets binding in Workers configuration
In Workers, the ASSETS binding to access static assets must be manually configured. The binding name is customizable. Example configuration: {"name": "my-worker", "compatibility_date": "$today", "main": "./worker/index.ts", "assets": {"directory": "./dist/client/", "binding": "ASSETS"}}.
Durable Objects with Cloudflare Pages setup
To use Durable Objects with a Cloudflare Pages project, you must create a separate Worker with a Durable Object and declare a binding to it in both Production and Preview environments. Using Durable Objects with Workers is simpler and recommended.
Multiple workers sharing same KV namespace with different bindings
Multiple workers can access the same KV namespace in Miniflare by specifying the same namespace identifier (e.g. 'counts') but binding it to different names in each worker's kvNamespaces configuration. For example, one worker can bind it as COUNTS while another binds it as NUMBERS.
kvNamespaces, r2Buckets, d1Databases options in Miniflare v3
In Miniflare v3, kvNamespaces, r2Buckets, and d1Databases options now accept both string arrays and Record<string, string> objects that map binding names to namespace IDs, bucket names, or database IDs. This allows multiple Workers to bind to the same namespace, bucket, or database under different binding names.
queueBindings renamed to queueProducers in Miniflare v3
In Miniflare v3, queueBindings has been renamed to queueProducers. It accepts either a Record<string, string> mapping binding names to queue names, or a string array of binding names for queues with the same name.
queueConsumers configuration in Miniflare v3
In Miniflare v3, queueConsumers accepts either a Record<string, QueueConsumerOptions> mapping queue names to consumer options, or a string array of queue names to consume with default options. QueueConsumerOptions has properties: maxBatchSize (number, default 5), maxBatchTimeout (number in seconds, default 1), maxRetries (number, default 2), and deadLetterQueue (string, default none).
Multiple workers with shared bindings example in Miniflare v3
Example of Miniflare v3 configuration with multiple workers sharing KV namespace bindings under different names: A 'worker' configuration has kvNamespaces binding COUNTS to 'counts' namespace, and serviceBindings to 'incrementer' worker and a custom CUSTOM function. An 'incrementer' worker configuration binds the same 'counts' namespace to NUMBERS. Both workers can access the same data through different binding names.
Miniflare getKVNamespace method
Get a KV namespace from a Miniflare instance: ```js const TEST_NAMESPACE = await mf.getKVNamespace("TEST_NAMESPACE"); ```
Miniflare getR2Bucket method
Get an R2 bucket from a Miniflare instance: ```js const BUCKET = await mf.getR2Bucket("BUCKET"); ```
Miniflare getCaches method
Get the global `CacheStorage` instance and access caches: ```js const caches = await mf.getCaches(); const defaultCache = caches.default; const namedCache = await caches.open("name"); ```
Miniflare getDurableObjectNamespace method
Get a Durable Object namespace and work with it: ```js const TEST_OBJECT = await mf.getDurableObjectNamespace("TEST_OBJECT"); const id = TEST_OBJECT.newUniqueId(); ```
Miniflare getDurableObjectStorage method
Get storage for a Durable Object ID: ```js const storage = await mf.getDurableObjectStorage(id); ```
Miniflare getQueueProducer method
Get a Queue Producer from a Miniflare instance: ```js const producer = await mf.getQueueProducer("QUEUE_BINDING"); ```
Miniflare getD1Database method
Get a D1 Database from a Miniflare instance: ```js const db = await mf.getD1Database("D1_BINDING"); ```
Miniflare service bindings example
Service bindings allow workers to call other workers. Service bindings can reference other named workers or be custom async functions: ```js serviceBindings: { INCREMENTER: "incrementer", async CUSTOM(request) { return new Response(message); }, } ```
KV namespace creation and configuration
Create a KV namespace using: npx wrangler kv namespace create "TODOS" --preview. The --preview flag creates a preview namespace. Configure the namespace in wrangler.json under kv_namespaces with binding, id, and preview_id fields. The binding name (e.g., "TODOS") becomes available as env.TODOS in the Worker code.
KV API primary methods
A KV namespace has three primary methods: get() to retrieve data, put() to store data, and delete() to remove data. Data must be stringified before storage and parsed after retrieval. Use: env.TODOS.put(key, JSON.stringify(data)) to write and env.TODOS.get(key) to read.
KV eventual consistency behavior
Workers KV is an eventually consistent, global datastore. Any writes within a region are immediately reflected within that same region but are not immediately available in other regions. Writes eventually become available everywhere, and Workers KV guarantees data consistency within each region after writes propagate.
User-specific KV caching with request headers
Create user-specific cache keys by extracting client information from request headers. Example: const ip = request.headers.get('CF-Connecting-IP'); const myKey = `data-${ip}`;. This allows maintaining separate data per user while sharing the same KV namespace.
Turso database connection requires two pieces of information
To connect to Turso from a Cloudflare Worker, you need: LIBSQL_DB_URL (the connection string for your Turso database) and LIBSQL_DB_AUTH_TOKEN (the authentication token for your Turso database, which should be kept secret and not committed to source code).
R2Bucket type for bindings
When defining Bindings type for a Hono Worker with R2, use the type R2Bucket for the R2 binding. Example: type Bindings = { MY_BUCKET: R2Bucket, OPENAI_API_KEY: string }
Create R2 bucket with wrangler
Use `npx wrangler r2 bucket create <BUCKET_NAME>` to create a new R2 bucket. Bucket names must be lowercase and can only contain dashes.