본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

Query D1 from Python Workers (Python Workers에서 D1 쿼리하기)

원문 보기 위키 갱신

이 문서는 Python Worker에서 D1 데이터베이스를 쿼리하고 애플리케이션을 전역으로 배포하는 방법을 설명해요.

출처: 문서

본문

Cloudflare Workers 플랫폼은 TypeScript, JavaScript, Rust, Python을 포함한 여러 언어를 지원해요. 이 가이드는 Python에서 D1 데이터베이스를 쿼리하고 애플리케이션을 전역으로 배포하는 방법을 보여줘요.

사전 요구 사항 (Prerequisites)

시작하기 전에 다음을 해 두세요:

  1. TypeScript와 JavaScript용 D1 튜토리얼을 검토해 D1 데이터베이스를 만들고 Workers 프로젝트를 구성하는 방법을 배우세요.
  2. Python 언어 가이드를 참고해 Workers 플랫폼에서 Python 지원이 어떻게 동작하는지 이해하세요.
  3. Python 언어에 대한 기본적인 친숙함을 갖추세요.

Cloudflare Workers가 처음이라면, 이 예시를 계속하기 전에 시작하기 가이드를 먼저 참고하세요.

Python에서 쿼리하기 (Query from Python)

이 예시는 기존 D1 데이터베이스가 있다고 가정해요. Python Worker가 데이터베이스를 쿼리할 수 있게 하려면 먼저 Worker와 D1 데이터베이스 사이에 바인딩을 만들고, 이것을 Wrangler 설정 파일에 정의해야 해요.

D1 데이터베이스의 database_name과 database_id가 필요해요. wrangler CLI를 사용해 새 데이터베이스를 만들거나, 다음과 같이 기존 데이터베이스의 ID를 가져올 수 있어요:

데이터베이스 만들기

npx wrangler d1 create my-first-db

데이터베이스 ID 검색

npx wrangler d1 info some-existing-db

# ┌───────────────────┬──────────────────────────────────────┐
# │                   │ c89db32e-83f4-4e62-8cd7-7c8f97659029 │
# ├───────────────────┼──────────────────────────────────────┤
# │ name              │ db-enam                              │
# ├───────────────────┼──────────────────────────────────────┤
# │ created_at        │ 2023-06-12T16:52:03.071Z             │
# └───────────────────┴──────────────────────────────────────┘

1. 바인딩 구성하기 (Configure bindings)

Wrangler 파일에서 새 [[d1_databases]] 구성 블록을 만들고, database_name과 database_id를 쿼리하려는 D1 데이터베이스의 이름과 id(각각)로 설정하세요:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "python-and-d1",
	"main": "src/entry.py",
	"compatibility_flags": [ // Required for Python Workers
		"python_workers"
	],
	// Set this to today's date
	"compatibility_date": "2026-10-07",
	"d1_databases": [
		{
			"binding": "DB", // This will be how you refer to your database in your Worker
			"database_name": "YOUR_DATABASE_NAME",
			"database_id": "YOUR_DATABASE_ID"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "python-and-d1"
main = "src/entry.py"
compatibility_flags = [ "python_workers" ]
# Set this to today's date
compatibility_date = "2026-10-07"

[[d1_databases]]
binding = "DB"
database_name = "YOUR_DATABASE_NAME"
database_id = "YOUR_DATABASE_ID"

binding의 값은 Worker 안에서 데이터베이스를 참조하는 방법이에요. 이 값을 바꾸면 Worker 스크립트에서도 똑같이 바꿔야 해요.

2. Python Worker 만들기 (Create your Python Worker)

Python Worker를 만들려면 src/entry.py에 빈 파일을 만들고, Wrangler 파일의 main 값에 맞춰 아래 내용을 채우세요:

from workers import Response, WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # Do anything else you'd like on request here!

        try:
            # Query D1 - we'll list all tables in our database in this example
            results = await self.env.DB.prepare("PRAGMA table_list").run()
            # Return a JSON response
            return Response.json(results)
        except Exception as e:
            return Response.json({"error": "Database query failed"}, status=500)

Wrangler 파일의 binding 값은 Python 코드의 변수 이름과 정확히 일치해야 해요. 이 예시는 DB 바인딩을 통해 데이터베이스를 참조하고, await self.env.DB.prepare(...)로 이 바인딩을 쿼리해요.

그런 다음 Python Worker를 바로 배포할 수 있어요:

npx wrangler deploy

# Example output
#
# Your worker has access to the following bindings:
# - D1 Databases:
#   - DB: db-enam (c89db32e-83f4-4e62-8cd7-7c8f97659029)
# Total Upload: 0.18 KiB / gzip: 0.17 KiB
# Uploaded python-and-d1 (4.93 sec)
# Published python-and-d1 (0.51 sec)
#   https://python-and-d1.YOUR_SUBDOMAIN.workers.dev
# Current Deployment ID: 80b72e19-da82-4465-83a2-c12fb11ccc72

Worker는 https://python-and-d1.YOUR_SUBDOMAIN.workers.dev에서 사용할 수 있게 돼요.

배포 중 오류가 발생하면:

  • Wrangler 설정 파일에 유효한 D1 데이터베이스의 database_id와 database_name이 구성되어 있는지 확인하세요.
  • Wrangler 설정 파일에 Python에 필요한 compatibility_flags = ["python_workers"]가 설정되어 있는지 확인하세요.
  • 오류 코드 목록을 검토하고 코드가 포착되지 않은 예외를 던지지 않는지 확인하세요.

다음 단계 (Next steps)