문제 해결: 데이터베이스

일반적인 데이터베이스 연결 및 쿼리 문제를 해결합니다.

연결 거부

오류: ECONNREFUSED 127.0.0.1:5432 또는 connect ECONNREFUSED 127.0.0.1:27017

이 오류는 1DevTool이 연결 문자열의 호스트와 포트에 도달했지만 거기에서 수신하는 것이 없음을 의미합니다. 데이터베이스 서버가 실행 중이지 않거나 다른 포트에서 수신 중입니다.

해결:

  • 데이터베이스가 실행 중인지 확인합니다. PostgreSQL: 터미널에서 pg_ctl status를 실행합니다. MySQL: mysqladmin status. Redis: redis-cli ping (PONG을 받아야 함). 서비스가 중지되었으면 시작합니다.
  • 포트를 확인합니다. 기본 포트는 5432 (PostgreSQL), 3306 (MySQL/MariaDB), 27017 (MongoDB), 6379 (Redis)입니다. DATABASE_URL의 포트를 데이터베이스가 실제로 사용하는 포트와 비교합니다.
  • Docker 컨테이너. 데이터베이스가 Docker 내부에서 실행 중이면 docker ps로 컨테이너가 실행 중인지 확인합니다. 나열되지 않으면 docker start <container-name>으로 시작합니다. 컨테이너의 포트가 호스트에 게시되었는지도 확인합니다 (docker ps 출력에서 0.0.0.0:5432->5432/tcp를 찾습니다).

인증 실패

오류: password authentication failed for user "postgres" 또는 Access denied for user 'root'@'localhost'

연결 문자열의 사용자 이름 또는 비밀번호가 데이터베이스 서버가 기대하는 것과 일치하지 않습니다.

해결:

  • DATABASE_URL 또는 연결 설정의 사용자 이름과 비밀번호를 다시 확인합니다. Supabase 계정 비밀번호와 데이터베이스 비밀번호를 혼동하기 쉽습니다 — 다릅니다. Supabase 대시보드의 Settings → Database에 표시된 비밀번호를 사용하세요.
  • 비밀번호의 특수 문자. 비밀번호에 @, #, /, :가 포함된 경우 연결 문자열에서 URL 인코딩해야 합니다. 예를 들어 @는 %40, #는 %23이 됩니다. p@ss#word 같은 비밀번호는 URL에서 p%40ss%23word로 작성됩니다.

SSL/TLS 필요

오류: SSL connection has been closed unexpectedly 또는 server requires SSL but client does not support it

많은 클라우드 데이터베이스 제공업체(Supabase, Neon, Railway, Render)는 암호화된 연결을 필요로 합니다.

해결: PostgreSQL 연결 문자열 끝에 ?sslmode=require를 추가합니다:

postgresql://user:pass@host:5432/db?sslmode=require

MongoDB Atlas의 경우 연결 문자열에 mongodb+srv:// 스키마를 사용합니다 — TLS를 자동으로 활성화하며 추가 매개변수가 필요 없습니다.

쿼리 시간 초과

원인: 쿼리가 너무 많은 데이터를 스캔하거나 1DevTool과 데이터베이스 간 네트워크 연결이 쿼리 중간에 끊어졌습니다.

해결:

  • 데이터 탐색 중 쿼리에 LIMIT 절을 추가합니다. 예: SELECT * FROM orders LIMIT 100.
  • 특정 쿼리가 항상 느리다면 WHERE 절의 열에 인덱스가 있는지 확인합니다. SQL 에디터에서 EXPLAIN ANALYZE <your query>를 실행하면 쿼리 계획이 표시됩니다.
  • 시간 초과가 간헐적으로 발생하면 네트워크를 확인합니다. 특히 VPN 연결이 불안정한 데이터베이스 연결을 유발할 수 있습니다.

MongoDB: 비밀번호의 특수 문자

MongoDB 비밀번호에 @, /, :, #가 포함된 경우 연결 문자열에서 이러한 문자를 URL 인코딩해야 합니다. 이러한 문자는 URL에서 특별한 의미를 가지며 그대로 사용하면 파싱이 깨집니다.

일반적인 인코딩: @ → %40, # → %23, / → %2F, : → %3A.

예: my@secret#pass 비밀번호는 연결 문자열에서 my%40secret%23pass가 됩니다.

Docker 컨테이너에 연결할 수 없음

데이터베이스가 Docker 컨테이너 내부에서 실행 중이고 호스트 머신에서 실행되는 1DevTool에서 연결하려고 한다면 연결 문자열에 localhost를 사용하지 마세요. 호스트에서 localhost는 컨테이너가 아닌 호스트 머신 자체를 참조합니다.

대신 host.docker.internal을 사용하세요:

postgresql://user:[email protected]:5432/db

이 특수 호스트 이름은 Docker 내부에서 항상 호스트 머신으로 해석되며 호스트 측에서 올바른 루프백 인터페이스로 해석됩니다.