럭키스팟

실전 문제 해결 가이드

로그인
배포수동 검토 가이드확인일 2026-07-08

DB 연결이 로컬만 되고 배포에서 터질 때

집에서는 붙는데 배포만 timeout·permission denied가 날 때 URL·SSL·방화벽·권한·연결 풀 순서로 좁힙니다.

한 줄 결론

DB 문제는 대부분 ‘주소 문자열 1줄’이 아니라, 권한·SSL·네트워크·env가 한 세트로 맞지 않아 생깁니다.

아래 내용은 초보 바이브코더를 위한 일반 안내입니다. 서비스·지역·약관에 따라 달라질 수 있으며, 실제 사업화·운영 전에는 해당 분야 전문가 확인이 필요합니다.

먼저 용어부터 — 그다음 실행 프롬프트

DATABASE_URL
DB 접속 주소 전체(비밀번호 포함)를 담는 env
migration
DB 테이블 구조를 바꾸는 변경 기록

  • Environment variables

    이건 env(환경변수)입니다

    비밀값·설정을 코드 밖에 두는 칸입니다. 로컬은 .env.local, 배포는 Vercel Environment Variables.

    • 비밀은 Git에 커밋하지 않습니다
    • 로컬과 배포 값이 다르면 ‘로컬만 됨’이 납니다
    • 이름만 같아도 값이 비면 500이 납니다

    이런 곳에 · OAuth secret · DATABASE_URL · API Key · CRON_SECRET

    지금 할 일 · .env.example에 이름만 적고, 실제 값은 .env.local에만

    비용·주의 · 잘못된 env로 무한 재시도하면 API 비용이 늘 수 있습니다.

    AI 프롬프트 보기
    Next.js + Vercel env 점검. 로컬은 되는데 배포만 실패. 필요한 키 목록(값 제외), Production 탭 확인 순서.

바로 실행 — AI 프롬프트

Prisma + Postgres connection failed. DATABASE_URL 형식·SSL ?sslmode=require·Vercel env·prisma db push 순서.

막히면 다시 넣을 프롬프트

Prisma P1001/P1017. URL 호스트: [   ], SSL: [   ], serverless 여부: [   ].

이런 사람이 보면 좋음

  • Supabase/Neon/PlanetScale 등 외부 DB를 처음 붙이는 사람
  • 로컬에서는 되는데 Vercel/서버에서만 DB 연결이 끊기는 사람
  • DB 비밀번호를 바꿨는데 어디가 깨졌는지 모르는 사람

초보자가 보통 착각하는 지점

  • 로컬과 배포가 같은 네트워크라고 생각합니다. 배포 환경은 별도 IP/네트워크 정책을 갖습니다.
  • DATABASE_URL 한 줄만 바꾸면 끝난다고 봅니다. SSL 모드·스키마·유저 권한이 맞지 않으면 바로 실패합니다.
  • DB 연결 에러를 코드 버그로만 보고, 방화벽/허용 IP/권한을 마지막에 봅니다.
  • dev와 prod에 같은 DB 계정·권한을 그대로 씁니다. 사고가 나면 범위가 커집니다.

실제 점검 체크리스트

  • 배포 환경의 DATABASE_URL이 로컬(.env.local)과 동일한 형식인지 확인합니다(유저/호스트/포트/DB명/쿼리).
  • DB 제공자 대시보드에서 ‘허용 IP/네트워크’ 정책이 배포 환경을 막지 않는지 확인합니다.
  • SSL 요구 여부를 확인하고, 필요하면 sslmode/인증서 설정이 들어갔는지 확인합니다.
  • 권한 에러라면 DB 유저가 필요한 스키마/테이블에 접근 권한을 갖는지 확인합니다.
  • 연결 풀/동시 요청이 많은 경우, 서버리스 환경에서 커넥션 폭주가 나는지 확인합니다.
  • 로컬에서 npm run build && npm run start로 프로덕션 모드에서도 동일 증상이 재현되는지 확인합니다.

실패했을 때 보는 순서

  1. 1에러 메시지를 분류합니다(timeout / permission denied / SSL / host not found).
  2. 2배포 환경 변수(DATABASE_URL)가 실제로 주입됐는지 확인합니다(빈 값/오타/환경 범위).
  3. 3DB 대시보드에서 네트워크/방화벽/허용 IP 설정을 확인합니다.
  4. 4SSL 요구 여부와 연결 옵션을 확인합니다.
  5. 5권한(유저/role)을 확인하고, 최소 권한 계정을 분리합니다.
  6. 6커넥션 폭주가 의심되면 pooler 사용/동시성 제한/캐시로 줄입니다.

배포 전 확인 항목

  • dev/prod DB 계정을 분리하고 최소 권한으로 만들었습니다.
  • 배포 환경에서 DB health 체크(간단 select 1)가 가능합니다.
  • DB 비밀번호 rotate 시 변경 순서를 체크리스트로 적어 두었습니다.

보안·법적 주의

  • DB 접속 정보는 비밀번호 취급입니다. 채팅/이슈/스크린샷에 전체 URL을 붙이지 마세요.
  • 개인정보가 들어가는 DB는 보관·삭제·접근 통제 정책이 필요합니다. 실제 운영 전 보안/법무 전문가 확인을 권합니다.
DBDATABASE_URLSSL권한Vercel