Skip to main content

KV

Cloudflare KV is a globally distributed key-value store that works well for caching, session data, feature flags, and lightweight configuration.

Use KV when you need fast key lookups, optional TTLs, and global distribution without relational querying.

Consistency

Workers KV is eventually consistent. Writes are usually visible first in the region where they were made and can take up to 60 seconds or more to appear in other regions. Writes to the same key are also limited to 1 per second.

If you need atomic updates, hot counters, or transactional state, use Durable Objects instead of KV.

Config​

edgebase.config.ts
import { defineConfig } from '@edge-base/shared';

export default defineConfig({
  kv: {
    cache: { binding: 'CACHE_KV' },
    sessions: { binding: 'SESSIONS_KV' },
  },
});

This declares two KV namespaces, cache and sessions, each with an explicit Wrangler binding name.

Access Rules​

KV namespaces support optional read and write rules for access control:

edgebase.config.ts
export default defineConfig({
  kv: {
    cache: {
      binding: 'CACHE_KV',
      rules: {
        read(auth) {
          return auth !== null
        },
        write(auth) {
          return auth !== null && auth.role === 'admin'
        },
      },
    },
  },
});
RuleOperationsSignature
readget, list(auth: AuthContext | null) => boolean
writeset, delete(auth: AuthContext | null) => boolean

Without rules defined, KV access falls back to Service Key validation only. See Service Keys for scoped access such as kv:namespace:cache:read and kv:namespace:cache:write.

Next Steps​