Cloudflare Workers MySQL 연결 방법: Hyperdrive와 mysql2 설정

상황별 바로가기: 드라이버부터 설정 · 원격 조회 확인 · 연결·조회 오류 진단

Cloudflare는 2026년 10월 14일 MySQL 지원 정식 제공을 발표했습니다. 발표에 나온 드문 빈 결과 문제는 베타 기간에 수정한 과거 버그입니다. MySQL 정식 제공 발표

연결 구조와 DB 접근 조건부터 확인

경로는 Worker의 mysql2 → Hyperdrive → 기존 MySQL입니다. Hyperdrive는 원본 DB와의 연결을 풀링하고, 설정에 따라 캐시 가능한 읽기 결과를 저장합니다. DB를 Workers 안으로 이전하는 방식은 아닙니다. 근거: Hyperdrive 연결 풀링

확인 대상	점검할 내용
원본 DB	MySQL 버전·DB명·접속 호스트·포트
네트워크	Hyperdrive에서 접근 가능한 주소와 방화벽 규칙
TLS	원본 DB가 암호화 연결을 허용하는지, 인증서 설정이 맞는지
계정	시험용 테이블을 조회할 전용 DB 사용자
Worker	바인딩 이름·ID·호환성 날짜·설치된 드라이버

공식 지원 표는 MySQL 5.7~8.x와 MySQL 호환 서비스 등을 안내합니다. 실제 서버 버전과 제공자의 제약도 함께 확인하세요. 지원 DB 목록 이 글의 생성 명령은 공개 접근 경로가 있는 시험용 DB를 기준으로 합니다. 사설 IP를 그대로 넣는 대신 별도 사설 연결 구성을 확인해야 합니다. 공개 DB 연결 전제와 사설 연결 안내

공개 경로를 사용해도 모든 IP를 무조건 허용할 필요는 없습니다. 공식 네트워크 문서를 보고 Cloudflare의 접속 범위에 맞춰 방화벽을 구성하세요. 원본 DB는 TLS를 지원해야 하며 인증서를 무시하는 설정을 연결 해결책으로 삼지 않습니다. 방화벽 안내 · TLS·인증서 안내

1단계: mysql2·Wrangler 실제 버전 기록

공식 MySQL 연결 문서는 mysql2 3.13.0 이상과 Promise API를 안내합니다. 최소 지원 버전은 호환성 기준이며, 최신 보안 업데이트를 뜻하지 않습니다. 설치 후에는 실제 버전과 패키지 잠금 파일을 보관하세요. 근거: 드라이버 최소 버전

새 시험용 프로젝트를 만드는 npm 예시입니다. 기존 Workers 프로젝트가 있다면 해당 프로젝트에서 필요한 의존성만 추가합니다.

mkdir hyperdrive-mysql-check
cd hyperdrive-mysql-check
npm init -y
npm install 'mysql2@^3.13.0'
npm install --save-dev wrangler
mkdir -p src
node --version
npx wrangler --version
npm ls mysql2 wrangler --depth=0

이 명령은 3.x 범위를 설치합니다. 4.x를 선택할 때에는 지원 조건을 다시 확인하세요. 최소 지원 버전과 실제 설치 버전은 다르므로 npm ls 결과를 남깁니다.

2단계: nodejs_compat는 compatibility_date와 함께 판단

“mysql2에는 무조건 nodejs_compat 한 줄을 추가한다”로 기억하기보다 호환성 날짜를 먼저 보세요. 현재 Node.js 호환성 문서의 기준은 다음과 같습니다. 근거: 날짜별 Node.js 호환성

compatibility_date	설정 판단
2026-08-04 이상	Node.js 호환성이 기본 활성화. 새 설정에는 긍정 플래그 생략 가능
2024-09-23~2026-08-03	compatibility_flags에 nodejs_compat 추가
그보다 오래된 프로젝트	기존 호환성 설정을 조사하고 별도 환경에서 날짜 변경·회귀 검증

기존 프로젝트가 날짜를 올릴 때 긍정 플래그를 반드시 지울 필요는 없습니다. 반대로 no_nodejs_compat·no_nodejs_compat_v2 같은 제외 설정이 있으면 함께 확인하세요. 호환성 날짜는 단순한 작성일이 아니라 런타임 동작을 선택하므로 운영 프로젝트의 날짜를 바로 바꾸기보다 테스트 환경에서 검증합니다.

3단계: Hyperdrive 생성과 MySQL 연결 문자열

원본 URL의 형식은 mysql://사용자:비밀번호@호스트:3306/DB명입니다. 원본 자격증명은 Hyperdrive 설정에 등록하고, Worker 코드는 바인딩에서 제공하는 접속 정보를 사용합니다. 두 정보의 호스트·비밀번호를 섞지 마세요. 근거: 생성·접속 정보 제공 방식

아래 명령을 실행하기 전에 HYPERDRIVE_ORIGIN_URL 환경변수에 시험용 DB의 실제 연결 URL을 안전하게 준비합니다. URL·비밀번호를 저장소나 캡처에 남기지 마세요. 첫 구성은 캐시를 끄고, 두 번째는 같은 DB에 캐시 비교용으로 만듭니다.

npx wrangler login
npx wrangler hyperdrive create mysql-fresh \
  --connection-string="$HYPERDRIVE_ORIGIN_URL" \
  --caching-disabled
npx wrangler hyperdrive create mysql-cached \
  --connection-string="$HYPERDRIVE_ORIGIN_URL" \
  --max-age=60 --swr=0

비교용 캐시 설정은 max-age 60초·swr 0초를 선택했습니다. 모든 구성의 기본값을 의미하는 것은 아닙니다. 각 생성 결과의 ID와 캐시 설정을 기록합니다. 원본 인증서에 별도 CA나 호스트 검증이 필요하면 해당 TLS 구성도 적용해야 합니다. 근거: 생성·캐시·TLS 옵션

구성 두 개는 DB도 두 개 만든다는 뜻이 아닙니다. 같은 DB를 바라보는 Hyperdrive 구성이며 원본에 유지하는 연결 수는 함께 고려해야 합니다. 근거: 캐시·비캐시 구성 병행

4단계: Wrangler Hyperdrive 바인딩 설정

wrangler.jsonc 예제를 프로젝트 루트에 저장하고 두 ID를 실제 생성 결과로 바꾸세요. 기존 설정은 덮어쓰지 말고 필요한 항목을 병합합니다. 아래 ID 문자열은 자리표시자라서 그대로 배포할 수 없습니다.

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "hyperdrive-mysql-check",
  "main": "src/index.mjs",
  "compatibility_date": "2026-10-16",
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE_FRESH",
      "id": "REPLACE_WITH_CACHE_DISABLED_CONFIG_ID"
    },
    {
      "binding": "HYPERDRIVE_CACHE",
      "id": "REPLACE_WITH_CACHE_ENABLED_CONFIG_ID"
    }
  ]
}

예제 날짜는 새 시험용 프로젝트 기준이어서 nodejs_compat를 생략했습니다. 바인딩 이름은 코드의 env.HYPERDRIVE_FRESH·env.HYPERDRIVE_CACHE와 정확히 일치해야 합니다. env 이름에는 DB 원본 URL을 직접 넣는 것이 아니라 생성한 Hyperdrive 리소스를 연결합니다. 근거: Worker 바인딩

5단계: 한글·이모지를 넣을 시험용 데이터 준비

쓰기 작업은 전용 시험 DB에서 준비 담당 계정으로 수행하고, Worker의 계정에는 이 예제에 필요한 조회 권한을 부여합니다. prepare-probe.sql은 같은 이름의 테이블이 이미 있으면 생성에 실패하도록 작성해 기존 테이블에 데이터를 덮어 넣지 않습니다.

SET NAMES utf8mb4;
CREATE TABLE hyperdrive_connection_probe (
  id INT PRIMARY KEY,
  note VARCHAR(80) CHARACTER SET utf8mb4 NOT NULL,
  revision INT NOT NULL
);
INSERT INTO hyperdrive_connection_probe (id, note, revision)
VALUES (1, '안녕하세요 🌏', 1);
COMMIT;
SELECT id, note, revision FROM hyperdrive_connection_probe WHERE id = 1;

원본 DB에 직접 연결한 클라이언트로 실행하고, 저장한 문자열과 revision 1이 조회되는지 확인하세요. utf8mb4는 보조 평면 문자까지 지원합니다. 연결과 열의 문자 집합을 함께 확인해야 이모지 저장·전달을 검증하기 쉽습니다. 근거: MySQL utf8mb4

6단계: mysql2 연결·조회 코드 적용

전체 Worker 코드 index.mjs를 src/index.mjs에 저장합니다. /db-check에서 고정된 두 쿼리만 실행하는 임시 점검용 코드입니다. 첫 쿼리는 한글·이모지 파라미터를 되돌려 받고, 두 번째는 준비한 행을 읽습니다. URL로 임의 SQL을 받지 않습니다.

핵심 연결 부분은 다음과 같습니다. binding에는 mode에 따라 선택한 Hyperdrive 바인딩이 들어갑니다. 아래 발췌만 배포하지 말고 인증·오류 처리·연결 정리가 포함된 전체 파일을 사용하세요.

import { createConnection } from 'mysql2/promise';

// 요청 핸들러 안에서 선택한 binding으로 연결
const connection = await createConnection({
  host: binding.host,
  user: binding.user,
  password: binding.password,
  database: binding.database,
  port: binding.port,
  disableEval: true,
  charset: 'utf8mb4',
});
const [echoRows] = await connection.query(
  'SELECT ? AS echoed', ['Workers 한글 🌏'],
);
const [rows] = await connection.query(
  'SELECT id, note, revision FROM hyperdrive_connection_probe WHERE id = ?',
  [1],
);

공식 mysql2 예제는 요청마다 연결을 만들고 disableEval: true를 지정합니다. 원본 연결 풀은 Hyperdrive가 관리하므로, 연결을 전역 변수에 보관해 다른 요청에서 재사용하지 않습니다. mysql2 연결 예제 · 요청 간 I/O 오류 설명

charset은 mysql2가 제공하는 연결 옵션입니다. 전체 코드는 finally에서 연결 종료를 시도하고, 오류 응답에는 원본 주소·비밀번호·SQL 메시지를 노출하지 않도록 작성했습니다. 근거: mysql2 연결 옵션

호출에는 DB_CHECK_TOKEN과 일치하는 Bearer 토큰이 필요합니다. 이것은 임시 HTTP 점검 경로를 제한하는 앱 토큰이며 DB 비밀번호가 아닙니다. 비어 있으면 503을 반환합니다. 시험이 끝나면 경로·토큰을 정리하고 실제 서비스에는 사용자 인증과 권한 검사를 적용하세요.

로컬 성공과 원격 Hyperdrive 검증을 구분

실행 방식	DB 경로	확인할 수 있는 것
wrangler dev + localConnectionString	로컬 Worker → 지정한 DB 직접 연결	코드·드라이버 동작. Hyperdrive 풀링·캐시 검증은 제외
wrangler dev --remote	Cloudflare에서 원격 Hyperdrive 사용	원격 바인딩·원본 접근·풀링·캐시를 시험
테스트 Worker 배포	배포 Worker → Hyperdrive → DB	배포된 설정과 실제 결과를 함께 기록

로컬 직접 연결은 다음 두 환경변수에 각각 로컬 개발용 DB URL을 설정할 수 있습니다. 로컬에서 두 이름을 써도 Hyperdrive 캐시가 비교되는 것은 아닙니다. --remote는 원격 리소스를 사용하므로 시험용 DB를 대상으로 해야 합니다. 근거: 로컬·원격 개발 동작

• CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE_FRESH
• CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE_CACHE

아래는 별도 테스트 Worker를 배포해서 확인하는 흐름입니다. 설정과 데이터 준비 후 실행하세요. secret put은 새 Worker 버전을 즉시 배포하므로 시험용 프로젝트에서 사용합니다.

npx wrangler deploy
npx wrangler secret put DB_CHECK_TOKEN

secret put의 입력 창에 충분히 긴 무작위 토큰을 넣습니다. 로컬 개발용 토큰은 .dev.vars 등에 별도로 준비하고 버전 관리에서 제외하세요. 근거: Workers 비밀값 설정 호출하는 셸에도 같은 DB_CHECK_TOKEN 값을 준비해야 합니다. Worker에 저장한 값이 셸로 자동 전달되지는 않습니다.

# deploy 결과의 실제 주소로 교체
hyperdrive_check_origin='https://hyperdrive-mysql-check.YOUR-SUBDOMAIN.workers.dev'
curl --fail-with-body --show-error \
  -H "Authorization: Bearer ${DB_CHECK_TOKEN}" \
  "${hyperdrive_check_origin}/db-check?mode=fresh"

아래는 초기 데이터로 시험할 때의 기대값이며 실제 조회 응답이 아닙니다. HTTP 200과 내용 일치를 함께 확인하세요.

응답 항목	초기 기대값	다르면 확인할 것
mode	fresh	요청 쿼리와 캐시 비활성 구성 ID
echo	Workers 한글 🌏	파라미터 전달·연결 문자 집합
rows	id 1인 행 한 개	원본 DB·테이블·행 준비 여부
rows[0].note / revision	안녕하세요 🌏 / 1	원본 직접 조회·커밋·실제 바인딩 대상

여기까지 맞으면 원격 연결과 기본 조회를 기록한 뒤 캐시 비교로 넘어갑니다. 401·503·502이면 오류 단계별 표에서 먼저 원인을 좁히세요.

캐시 결과와 원본 MySQL 결과 비교하기

캐시가 켜져 있으면 모든 SELECT가 항상 원본까지 가는 것은 아닙니다. 특히 쓰기 이후 기존 읽기 캐시가 자동으로 무효화되는 구조가 아니므로, 최신 결과가 필요한 경로에는 캐시를 끈 구성을 사용합니다. 근거: 읽기 캐시와 read-after-write 동작

1. 원본 직접 조회와 fresh 경로에서 초기 revision 1·문자열을 확인합니다.
2. 동일 위치에서 cached 경로를 호출해 초기 결과를 읽고 시각을 적습니다.
3. update-probe.sql을 원본 DB에 직접 실행합니다. 전용 행의 note를 변경 확인 🚀, revision을 2로 바꾸고 커밋한 뒤 직접 조회합니다.
4. fresh 경로를 다시 호출해 변경한 값과 원본 결과를 대조합니다.
5. cached 경로는 같은 SQL·파라미터로 다시 호출하고 캐시 유지 시간 전후 결과를 기록합니다.

curl --fail-with-body --show-error \
  -H "Authorization: Bearer ${DB_CHECK_TOKEN}" \
  "${hyperdrive_check_origin}/db-check?mode=cached"

관측	판단할 내용
원본 2, fresh 2, cached 1	읽기 캐시의 이전 결과일 수 있으므로 설정·조회 시각 대조
원본 2, fresh 2, cached 2	캐시 미스·만료 등 가능. 캐시 비활성화의 증거로 단정하지 않기
원본 2, fresh 1	캐시 꺼진 ID인지, 같은 DB·행을 읽는지, 커밋했는지 확인
한글 정상, 이모지만 다름	연결·열·입력 클라이언트의 utf8mb4 설정과 원본 값 대조

위 표는 원인 후보를 좁히는 해석 기준이며 실제 관측 결과가 아닙니다. cached 경로가 새 값을 바로 반환할 수도 있습니다. SQL에 NOW()를 넣거나 주석을 바꿔 캐시를 피하려 하지 말고, 캐시를 끈 바인딩으로 비교하세요. HTTP 응답의 Cache-Control: no-store는 브라우저 등의 응답 캐시 설정이며 Hyperdrive 쿼리 캐시를 끄는 옵션이 아닙니다.

두 요청의 시간만으로 성능 향상률이나 캐시 적중을 판단할 수는 없습니다. 이 절차의 목적은 최신 원본과 캐시 결과의 정합성 비교입니다.

오류 로그는 생성 단계와 실행 단계로 나눠 확인

Hyperdrive 설정 생성 실패와 Worker에서 조회하다 난 오류는 다른 단계입니다. 공식 문제 해결 문서의 코드와 실제 기록을 맞춰 보세요. 근거: 구성·드라이버·런타임 오류 진단

단계·증상	먼저 확인할 것
생성 시 2008·2010·2011	DNS·호스트·포트·접근 경로·방화벽
생성 시 2012	원본 DB의 TLS 지원·설정
생성 시 2013·2014	자격증명과 실제 DB명
Code generation from strings disallowed for this context	mysql2 버전과 disableEval: true
Cannot perform I/O on behalf of a different request	전역 연결·이전 요청의 객체를 재사용하는지
이 예제의 503	DB_CHECK_TOKEN과 선택한 바인딩 누락
이 예제의 401	호출 토큰 일치 여부. DB 인증 오류와 구분
이 예제의 502	서버 로그의 connect·query 단계와 오류 code

원본 주소·전체 연결 URL·비밀번호·인증 헤더를 공개 로그에 넣지 말고, 버전·단계·오류 코드·시각·바인딩 이름을 기록하세요. 조회가 정상인데 서비스가 계속 느리다면 SQL 실행계획·DB 위치·연결 수와 Worker CPU를 나눠 조사합니다. Worker 쪽 병목은 Cloudflare Workers CPU 프로파일링과 Flamegraph 점검에서 이어서 볼 수 있습니다.

연결 확인 후 남길 자료와 이 글의 검증 범위

Hyperdrive MySQL 점검 기록표 CSV에 설치 버전·비밀값을 가린 바인딩·실제 조회 결과·한글과 이모지·캐시 비교를 남길 수 있습니다. 빈 양식이며 성공 결과를 미리 채워 두지 않았습니다.

완료 기록에는 원격 fresh 조회, 문자열 일치, 원본 갱신 후 revision 2 확인, 캐시 비교를 나눠 적으세요. 로컬 직접 연결만 했다면 원격 Hyperdrive는 미확인으로 남깁니다. mysql2·Wrangler 버전, 호환성 날짜나 캐시 설정을 바꾸면 이 기록을 기준으로 재검증할 수 있습니다.

자주 묻는 질문

Workers에서 mysql2만 설치하면 연결되나요?

아닙니다. 지원되는 드라이버와 런타임 호환성, Hyperdrive 구성·바인딩, 원본 DB의 네트워크·TLS·권한까지 맞아야 합니다. 공식 예제의 disableEval 설정과 요청 안에서 연결을 만드는 방식도 확인하세요.

compatibility_date에 따라 Node 호환성 설정이 달라지나요?

네. 현재 문서는 2026-08-04 이상에서 기본 활성화를, 2024-09-23~2026-08-03에서는 nodejs_compat 추가를 안내합니다. 오래된 프로젝트는 날짜 변경에 따른 다른 런타임 영향도 함께 시험해야 합니다.

캐시를 끄면 연결 풀링도 사라지나요?

아닙니다. Hyperdrive의 쿼리 캐시를 꺼도 연결 풀링은 유지됩니다. 최신 결과가 필요한 읽기는 캐시를 끈 바인딩으로, 잠시 이전 결과를 허용할 수 있는 읽기는 캐시 사용 바인딩으로 나눌 수 있습니다. 단, 로컬 직접 연결 모드에서는 Hyperdrive 풀링 자체가 적용되지 않습니다.