DB가 응답하지 않아요! Communications link failure 원인과 3분 해결법 (식당 전화 비유)

안녕하세요, 여러분의 든든한 IT 길잡이 데브프리입니다.

 

스프링 부트(Spring Boot)로 열심히 코드를 짜고 드디어 서버를 실행했는데, 콘솔 창에 빨간색 글씨가 폭포수처럼 쏟아지며 서버가 켜지지 않은 적 있으신가요?

 

가장 윗줄로 스크롤을 올려보면 아래와 같은 무시무시한 에러 메시지가 적혀 있습니다. com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure

(또는 java.net.ConnectException: Connection refused: connect)

 

"통신 링크 실패라고? 내 인터넷이 끊겼나? 코드를 잘못 짰나?"

초보 백엔드 개발자들을 패닉에 빠뜨리는 가장 흔한 DB 연결 에러입니다. 하지만 걱정하지 마세요! 이 에러는 여러분의 자바 코드가 틀려서 나는 에러가 아닙니다.

 

오늘은 이 'DB 접속 실패 에러'의 원인을 아주 직관적인 일상생활 비유로 알아보고, 3가지 핵심 체크리스트를 통해 완벽하게 해결하는 방법을 정리해 드리겠습니다!

 

1. Communications link failure, 도대체 넌 누구냐? (식당 배달 전화 비유)

에러 메시지의 Communications link failure를 직역하면 "통신(연결) 선이 끊어졌다"는 뜻입니다. 즉, 스프링 부트(백엔드 서버)가 데이터베이스(MySQL, Oracle 등)에 말을 걸려고 시도했지만, 대답을 듣지 못했다는 의미입니다.

이 에러는 배달 음식을 시키려고 식당에 전화를 걸었는데, 식당이 문을 닫았거나 전화번호를 잘못 눌러서 '없는 번호입니다'라는 안내를 받는 상황과 완벽하게 똑같습니다.

우리가 피자를 시켜 먹으려면 피자집(DB)이 영업 중이어야 하고, 내가 전화번호(주소)를 정확히 눌러야 합니다.

 

스프링 부트도 마찬가지입니다. DB에 데이터를 넣으려면 ① DB 프로그램이 켜져 있어야 하고, ② 주소(URL)가 정확해야 하며, ③ 아이디와 비밀번호가 맞아야 합니다. 이 3가지 중 하나라도 어긋나면 전화를 받지 못하고 에러를 뱉어내는 것입니다.

 

2. 해결 방법: 3단계 트러블슈팅 체크리스트

코드를 고칠 필요는 전혀 없습니다. 여러분의 application.properties (또는 application.yml) 파일과 컴퓨터 환경만 점검하면 됩니다.

실수 ①: DB 프로그램(식당)을 아예 켜지 않았을 때 (가장 흔함!)

초보자들이 가장 많이 하는 귀여운 실수입니다. 스프링 부트 실행 버튼은 눌렀지만, 정작 내 컴퓨터에 깔려 있는 MySQL이나 MariaDB, 혹은 Docker 컨테이너를 실행(Start)하는 것을 깜빡한 경우입니다.

• 해결법:
  • 윈도우 사용자는 서비스(Services.msc) 앱을 열어 MySQL 서비스가 '실행 중'인지 확인하세요.
  • Mac 사용자는 터미널에서 brew services start mysql 명령어를 쳤는지, 혹은 Docker 데스크탑에서 DB 컨테이너가 켜져(초록불) 있는지 먼저 확인하세요! 식당 문부터 열어야 전화를 받을 수 있습니다.

실수 ②: 주소(URL)나 포트 번호에 오타가 있을 때

DB를 켜두었는데도 연결이 안 된다면, 전화번호를 잘못 누른 것입니다. 스프링 부트의 설정 파일(application.properties 등)을 열어 spring.datasource.url 부분을 꼼꼼히 확인하세요.

포트 번호(보통 3306)나 데이터베이스 이름에 단 하나의 오타라도 있으면, 스프링 부트는 엉뚱한 곳에 전화를 걸게 됩니다.

Properties

 

# 🚨 흔히 하는 오타 예시
spring.datasource.url=jdbc:mysql://localhost:3306/devfree_db
# 1. 3306이 아니라 3307 등 다른 포트를 쓰고 있진 않나요?
# 2. devfree_db 라는 이름의 스키마(데이터베이스)를 실제로 생성하셨나요?
# 3. 오타(locahost 등)가 있지는 않나요?

특히 DB 프로그램(DBeaver나 MySQL Workbench)을 열어 URL에 적힌 이름과 똑같은 이름의 스키마(데이터베이스)가 실제로 만들어져 있는지 반드시 확인하세요.

실수 ③: 아이디(Username)나 비밀번호(Password)가 틀렸을 때

전화는 걸렸는데, 비밀번호가 틀려서 DB가 스프링 부트를 문전박대하는 경우입니다. 이때는 에러 메시지 중간에 Access denied for user 라는 문구가 포함되어 있습니다.

Properties

 

spring.datasource.username=root
spring.datasource.password=1234

• 해결법: 설정 파일에 적힌 아이디와 비밀번호가 맞는지 점검하세요. 띄어쓰기(공백)가 실수로 들어가 있는 경우가 매우 많습니다. DBeaver 같은 DB 툴에서 해당 아이디/비번으로 접속이 잘 되는지 직접 테스트해 보는 것이 가장 확실합니다.

 

3. 요약: 트러블슈팅 체크리스트

Communications link failure 에러를 마주했다면 당황하지 말고 심호흡을 한 뒤, 아래 3가지를 순서대로 체크하세요.

1. DB 프로그램이 실행 중인가? (MySQL 프로세스나 도커 컨테이너가 켜져 있는지 확인)
2. URL 주소와 포트, DB 이름이 정확한가? (localhost, 3306, 스키마 이름 오타 확인)
3. 아이디와 비밀번호가 맞는가? (Access denied 에러 시, 공백 문자가 없는지 확인)

 

마무리

화면을 뒤덮는 수십 줄의 붉은 에러 로그(Stack Trace)를 보면 덜컥 겁부터 나기 마련입니다. 하지만 그 복잡한 로그들도 찬찬히 읽어보면 결국 "DB가 전화를 안 받아요!"라는 아주 단순한 불평을 길게 늘어놓은 것뿐입니다.

 

에러를 두려워하지 마세요. 오늘 배운 트러블슈팅 과정처럼, 로그가 가리키는 원인을 찾아 하나씩 점검하다 보면 어느새 에러를 해결하고 한 뼘 더 성장한 자신을 발견하게 될 것입니다.

 

오늘 준비한 가이드가 여러분의 붉은 에러 창을 깨끗하게 지워주었기를 바랍니다. 오류를 고치다 막히는 부분이 있다면 언제든 댓글로 남겨주세요.

 

지금까지 데브프리였습니다. 감사합니다!