ClickHouse Managed Postgres에서 Cloudflare Workers 사용하기

Hyperdrive를 통해 Cloudflare Worker에서 ClickHouse Managed Postgres에 쿼리하는 방법을 안내합니다. node-postgres 사용, 검증된 TLS 연결, 로컬 개발, workers.dev 배포까지 다룹니다

Cloudflare Workers는 Cloudflare 네트워크에서 코드를 실행하고, Hyperdrive는 이 네트워크에서 데이터베이스로 연결되는 연결 풀을 유지합니다. 따라서 요청할 때마다 TCP 및 TLS 핸드셰이크를 새로 수행하는 비용이 들지 않습니다. 이 가이드에서는 인스턴스의 인증서를 검증하는 Hyperdrive 구성을 생성하고, node-postgres(pg)로 행을 생성하고 읽는 TypeScript Worker를 빌드합니다. 그런 다음 wrangler dev로 로컬에서 실행하고 workers.dev에 배포합니다.

​

사전 요구 사항

• Cloudflare 계정. Hyperdrive는 Workers Free 및 Paid 요금제에서 모두 사용할 수 있습니다.
• Node.js 20 이상. 이 가이드는 Node.js 24.21.0, Wrangler 4.145.0, create-cloudflare 2.73.1, pg 8.23.1, Postgres 18 환경에서 테스트되었습니다.
• ClickHouse Cloud 계정.
• 데이터베이스와 테이블 생성에 사용할 psql. SQL 콘솔에서 SQL 문을 실행해도 됩니다.

​

ClickHouse Managed Postgres 서비스 생성

ClickHouse Cloud 콘솔에서 New service를 클릭한 후 Postgres를 선택하십시오. 몇 분 이내에 인스턴스가 준비됩니다. 단계별 안내는 빠른 시작 가이드를 참조하십시오.

​

연결 정보 확인

서비스의 왼쪽 사이드바에서 Connect를 클릭합니다. Directly를 선택된 상태로 두고 Use SSL을 켭니다. 그러면 URL 끝에 sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem이 추가됩니다. Download CA certificate를 클릭하여 인스턴스의 CA 인증서를 다운로드합니다. Settings → CA Certificate에서도 다운로드할 수 있습니다.

이 가이드에서는 Hyperdrive가 포트 6432의 번들 PgBouncer가 아닌 포트 5432의 직접(direct) 연결을 사용하도록 설정합니다.

• Hyperdrive는 그 자체가 트랜잭션 모드(transaction mode)로 동작하는 연결 풀러(connection pooler)입니다. 데이터베이스에 대한 소수의 장기 연결을 풀로 유지하면서 모든 Worker 요청이 이를 공유하도록 하므로, 원래 PgBouncer가 하던 역할을 대신합니다. Cloudflare에서도 Hyperdrive에는 풀링된 연결 문자열 대신 직접 연결 문자열을 지정할 것을 권장합니다.
• Hyperdrive가 포트 6432를 사용하도록 설정해도 동작은 하지만, 트랜잭션 풀러 2개를 연달아 두면 용량은 늘지 않고 네트워크 홉만 하나 늘어나며 풀 크기를 조정해야 할 곳도 한 군데 더 생깁니다.
• Hyperdrive는 구성당 Workers Free 요금제에서는 최대 약 20개, Paid 요금제에서는 최대 약 100개의 연결을 엽니다. 이는 기본 max_connections 값인 500을 넘지 않습니다. 동일한 인스턴스에 여러 Hyperdrive 구성이나 다른 클라이언트가 연결되어 있다면 전체 연결 수를 합산해 보고, 필요하면 설정에서 max_connections를 조정하거나 Hyperdrive의 오리진 연결 한도를 조정하십시오.

IP 액세스 목록을 사용한다면, Hyperdrive는 Cloudflare의 IP 범위에서 연결하므로 해당 범위를 허용해야 합니다.

​

데이터베이스 생성

다운로드한 인증서의 이름을 ca-certificate.pem으로 변경합니다. 그런 다음 데이터베이스와 notes 테이블을 생성합니다. <PASSWORD>와 호스트는 Connect 모달에 표시된 값으로 바꾸십시오.

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_cloudflare;"

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE TABLE notes (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, content text NOT NULL, created_at timestamptz NOT NULL DEFAULT now());"

CREATE TABLE

​

Worker 프로젝트 생성

create-cloudflare로 “Hello World” 템플릿 기반의 TypeScript Worker를 생성한 후 pg를 설치하세요:

npm create cloudflare@latest -- hyperdrive-notes --type=hello-world --lang=ts --no-deploy
cd hyperdrive-notes
npm install pg
npm install -D @types/pg

기존 앱에 추가하시나요?

npm create cloudflare는 건너뛰십시오. Worker 프로젝트에서 npm install pg와 npm install -D @types/pg를 실행한 다음, Hyperdrive 바인딩을 추가하는 Hyperdrive 구성 생성 단계와 nodejs_compat을 활성화하는 Worker 구성 단계로 이어서 진행하십시오.

ca-certificate.pem을 프로젝트 디렉터리로 옮기십시오. Wrangler를 처음 사용한다면 npx wrangler login을 실행하여 Cloudflare 계정에 대한 Wrangler 접근 권한을 부여하십시오.

​

Hyperdrive 구성 생성

Hyperdrive는 데이터베이스 연결을 항상 암호화하지만, 기본적으로는 인스턴스의 CA로 인증서를 검증하지 않습니다. sslmode=verify-full과 동일한 수준으로 검증하려면 먼저 CA 인증서를 Cloudflare 계정에 업로드하십시오.

npx wrangler cert upload certificate-authority --ca-cert ca-certificate.pem --name managed-postgres-ca

Success! Uploaded CA Certificate managed-postgres-ca
ID: <CA_CERTIFICATE_ID>

출력에 표시된 ID를 사용하여 Hyperdrive 구성을 생성하십시오. 연결 문자열(connection string)은 포트 5432와 guide_cloudflare 데이터베이스를 사용하며, SSL 매개변수는 포함하지 않습니다. TLS는 대신 --sslmode와 --ca-certificate-id로 구성합니다.

npx wrangler hyperdrive create managed-postgres \
  --connection-string="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare" \
  --ca-certificate-id <CA_CERTIFICATE_ID> \
  --sslmode verify-full \
  --caching-disabled \
  --binding HYPERDRIVE \
  --update-config

✅ Created new Hyperdrive PostgreSQL config: <HYPERDRIVE_ID>

Hyperdrive는 구성을 생성하는 과정에서 데이터베이스에 연결합니다. --sslmode verify-full을 사용하면 서버 인증서가 업로드한 CA로 서명되었는지, 그리고 호스트명과 일치하는지 확인합니다. 둘 중 하나라도 확인에 실패하면 명령은 cert verification failed - unable to get local issuer certificate와 같은 오류를 반환하며 실패하고, 구성은 생성되지 않습니다. 비밀번호는 프로젝트가 아닌 Cloudflare 계정의 Hyperdrive 구성에 저장됩니다.

--binding HYPERDRIVE --update-config를 지정하면 구성이 wrangler.jsonc에 추가되므로 Worker에서 env.HYPERDRIVE로 접근할 수 있습니다. 프로젝트에서 wrangler.toml을 사용한다면 Wrangler가 해당 파일을 변경하지 않으므로, 명령이 출력하는 [[hyperdrive]] 스니펫을 파일에 직접 붙여 넣으십시오.

쿼리 캐싱

Hyperdrive는 읽기 쿼리의 결과를 캐시할 수 있으며, 기본 캐시 시간은 60초입니다. 이 가이드에서는 --caching-disabled로 캐싱을 끄므로 쓰기 직후에 읽으면 새 행이 반환됩니다. 약간 오래된 결과가 허용되는 읽기 위주의 쿼리가 있다면 캐싱을 켠 두 번째 구성을 생성하고 두 구성을 모두 바인딩할 수 있습니다. 자세한 내용은 쿼리 캐싱을 참조하십시오.

​

Worker 구성하기

pg를 사용하려면 Node.js 호환성 계층이 필요합니다. wrangler.jsonc를 열고 compatibility_date 옆에 nodejs_compat 플래그를 추가하십시오. 추가하고 나면 파일의 해당 부분은 다음과 같습니다.

wrangler.jsonc

{
	"name": "hyperdrive-notes",
	"main": "src/index.ts",
	"compatibility_date": "2026-09-26",
	"compatibility_flags": ["nodejs_compat"],
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<HYPERDRIVE_ID>"
		}
	]
}

wrangler.toml 파일을 사용한다면 compatibility_date 아래에 compatibility_flags = ["nodejs_compat"]를 대신 추가하세요. 파일에 이미 compatibility_flags가 있다면 해당 목록에 nodejs_compat를 추가하세요.

env.HYPERDRIVE에 타입이 지정되도록 TypeScript 타입을 다시 생성하세요:

npx wrangler types

프로젝트에서 아직 @cloudflare/workers-types 패키지를 사용하고 있다면 wrangler types 명령이 생성된 타입으로 전환하는 방법을 안내합니다.

​

데이터베이스 쿼리하기

src/index.ts를 POST /notes 요청 시 노트를 생성하고 GET /notes 요청 시 모든 노트를 조회하는 Worker로 교체하세요. 기존 Worker가 있다면 대신 fetch 핸들러에 동일한 /notes 처리 로직을 추가하세요.

src/index.ts

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname !== "/notes") {
			return new Response("Not found", { status: 404 });
		}

		// Hyperdrive keeps the connections to Postgres, so a new client per request is cheap.
		const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
		await client.connect();

		try {
			if (request.method === "POST") {
				// Create
				const { content } = await request.json<{ content: string }>();
				const { rows } = await client.query(
					"INSERT INTO notes (content) VALUES ($1) RETURNING id, content, created_at",
					[content],
				);
				return Response.json(rows[0], { status: 201 });
			}

			// Read
			const { rows } = await client.query("SELECT id, content, created_at FROM notes ORDER BY id");
			return Response.json(rows);
		} finally {
			// Close the client after the response is sent.
			ctx.waitUntil(client.end());
		}
	},
} satisfies ExportedHandler<Env>;

env.HYPERDRIVE.connectionString은 인스턴스가 아니라 Hyperdrive를 가리킵니다. Worker와 Hyperdrive 간의 연결은 Cloudflare 내부에서만 이루어지므로 SSL 매개변수가 필요하지 않습니다. Postgres로의 검증된 TLS 연결은 Hyperdrive가 처리합니다.

Hyperdrive는 PgBouncer와 마찬가지로 트랜잭션 모드로 실행되므로, 트랜잭션마다 Postgres에 대해 서로 다른 연결을 사용할 수 있습니다. pg의 매개변수화된 쿼리, 트랜잭션, 이름이 지정된 prepared statement는 모두 정상적으로 동작합니다. 다만 세션 수준의 SET과 같은 세션 상태가 여러 쿼리에 걸쳐 유지된다고 가정해서는 안 됩니다. 대신 트랜잭션 내부에서 SET LOCAL을 사용하십시오.

​

로컬에서 실행하기

wrangler dev를 사용하면 Worker를 로컬 머신에서 실행할 수 있습니다. 로컬 환경에서는 Hyperdrive가 연결을 풀링하지 않으며, 바인딩은 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>에 지정된 데이터베이스에 직접 연결됩니다. 이 변수에 sslmode=verify-full과 CA 인증서 경로를 포함한 직접 연결 문자열을 설정한 다음 Worker를 시작하세요:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare?sslmode=verify-full&sslrootcert=ca-certificate.pem"
npx wrangler dev --port 3108

Found a non-empty CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE variable for binding. Hyperdrive will connect to this database during local development.
...
Ready on http://localhost:3108

Wrangler가 로컬 연결의 TLS를 처리합니다. sslrootcert는 wrangler dev를 실행한 디렉터리를 기준으로 한 상대 경로로 해석됩니다.

sslmode를 생략하면 로컬 연결이 암호화되지 않습니다. sslmode=require를 사용하면 연결은 암호화되지만 인증서는 검증되지 않습니다. 반드시 sslmode=verify-full과 sslrootcert를 함께 사용하십시오. CA가 없거나 잘못된 경우 요청이 Connection terminated unexpectedly 오류를 내며 실패합니다.

다른 터미널을 하나 더 열어 노트를 생성하세요:

curl -X POST http://localhost:3108/notes -H "Content-Type: application/json" -d '{"content": "Hello from wrangler dev"}'

{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"}

노트 목록을 조회합니다.

curl http://localhost:3108/notes

[{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"}]

pg는 bigint 컬럼을 문자열로 반환하므로 id 값은 1이 아니라 "1"입니다.

​

배포

Worker를 배포합니다.

npx wrangler deploy

Your Worker has access to the following bindings:
Binding                                   Resource
env.HYPERDRIVE (<HYPERDRIVE_ID>)          Hyperdrive Config

Uploaded hyperdrive-notes (2.35 sec)
Deployed hyperdrive-notes triggers (0.76 sec)
  https://hyperdrive-notes.<your-subdomain>.workers.dev

Worker를 처음 생성하는 경우 Wrangler에서 workers.dev 하위 도메인을 등록하라는 메시지가 표시됩니다. 배포된 Worker를 통해 노트를 생성하십시오:

curl -X POST https://hyperdrive-notes.<your-subdomain>.workers.dev/notes -H "Content-Type: application/json" -d '{"content": "Hello from Hyperdrive"}'

{"id":"2","content":"Hello from Hyperdrive","created_at":"2026-09-30T16:58:39.733Z"}

브라우저에서 https://hyperdrive-notes.<your-subdomain>.workers.dev/notes를 열면 두 노트를 모두 확인할 수 있습니다. 응답은 다음과 같습니다.

[{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"},{"id":"2","content":"Hello from Hyperdrive","created_at":"2026-09-30T16:58:39.733Z"}]

​

콘솔에서 확인

서비스의 왼쪽 사이드바에서 SQL 콘솔을 열고 guide_cloudflare와 public을 차례로 펼친 다음 notes 테이블을 클릭하세요. 두 노트가 모두 표시됩니다.

id	content	created_at
1	Hello from wrangler dev	2026-09-30 16:58:16.232466+00
2	Hello from Hyperdrive	2026-09-30 16:58:39.733203+00

​

정리

Cloudflare 계정에서 생성한 리소스를 제거하려면 Worker, Hyperdrive 구성, CA 인증서를 삭제하십시오.

npx wrangler delete
npx wrangler hyperdrive delete <HYPERDRIVE_ID>
npx wrangler cert delete --name managed-postgres-ca

wrangler cert delete 실행 시 Certificate cannot be deleted while in use 오류가 발생하면 Hyperdrive 구성을 삭제한 후 1분 정도 기다렸다가 다시 실행하십시오.

​

다음 단계

• 연결: 연결 문자열(connection string), PgBouncer, TLS
• 설정: max_connections 등의 Postgres 매개변수
• 읽기 레플리카(Read replica): 읽기 트래픽 확장
• Hyperdrive 문서: 쿼리 캐싱, 연결 풀 튜닝, 관측성