Michael JohnsonCloudflare D1 쿼리가 50MB를 초과하는 결과를 반환하면 2026년 11월 4일부터 오류가 발생합니다. 개발자에게 중요한 점은 이 변경의 범위입니다. 제한은 데이터베이스의 최대 크기가 아니라 개별 쿼리 결과의 크기에 적용됩니다. REST API를 통한 데이터 가져오기와 내보내기는 이 제한에 해당하지 않으므로, 데이터를 읽는 방식에 따라 작업 흐름을 바꿔야 할지가 결정됩니다.
무엇이 제한되나요?
Cloudflare는 10월 30일 게시물에서 결과가 50MB를 초과하는 쿼리는 D1 query result exceeded the maximum response size limit of 50 MB 오류를 반환한다고 밝혔습니다. 적용 시작일은 2026년 11월 4일입니다. D1 문서에도 쿼리 결과 크기 제한이 명시되어 있으며, 데이터베이스 자체는 유료 요금제에서 최대 10GB, 무료 요금제에서 최대 500MB까지 저장할 수 있습니다.
이 둘은 서로 다른 층위의 제한입니다. 저장 용량은 데이터베이스에 저장할 수 있는 데이터의 양을 정하고, 결과 제한은 한 번의 쿼리가 반환할 수 있는 데이터의 양을 정합니다. 따라서 데이터베이스에 50MB를 훨씬 넘는 데이터를 저장해도 필요한 부분을 나눠 읽을 수 있습니다. 반대로 규모가 작은 데이터베이스라도 폭이 넓은 행을 많이 선택하거나 대용량 텍스트 및 바이너리 필드를 포함하면 쿼리 결과가 제한을 넘을 수 있습니다.
Cloudflare의 제한 발표에 따르면 이 임계값은 D1 쿼리 분포의 99.999 백분위수에 해당합니다. 이는 공급업체가 제시한 쿼리 분포 추정치입니다. 실제 적용을 검토할 때는 앱의 개별 응답을 측정하고 대량의 데이터를 반환하는 쿼리를 찾아내는 것이 더 중요합니다.
REST API를 통한 내보내기는 왜 별도일까요?
일반적으로 애플리케이션 쿼리는 SQL 실행 결과를 받아 호출 코드에 전달합니다. REST API를 통한 데이터베이스 가져오기와 내보내기는 별도의 작업입니다. Cloudflare는 이 작업에는 새 임계값이 적용되지 않으며 기존 방식대로 계속 이용할 수 있다고 밝혔습니다. 따라서 대량 조회에서 오류가 발생하더라도 데이터베이스에서 대용량 데이터를 내보낼 수 없다는 뜻은 아닙니다.
이 차이를 이해하면 적절한 데이터 처리 방식을 선택하는 데 도움이 됩니다. 앱에서 화면 표시, 처리 또는 보고서 작성을 위해 모든 레코드가 필요하다면 조회를 여러 묶음으로 나누세요. 데이터 이전이나 내보내기가 목적이라면 하나의 SQL 응답으로 전체 데이터베이스를 가져오려 하기보다 REST API를 통한 내보내기 방식을 확인하세요.
필요한 데이터를 잃지 않고 응답 크기를 줄이는 방법
첫 번째 방법은 필요 없는 열을 제외하는 것입니다. SELECT * 대신 현재 작업에 필요한 필드만 지정하세요. 테이블에 긴 설명, JSON 또는 BLOB 값이 들어 있다면 특히 응답 크기를 줄일 수 있습니다.
두 번째 방법은 Cloudflare의 권장대로 LIMIT와 OFFSET을 사용해 행을 나눠 읽는 것입니다. 예를 들어 인터페이스는 사용자가 스크롤할 때 다음 페이지를 가져오고, 배치 작업은 데이터 묶음별로 처리할 수 있습니다. 고유 식별자와 같은 기준으로 안정적인 정렬을 추가하세요. 정렬이 없으면 쿼리 사이에 데이터가 바뀔 때 페이지 경계가 달라질 수 있습니다.
장시간 실행되는 내보내기 작업에서는 마지막으로 처리한 레코드의 체크포인트도 저장하는 것이 좋습니다. 그러면 작업이 중단된 뒤 전체 데이터 세트를 다시 처리하지 않고 이어서 진행할 수 있습니다. 구체적인 방식은 애플리케이션에 따라 다르지만, 핵심은 한 번에 전체 데이터 세트를 반환하는 단일 쿼리에 의존하지 않고 각 응답의 크기를 제한하는 것입니다.
애플리케이션에서 확인할 항목
보고서용 내보내기, 관리 화면, 백그라운드 작업, 여러 행을 배열로 반환하는 API 경로처럼 큰 목록을 가져오는 쿼리부터 확인하세요. 일시적으로 직렬화된 응답의 크기나 선택한 필드의 개수와 크기를 기록해 보세요. 그런 다음 일반적인 소규모 테스트 데이터만이 아니라 예상 가능한 최대 데이터 규모도 확인하세요.
변경 사항 적용 후 애플리케이션에서 오류가 발생하면 D1 문서는 결과 크기가 50MB를 초과한 경우와 연관된 오류라고 설명하며, 필요한 열만 선택하거나 결과를 페이지 단위로 나누도록 권고합니다. 이렇게 하면 응답 크기 문제를 실행 시간, 메모리 또는 데이터베이스 가용성 제한과 구분할 수 있습니다. 이러한 제한에는 각각 다른 오류와 원인이 있습니다.
팀이 기억할 결론은 간단합니다. 일반적인 짧은 조회는 변경하지 않아도 될 가능성이 높지만, 대량 조회는 데이터를 나눠 처리하도록 바꾸는 편이 좋습니다. 이 제한은 더 큰 데이터베이스의 저장을 막거나 REST API 내보내기를 중단하지 않습니다. 각 응답이 50MB 이내에 머물도록 쿼리를 설계해야 한다는 뜻입니다.
