# Bindings: config names and code names must match

A binding grants your Worker a capability, like reading an R2 bucket, and exposes it on the `env` object. Cloudflare's docs put it plainly: with bindings you never add secret keys to your Worker, the permission is embedded in the API itself.

## The rule that breaks everyone

The `binding` string in your Wrangler config is the property name your code uses. The resource name is separate. Confusing them is the classic failure:

```jsonc
{
  "main": "./src/index.js",
  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "prod-uploads" }]
}
```

```js
export default {
  async fetch(request, env) {
    await env.MY_BUCKET.put("key", request.body);
  }
};
```

Your code reads `env.MY_BUCKET` (the binding), not the bucket name `prod-uploads`. This applies to KV (`binding` vs namespace `id`), D1 (`binding` vs `database_id`), and Queues (`binding` vs `queue` name).

## Per-resource shapes

- KV: `kv_namespaces = [{ binding = "MY_KV", id = "abc123" }]` then `env.MY_KV.get(...)`.
- D1: `[[d1_databases]]` with `binding`, `database_name`, `database_id`, then `env.DB.prepare(...)`.
- Queues producer: `[[queues.producers]]` with `binding` and `queue`; consumer: `[[queues.consumers]]` with `queue` and optional `max_batch_size`.
- Python Workers: same config, access via `self.env.MY_BUCKET`.

## The stale-global trap

Deploying a bindings-only change may reuse existing isolates without reloading your code. Never cache clients derived from `env` (secrets, bucket handles) in global scope; construct per request so binding changes take effect. The docs show exactly this with a `new Client(env.MY_SECRET)` per-request pattern.

## Checklist

- After `wrangler kv:namespace create` or `wrangler d1 create`, copy the printed config block into your Wrangler file verbatim, do not retype ids.
- In Hono, bindings arrive on `c.env`, same names: type them (`type Bindings = { DB: D1Database }`) so mismatches fail at build.
- In local dev, bindings without a local id fall back to remote or fail; pass the id explicitly or accept the remote call.