Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
pcx_content_type: how-to
title: Bindings
sidebar:
order: 5
---
import { Aside } from "@astrojs/starlight/components";

When you deploy User Workers through Workers for Platforms, you can attach [bindings](/workers/runtime-apis/bindings/) to give them access to resources like [KV namespaces](/kv/), [D1 databases](/d1/), [R2 buckets](/r2/), and more. This enables your end customers to build more powerful applications without you having to build the infrastructure components yourself.

With bindings, each of your users can have their own:
- [KV namespace](/kv/) that they can use to store and retrieve data
- [R2 bucket](/r2/) that they can use to store files and assets
- [Analytics Engine](/analytics/analytics-engine/) dataset that they can use to collect observability data
- [Durable Objects](/durable-objects/) class that they can use for stateful coordination

#### Resource isolation

Each User Worker can only access the bindings that are explicitly attached to it. For complete isolation, you can create and attach a unique resource (like a D1 database or KV namespace) to every User Worker.

![Resource Isolation Model](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-5.svg "Resource Isolation Model")

## Adding a KV Namespace to a User Worker
This example walks through how to create a [KV namespace](/kv/) and attach it to a User Worker. The same process can be used to attach to other [bindings](/workers/runtime-apis/bindings/).

### 1. Create a KV namespace
Create a KV namespace using the [Cloudflare API](/api/resources/kv/subresources/namespaces/methods/bulk_update/).

### 2. Attach the KV namespace to the User Worker

Use the [Upload User Worker API](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/) to attach the KV namespace binding to the Worker. You can do this when you're first uploading the Worker script or when updating an existing Worker.

:::note
When using the API to upload scripts, bindings must be specified in the `metadata` object of your multipart upload request. You cannot upload the `wrangler.toml` file as a module to configure the bindings. For more details about multipart uploads, see [Multipart upload metadata](/workers/configuration/multipart-upload-metadata/).
:::

##### Example API request

```bash
curl -X PUT \
"https://api.cloudflare.com/client/v4/accounts/<account-id>/workers/dispatch/namespaces/<your-namespace>/scripts/<script-name>" \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer <api-token>" \
-F 'metadata={
"main_module": "worker.js",
"bindings": [
{
"type": "kv_namespace",
"name": "USER_KV",
"namespace_id": "<your-namespace-id>"
}
]
}' \
-F 'worker.js=@/path/to/worker.js'
```
Now, the User Worker has can access the `USER_KV` binding through the `env` argument using `env.USER_DATA.get()`, `env.USER_DATA.put()`, and other KV methods.

Note: If you plan to add new bindings to the Worker, use the `keep_bindings` parameter to ensure existing bindings are preserved while adding new ones.

```bash
curl -X PUT \
"https://api.cloudflare.com/client/v4/accounts/<account-id>/workers/dispatch/namespaces/<your-namespace>/scripts/<script-name>" \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer <api-token>" \
-F 'metadata={
"bindings": [
{
"type": "r2_bucket",
"name": "STORAGE",
"bucket_name": "<your-bucket-name>"
}
],
"keep_bindings": ["kv_namespace"]
}'
```
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,6 @@ Since you will be deploying Workers on behalf of your users, you will likely wan

## Bindings

You can use any Workers [bindings](/workers/runtime-apis/bindings/) with the dynamic dispatch Worker or any user Workers.
You can use any Workers [bindings](/workers/runtime-apis/bindings/) with the dynamic dispatch Worker or any [user Workers](/cloudflare-for-platforms/workers-for-platforms/get-started/bindings/).

Bindings for your user Workers can be defined on [multipart script uploads](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/content/methods/update/) in the [metadata](/workers/configuration/multipart-upload-metadata/) part.
To learn how to extend KV, D1, R2, and other resources to your User Workers through bindings, see [Bindings](/cloudflare-for-platforms/workers-for-platforms/get-started/bindings/).