The database server at {database_host}:{database_port} was reached but timed out. Please try again. Please make sure your database server is running at {database_host}:{database_port}.

확인 방법

오류 화면 또는 로그에서 오류 코드가 P1002인지 확인합니다.

표시된 메시지가 다음 형식과 일치하는지 확인합니다.

The database server at {database_host}:{database_port} was reached but timed out. Please try again. Please make sure your database server is running at {database_host}:{database_port}.

{database_host}와 {database_port} 위치에는 현재 연결에 사용된 호스트와 포트 값이 표시됩니다.

이 코드와 메시지가 일치하면 Prisma는 해당 데이터베이스 서버에 도달했지만 시간 초과된 상태를 보고한 것입니다.

출처: Prisma Error Reference (새 창에서 열림)

진단 기록

먼저 문제가 발생한 URL 또는 화면, 표시 시각, 사용한 플랫폼과 배포 버전을 기록합니다. 화면과 로그에서 오류 문자열이 일부만 보이면 앞뒤 문장을 포함해 원문을 보존하고, 민감한 값은 가립니다.

다음 순서로 관찰값을 대조합니다.

1. 오류 화면 또는 로그의 오류 코드가 P1002인지 확인합니다.
2. 표시된 오류 메시지가 Prisma 문서의 P1002 메시지 형식과 일치하는지 확인합니다.
3. 메시지에 표시된 데이터베이스 호스트와 포트 값을 확인합니다.

각 항목은 확인한 값과 확인하지 못한 이유를 함께 기록해야 합니다. 이 문서의 조건과 실제 관찰값이 다르면 원인을 단정하지 말고, 문제 해결 시작 가이드에서 더 넓은 분기를 선택하십시오.

판정 기준

오류 문자열이 일치한다는 사실만으로 원인이 확정되지는 않습니다. 같은 문구가 여러 환경에서 나타날 수 있으므로 웹서버·런타임·운영체제·최근 변경 사항을 함께 비교합니다. 한 단계에서 기대한 값이 나오지 않으면 다음 단계로 넘어가지 말고 해당 환경의 공식 문서를 우선 확인합니다.

안전한 다음 단계

검사 전에 백업과 변경 이력을 확인하고, 비밀번호·세션 쿠키·인증 토큰·개인정보를 공개 로그나 문의 내용에 넣지 않습니다. 설정·권한·데이터를 변경해야 한다면 영향 범위와 되돌리는 방법을 먼저 기록한 뒤 운영 시간과 승인 절차에 맞춰 진행합니다.

원인 분포

[Observation] 수집된 3건 모두 데이터베이스 서버에 도달했지만 PostgreSQL advisory lock을 제한 시간 안에 획득하지 못한 사례입니다.

[Observation] 2건에서는 이전 migration 또는 idle 세션이 lock을 보유한 정황이 명시되었고, 1건에서는 Prisma와 PgBouncer의 처리 방식 조정이 해결책으로 기록되었습니다.

[Hypothesis] 이 문서의 관측 사례에서는 네트워크 도달성보다 migration advisory lock 경합 또는 잔류 세션을 우선 확인하는 편이 적절합니다. 이는 실제 전체 발생 빈도를 의미하지 않습니다.

오진 함정

• [Observation] P1002가 표시되어도 사례 1에서는 연결 풀 사용 여부나 앱 크기를 변경해도 문제가 재현되었습니다.
• [Observation] 사례 2와 사례 3에서는 서버 중단보다 advisory lock을 보유한 idle 세션이 문제 문맥에 포함되었습니다.
• [Hypothesis] 단순히 데이터베이스 서버 실행 여부나 연결 풀 크기만 확인하면 lock 보유 세션을 놓칠 수 있습니다.

환경 매트릭스

사례	실행 환경	Prisma 작업	관측된 상태	수정 또는 결과
1	DigitalOcean App Platform, PostgreSQL 13, PgBouncer 관련 구성	prisma migrate deploy	advisory lock 획득 시간 초과	Prisma와 PgBouncer 처리 방식 조정 후 배포 오류 해결
2	Docker, Umami 2.13.2, PostgreSQL	prisma migrate deploy	idle 세션이 advisory lock 보유	해당 lock 해제 절차 안내 후 이슈 종료
3	Supabase, PostgreSQL 15.1, Prisma	prisma migrate dev, reset	이전 migration 연결이 idle 상태로 lock 보유	pg_locks와 pg_stat_activity로 연결을 찾아 종료

[Observation] 서로 다른 배포 환경과 PostgreSQL 버전에서 같은 advisory lock 획득 시간 초과가 보고되었습니다.

진단 순서

1. [Observation] P1002가 발생한 Prisma 작업이 migrate deploy, migrate dev, reset 중 무엇인지 확인합니다.
2. [Observation] 오류 로그에서 PostgreSQL advisory lock 획득 실패와 제한 시간을 확인합니다.
3. [Observation] pg_locks와 pg_stat_activity에서 Prisma migration과 관련된 lock 및 idle 세션을 확인합니다.
4. [Observation] lock을 보유한 idle 연결이 확인되면, 사례 2와 사례 3에서 안내되거나 사용된 방식처럼 해당 연결을 종료해 lock을 해제합니다.
5. [Observation] 사례 1에서는 Prisma와 PgBouncer 처리 방식 조정 후 배포 오류가 해결되었으므로, PgBouncer를 사용하는 환경이면 해당 구성과 Prisma의 상호작용도 확인합니다.
6. [Observation] lock 해제 또는 구성 조정 후 같은 migration 작업을 다시 실행해 결과를 확인합니다.