KV 바인딩

Worker와 KV 네임스페이스 사이의 통신을 가능하게 하는 KV 바인딩을 설정하는 방법을 알아봐요. Wrangler 설정 파일에서 바인딩을 정의하고 Worker 코드에서 사용하는 전체 과정을 살펴봐요.

출처: 문서

본문

KV 바인딩은 Worker와 KV 네임스페이스 사이의 통신을 가능하게 해요.

KV 바인딩은 Wrangler 설정 파일에서 구성해요.

Workers에서 KV 접근하기

KV 네임스페이스는 Cloudflare의 글로벌 네트워크에 복제되는 키-값 데이터베이스예요.

Worker 안에서 KV 네임스페이스에 연결하려면 네임스페이스의 ID를 가리키는 바인딩을 정의해야 해요.

바인딩의 이름은 KV 네임스페이스의 이름과 일치할 필요는 없어요. 대신 바인딩은 유효한 JavaScript 식별자여야 해요. 그 식별자가 Worker 안에서 전역 변수로 존재하기 때문이에요.

KV 네임스페이스는 직접 고른 이름 (예: My tasks) 과 할당된 ID (예: 06779da6940b431db6e566b4846d64db) 를 가져요.

Worker를 실행하려면 바인딩을 정의하세요.

다음 예시에서 바인딩은 TODO 라고 불러요. Wrangler 설정 파일의 kv_namespaces 부분에 다음을 추가하세요:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker",
	// ...
	"kv_namespaces": [
		{
			"binding": "TODO",
			"id": "06779da6940b431db6e566b4846d64db"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker"

[[kv_namespaces]]
binding = "TODO"
id = "06779da6940b431db6e566b4846d64db"

이렇게 하면 배포된 Worker의 환경 객체 ( fetch() 요청 핸들러의 두 번째 매개변수) 에 TODO 필드가 생겨요. TODO 바인딩의 모든 메서드는 ID가 06779da6940b431db6e566b4846d64db 인 KV 네임스페이스에 매핑돼요 — 이것은 앞서 My Tasks 라고 부른 네임스페이스예요.

export default {
  async fetch(request, env, ctx) {
    // Get the value for the "to-do:123" key
    // NOTE: Relies on the `TODO` KV binding that maps to the "My Tasks" namespace.
    let value = await env.TODO.get("to-do:123");

    // Return the value, as is, for the Response
    return new Response(value);
  },
};

로컬 개발 시 KV 바인딩 사용하기

wrangler dev 명령으로 로컬 개발을 위해 Wrangler를 사용할 때, Wrangler는 KV의 로컬 버전을 기본으로 사용해서 KV의 실제 프로덕션 데이터와 간섭되지 않도록 해요. 즉, 로컬로 쓰지 않은 키를 읽으면 null 이 반환돼요.

wrangler dev 가 Cloudflare의 글로벌 네트워크에서 실행 중인 Workers KV 네임스페이스에 연결하도록 하려면 KV 바인딩 설정에 "remote" : true 를 설정하세요. 자세한 내용은 원격 바인딩 문서를 참조하세요.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker",
	// ...
	"kv_namespaces": [
		{
			"binding": "TODO",
			"id": "06779da6940b431db6e566b4846d64db"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker"

[[kv_namespaces]]
binding = "TODO"
id = "06779da6940b431db6e566b4846d64db"

ES modules 형식으로 Durable Objects와 Workers에서 KV 접근하기

Durable Objects는 ES modules 형식을 사용해요. 전역 변수 대신, 바인딩은 생성자에 전달되는 env 매개변수의 속성으로 사용할 수 있어요.

예시는 다음과 같을 수 있어요:

import { DurableObject } from "cloudflare:workers";

export class MyDurableObject extends DurableObject {
  constructor(ctx, env) {
    super(ctx, env);
  }

  async fetch(request) {
    const valueFromKV = await this.env.NAMESPACE.get("someKey");
    return new Response(valueFromKV);
  }
}

더 알아보기 (Learn more)

KV 네임스페이스의 개념과 생성·바인딩 방법은 KV 네임스페이스 문서를 참고하세요. 읽기/쓰기 API 사용법은 각 API 문서에서 확인할 수 있어요.