Cloudflare Workers에서 Python 앱을 기존 DB에 바로 연결하는 법

기존 데이터베이스는 그대로 두고 Cloudflare Workers만 연결합니다

이번 릴리스의 핵심은 데이터베이스를 옮기지 않아도 된다는 데 있습니다.

Hyperdrive는 Cloudflare Worker와 기존 PostgreSQL 또는 MySQL 데이터베이스 사이를 잇는 관리형 연결 계층입니다. 새 데이터베이스가 아니며, 레코드를 Cloudflare로 복사하지도 않습니다. Python 코드는 Hyperdrive 바인딩이 제공하는 연결 정보와 일반 데이터베이스 드라이버를 사용해 TCP 연결을 엽니다. 그 뒤 데이터베이스까지 이어지는 장기 연결 풀은 Hyperdrive가 관리합니다.

이로써 흔히 쓰이던 우회 구조가 달라집니다. 데이터베이스에 직접 연결할 수 없던 Python Worker는 SQL 실행만을 담당하는 작은 API나 서버를 호출하곤 했습니다. 연결 경로는 다음과 같았습니다.

기존: Python Worker → 데이터베이스 브리지 → PostgreSQL 또는 MySQL

현재: Python Worker → Hyperdrive → PostgreSQL 또는 MySQL

Cloudflare는 Worker 가까이에서 연결 설정을 처리하고, 오리진 데이터베이스 가까이에는 풀링된 연결을 유지합니다. Hyperdrive 가이드에 따르면 일반적인 구성에서는 첫 쿼리를 보내기 전까지 일곱 번의 왕복이 필요합니다. TCP에 한 번, TLS에 세 번, 데이터베이스 인증에 세 번입니다. 짧게 실행되는 Worker가 호출될 때마다 이 설정 과정을 되풀이하는 대신 기존 풀을 재사용할 수 있습니다.

지원 조건은 명확합니다. Python Workers에는 2026-09-08 이후 호환성 날짜가 필요하며, 이 기능은 아직 베타입니다. PostgreSQL용으로는 asyncpg, pg8000, psycopg가, MySQL용으로는 aiomysql, pymysql이 Cloudflare의 테스트를 거쳤습니다. 권장 드라이버는 asyncpg와 aiomysql입니다.

Cloudflare는 다른 TCP 드라이버도 작동할 수 있다고 설명합니다. 그렇다고 모든 패키지, ORM, 기존 애플리케이션의 작동을 보장하는 것은 아닙니다. 데이터베이스 호환성은 마이그레이션의 첫 관문일 뿐, 전체 통과를 의미하지 않습니다.

Cloudflare Workers 비용에서 달라지는 항목

이미 Python 앱을 Workers에서 운영하면서 데이터베이스 연결 때문에 브리지 비용만 따로 내고 있다면 가장 분명한 절감 효과를 기대할 수 있습니다.

계산은 간단합니다.

현재 월 비용 = 데이터베이스 + Worker + 브리지 호스트

가능한 월 비용 = 데이터베이스 + Worker

데이터베이스 비용은 그대로 남습니다. Hyperdrive의 기본 커넥션 풀링과 쿼리 캐싱은 Workers Paid에서 별도 요금이 없으며, Hyperdrive에는 이그레스 요금도 없습니다. 계정이 이미 Workers 기본 제공량 안에서 운영된다면 이 연결 경로 때문에 늘어나는 Cloudflare 비용은 $0입니다. 실제로 줄일 수 있는 현금 지출은 사라지는 브리지 호스트의 비용입니다.

유지보수도 같은 계산에 넣어야 합니다. 브리지를 제거하면 배포 하나, 상태 검사 하나, 시크릿 묶음 하나, 로그 스트림 하나, 장애 경계 하나도 함께 사라질 수 있습니다. 누가 관리하고 얼마나 자주 문제를 일으키는지 확인하기 전에는 그 작업에 임의의 금액을 매기지 않는 편이 좋습니다.

새 유료 계정의 Workers Paid는 계정당 월 $5부터 시작합니다. 매월 요청 1,000만 건과 CPU 시간 3,000만 밀리초가 포함됩니다. 초과분은 요청 100만 건마다 $0.30, CPU 시간 100만 밀리초마다 $0.02입니다. 이 플랜에서 Hyperdrive 데이터베이스 쿼리는 무제한으로 표시됩니다.

Free 플랜으로도 소규모 개념 검증을 진행할 수 있습니다. 하루 Worker 요청 100,000건과 Hyperdrive 데이터베이스 쿼리 100,000건이 포함되고, 호출당 CPU 시간은 10밀리초입니다. 두 항목은 별도로 집계됩니다. 요청 하나에서 SQL 문을 여러 번 실행하면 데이터베이스 쿼리도 여러 건 차감될 수 있습니다.

당장 적용할 수 있는 세 가지 사례

FastAPI 서비스를 운영하는 1인 창업자

관리형 PostgreSQL 데이터베이스 앞에 FastAPI Worker를 두고, HTTP 호출을 받아 SQL만 실행하는 작은 컨테이너를 함께 운영하는 상황을 가정해 보겠습니다. 그 컨테이너에 비즈니스 로직이 없다면 asyncpg 테스트로 Hyperdrive가 이를 대체할 수 있는지 확인할 수 있습니다.

새 데이터베이스를 얻는 것이 핵심은 아닙니다. 현재 스키마와 백업, 제공업체는 유지하면서 연결 어댑터 역할만 하던 서비스를 지우는 것이 이점입니다. 먼저 라우트 하나를 옮겨 결과와 지연 시간을 비교하고, 운영 환경의 동작이 일치한 뒤 브리지를 제거해야 합니다.

고객별 MySQL 데이터베이스를 관리하는 소규모 에이전시

소규모 에이전시는 각 고객의 MySQL 데이터베이스를 바라보는 작은 Python API 여러 개를 관리할 수 있습니다. 이제 조건에 맞는 앱마다 데이터베이스 프록시를 따로 배포하는 대신 Worker 안에서 aiomysql이나 pymysql을 테스트할 수 있습니다.

이점은 운영 방식을 통일할 수 있다는 데 있습니다. Worker 배포 경로는 하나로 맞추고, 데이터베이스마다 Hyperdrive 구성 하나를 둘 수 있습니다. 다만 브리지가 테넌트 권한 검증, 스키마 변환, 감사처럼 쿼리 전달 이상의 일을 한다면 그대로 유지해야 합니다.

읽기 요청이 많은 엔드포인트 하나만 옮기는 플랫폼 팀

플랫폼 팀이 백엔드 전체를 마이그레이션할 필요는 없습니다. 읽기 비중이 높은 공개 Python 엔드포인트 하나만 Workers로 옮기고 리전 데이터베이스는 유지한 채, Hyperdrive가 오리진 연결을 풀링하도록 구성할 수 있습니다.

이 경우 캐싱 정책을 명시적으로 결정해야 합니다. Hyperdrive는 기본적으로 조건에 맞는 읽기 결과를 60초 동안 캐시하며, 재검증 중에는 오래된 결과를 추가로 15초간 제공할 수 있습니다. 공개 카탈로그나 콘텐츠 조회라면 허용할 수 있습니다. 반면 인증, 권한, 결제 상태, 쓰기 직후의 읽기에는 캐시를 끈 별도 Hyperdrive 구성을 사용해야 합니다.

기존의 Django와 FastAPI 비교는 프레임워크 선택에도 여전히 도움이 됩니다. 이번 릴리스로 달라진 것은 판단 기준 중 한 부분입니다. PostgreSQL 또는 MySQL을 유지하는 방식이 이제 Python Worker의 공식 경로가 됐지만, 그렇다고 Django나 FastAPI 애플리케이션의 나머지 부분까지 인증된 것은 아닙니다.

가장 작은 안전 연결 테스트 만들기

운영용이 아닌 MySQL 데이터베이스와 권한이 제한된 테스트 사용자를 씁니다. 목표는 고객 데이터로 전체 마이그레이션을 예행연습하는 것이 아니라 SELECT 1로 연결 경로를 검증하는 것입니다.

첫 테스트에서 캐시를 거치지 않은 데이터베이스 왕복 시간을 측정할 수 있도록 캐시가 꺼진 Hyperdrive 구성을 만듭니다.

npx wrangler hyperdrive create python-db-test --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --caching-disabled

Wrangler가 반환한 구성 ID를 wrangler.toml에 복사합니다. 아래 날짜는 필수 기준인 2026-09-08보다 늦습니다.

name = "python-hyperdrive"
main = "src/main.py"
compatibility_date = "2026-09-16"
compatibility_flags = ["python_workers"]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<HYPERDRIVE_CONFIG_ID>"

pyproject.toml에 드라이버를 추가합니다.

[project]
dependencies = [
    "aiomysql",
]

이제 src/main.py에 Cloudflare가 문서로 안내한 연결 테스트를 작성합니다.

import aiomysql
from workers import Response, WorkerEntrypoint


class Default(WorkerEntrypoint):
    async def fetch(self, request):
        hd = self.env.HYPERDRIVE
        connection = await aiomysql.connect(
            host=hd.host,
            port=int(hd.port),
            user=hd.user,
            password=hd.password,
            db=hd.database,
            ssl=None,
        )
        try:
            cursor = await connection.cursor()
            await cursor.execute("SELECT 1")
            result = await cursor.fetchone()
            return Response.json({"result": result[0]})
        finally:
            connection.close()

문서에 나온 Python Workers 명령으로 배포합니다.

uv run pywrangler deploy

ssl=None은 언뜻 잘못된 설정처럼 보일 수 있습니다. Cloudflare 예시에서 이는 Worker와 Hyperdrive 사이의 드라이버 연결에 적용됩니다. Hyperdrive에서 오리진 데이터베이스로 이어지는 연결에는 여전히 TLS가 필요하며, 안전하지 않은 평문 오리진 연결은 지원되지 않습니다.

브리지는 선택 사항이 됐을 뿐, 저절로 쓸모없어지지는 않습니다

이번 출시는 연결 경로를 바꿨습니다. Python Workers를 제약 없는 CPython 서버로 바꾼 것은 아닙니다.

Python 패키지 지원 범위는 순수 Python 패키지, PyEmscripten 휠, Pyodide에 포함된 패키지입니다. Cloudflare는 WebAssembly 패키지 지원이 아직 초기 단계라고 밝히고 있어, 필요한 의존성 하나가 없으면 마이그레이션이 중단될 수 있습니다. 현재 드라이버 및 ORM 문서는 동기 SQLAlchemy만 지원합니다. Workers 환경에서 greenlet을 지원하지 않기 때문에 비동기 SQLAlchemy는 지원되지 않습니다.

데이터베이스 프로토콜에도 제약이 있습니다. Hyperdrive는 PostgreSQL 9.0부터 17.x, MySQL 5.7부터 8.x, 그리고 MariaDB를 지원합니다. SQL Server와 MongoDB는 지원하지 않습니다. PostgreSQL advisory lock과 LISTEN, NOTIFY도 사용할 수 없습니다. MySQL의 multi-statement query와 protocol-level prepared statement 역시 지원 범위 밖입니다. Free와 Paid 모두 쿼리 최대 실행 시간은 60초입니다.

풀링을 적용하면 세션에 대한 전제도 달라집니다. Hyperdrive는 트랜잭션 풀링을 사용하므로 트랜잭션이 끝나면 오리진 연결이 풀로 돌아갑니다. 트랜잭션 사이에도 세션 상태가 유지된다고 가정하는 코드는 검토가 필요합니다. 긴 트랜잭션은 풀을 소진해 동시성 이점을 없앨 수도 있습니다.

월요일에 할 일

월요일부터 애플리케이션 전체를 마이그레이션하지 마십시오. 데이터베이스 연결만 담당하는 브리지가 정말 필요한지부터 증명해야 합니다.

브리지가 데이터베이스 연결만 담당하고, 앱이 PostgreSQL 또는 MySQL을 사용하며, 검증된 드라이버로 해당 라우트를 처리할 수 있다면 이번 주에 움직일 수 있습니다. 비동기 SQLAlchemy, 사용할 수 없는 패키지, 지원되지 않는 SQL 동작에 의존하거나 엄격한 쓰기 후 읽기 일관성을 아직 분리하지 못했다면 기다려야 합니다. 앱을 현재 서버에 그대로 둘 예정이거나 브리지에 Hyperdrive가 대신할 수 없는 비즈니스 로직이 있다면 이번 변화의 영향을 받지 않습니다.

다음 플랫폼 변화도 월요일에 바로 실행할 판단으로 정리해 받아보려면 뉴스레터를 구독하세요.