본문 바로가기
카테고리 없음

Laravel에서 'Connection refused' 오류 해결법: MySQL 연결 문제

by blogfine 2025. 4. 3.

Laravel에서 'Connection refused' 오류란?

Laravel에서 'Connection refused' 오류는 주로 데이터베이스 연결을 시도할 때 발생하는 오류입니다. 이 오류는 Laravel 애플리케이션이 MySQL 데이터베이스에 연결하려고 할 때, MySQL 서버가 연결을 거부하거나 접속할 수 없을 때 발생합니다. 데이터베이스 연결을 실패하게 되면 애플리케이션의 기능이 제대로 작동하지 않으므로 빠르게 해결하는 것이 중요합니다. 이 오류는 다양한 원인에 의해 발생할 수 있으며, 올바르게 설정하고 확인하는 방법을 알아보겠습니다.

'Connection refused' 오류의 원인

'Connection refused' 오류는 여러 가지 원인으로 발생할 수 있습니다. 주요 원인으로는 다음과 같습니다:

  • 잘못된 데이터베이스 호스트: 데이터베이스 서버의 주소가 잘못 설정되었거나 올바르지 않은 IP 주소를 사용하는 경우 연결이 거부됩니다.
  • 잘못된 데이터베이스 포트: MySQL 서버가 다른 포트에서 실행 중일 경우, 기본 포트인 3306을 사용하려고 시도할 때 'Connection refused' 오류가 발생할 수 있습니다.
  • MySQL 서버가 실행되지 않음: MySQL 서버가 다운되었거나 실행 중이지 않으면 연결이 거부됩니다.
  • 방화벽 설정 문제: MySQL 서버와 Laravel 애플리케이션 간의 네트워크 방화벽 설정이 잘못되어 연결을 차단할 수 있습니다.
  • 잘못된 사용자 인증: 잘못된 데이터베이스 사용자 이름 또는 비밀번호를 사용하는 경우 연결이 거부될 수 있습니다.

'Connection refused' 오류 발생 예시

아래는 'Connection refused' 오류가 발생할 수 있는 상황의 예시입니다. 이 오류는 MySQL 서버에 접속하려고 할 때 발생할 수 있습니다:

Illuminate\Database\QueryException
  SQLSTATE[HY000] [2002] Connection refused

위와 같은 오류 메시지가 나타나면, Laravel 애플리케이션이 데이터베이스에 연결할 수 없다는 의미입니다. 이 오류는 데이터베이스 서버가 다운되었거나, 데이터베이스 연결 설정이 잘못되었을 때 발생합니다.

'Connection refused' 오류 해결법

이 오류를 해결하려면 아래의 방법들을 시도할 수 있습니다:

1. 데이터베이스 호스트 및 포트 설정 확인

Laravel에서 MySQL 서버의 호스트 주소와 포트 번호는 config/database.php 파일에 설정되어 있습니다. 기본적으로 'localhost'와 포트 3306을 사용하지만, MySQL 서버가 다른 호스트나 포트에서 실행 중일 수 있습니다. 이 경우, DB_HOST와 DB_PORT 값을 확인하고 수정해야 합니다. 예를 들어:


DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

위와 같이 올바른 IP 주소와 포트를 설정했는지 확인하고, MySQL 서버의 IP와 포트가 정확한지 점검하세요.

2. MySQL 서버 상태 확인

MySQL 서버가 실행되고 있는지 확인해야 합니다. 서버가 실행되지 않으면 Laravel은 MySQL에 연결할 수 없습니다. MySQL 서버가 실행 중인지 확인하려면 다음 명령어를 사용할 수 있습니다:

sudo service mysql status

만약 서버가 실행되지 않으면 아래 명령어로 서버를 시작할 수 있습니다:

sudo service mysql start

MySQL 서버가 실행 중인지 확인하고, 필요 시 서버를 시작하세요.

3. 방화벽 설정 확인

MySQL 서버와 Laravel 애플리케이션 간의 네트워크 방화벽이 MySQL 연결을 차단할 수 있습니다. MySQL 서버가 다른 서버에서 실행되고 있다면, 해당 서버의 방화벽에서 3306 포트를 열어야 합니다. 아래 명령어로 방화벽 설정을 확인하고 포트를 열 수 있습니다:

sudo ufw allow 3306

방화벽에서 MySQL 포트를 열어주고, 연결을 허용하도록 설정해 주세요.

4. 데이터베이스 사용자 인증 확인

잘못된 사용자 이름이나 비밀번호로 인해 'Connection refused' 오류가 발생할 수 있습니다. Laravel에서 사용하는 데이터베이스 사용자 계정이 MySQL 서버에 올바르게 설정되어 있는지 확인해야 합니다. MySQL에서 사용자 계정을 확인하고, 필요한 경우 비밀번호를 재설정할 수 있습니다. 예를 들어, MySQL에서 사용자 계정을 생성하는 명령어는 다음과 같습니다:

CREATE USER 'your_username'@'localhost' IDENTIFIED BY 'your_password';

그 후, 해당 사용자에게 필요한 권한을 부여합니다:

GRANT ALL PRIVILEGES ON your_database_name.* TO 'your_username'@'localhost';

이렇게 사용자를 정확하게 설정하면, 'Connection refused' 오류를 해결할 수 있습니다.

5. .env 파일 설정 점검

Laravel 애플리케이션은 .env 파일에서 데이터베이스 연결 정보를 읽어들입니다. 이 파일에서 설정된 DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD 값을 정확하게 입력했는지 다시 한 번 확인하세요. 특히 DB_HOST가 localhost나 127.0.0.1로 잘 설정되어 있는지 확인하고, 이 값들이 MySQL 서버의 실제 IP와 일치하는지 점검합니다.

정리

'Connection refused' 오류는 MySQL 데이터베이스 서버와의 연결 문제로 발생합니다. 이 오류를 해결하려면 데이터베이스 연결 설정을 점검하고, MySQL 서버가 실행 중인지 확인해야 합니다. 또한, 방화벽 설정이나 사용자 인증 문제를 해결하고, .env 파일에 정확한 정보를 입력하는 것이 중요합니다. 위에서 설명한 방법들을 통해 MySQL 연결 문제를 해결하고, Laravel 애플리케이션이 정상적으로 동작하도록 할 수 있습니다.

티스토리툴바