백엔드 개발을 하다 보면 데이터베이스와 연결하는 과정에서 여러 가지 이슈를 마주할 수 있습니다. 특히 Node.js 환경에서 MongoDB나 MySQL 같은 데이터베이스와 연결하려고 할 때, 연결 실패 문제는 자주 발생하는 상황입니다. 이번 포스트에서는 데이터베이스 연결 실패의 원인과 이를 해결하기 위한 방법들을 살펴보겠습니다.

1. 환경 설정 확인

먼저, 데이터베이스와의 연결 시 가장 기본적으로 확인해야 하는 것은 환경 설정입니다. 데이터베이스의 주소, 포트, 사용자 이름, 비밀번호 등이 올바르게 설정되어 있는지를 확인해야 합니다. 아래는 MongoDB를 연결할 때 사용하는 예제입니다.

const mongoose = require('mongoose');

const uri = 'mongodb://username:password@localhost:27017/mydatabase';

mongoose.connect(uri, { useNewUrlParser: true, useUnifiedTopology: true })
    .then(() => console.log('MongoDB connected'))
    .catch(err => console.error('MongoDB connection error:', err));

위 코드에서 uri가 올바른 형식으로 입력되었는지 확인합니다. 특히 사용자 이름이나 비밀번호에 오타가 없는지, 데이터베이스 이름이 정확한지를 체크해야 합니다.

2. 데이터베이스 서버 상태 확인

다음으로 확인해야 할 것은 데이터베이스 서버가 정상적으로 실행되고 있는지 여부입니다. 로컬 개발 환경에서 MongoDB나 MySQL 서버가 죽어있다면 당연히 연결 실패가 발생할 것입니다. 각 데이터베이스 서버를 확인하는 방법은 다음과 같습니다.

MongoDB

sudo systemctl status mongod

MySQL

sudo systemctl status mysql

서버가 실행 중이지 않다면, 다음의 명령어로 서버를 시작할 수 있습니다.

MongoDB

sudo systemctl start mongod

MySQL

sudo systemctl start mysql

3. 방화벽 및 네트워크 설정

서버가 실행 중인데도 연결이 실패한다면, 방화벽 설정이나 네트워크 설정에도 문제의 원인이 있을 수 있습니다. 기본적으로 데이터베이스는 특정 포트(예: MongoDB는 27017, MySQL은 3306)를 통해 접근합니다. 이 포트가 방화벽에 의해 차단되어 있는지 확인해야 합니다.

우분투에서 방화벽 규칙 확인

sudo ufw status

필요하다면 다음과 같이 포트를 허용할 수 있습니다.

MongoDB

sudo ufw allow 27017

MySQL

sudo ufw allow 3306

4. CORS 정책 확인

Node.js를 사용하는 경우, 다양한 클라이언트 애플리케이션이 백엔드 서버와 통신할 수 있습니다. 이때 CORS(Cross-Origin Resource Sharing) 설정이 제대로 되어 있지 않으면 연결이 실패할 수 있습니다. Express를 사용하는 Node.js 서버에서 CORS를 설정하는 방법은 다음과 같습니다.

const express = require('express');
const cors = require('cors');

const app = express();
app.use(cors());  // 모든 도메인에서의 요청을 허용합니다.

특정 도메인만 허용하고 싶다면 다음과 같이 설정할 수 있습니다.

app.use(cors({
    origin: 'http://your-client-application.com'
}));

5. 에러 메시지 분석

마지막으로, 데이터베이스 연결 실패 시 반환되는 에러 메시지를 잘 분석해야 합니다. 예를 들어, ECONNREFUSED 에러는 서버가 실행 중이지 않거나 주소가 잘못되었음을 나타냅니다. 반면 AuthenticationFailed 에러는 사용자 이름이나 비밀번호가 잘못되었음을 의미합니다. 이러한 에러 코드를 정확히 이해하고 문제를 해결할 수 있어야 합니다.

mongoose.connect(uri, { useNewUrlParser: true, useUnifiedTopology: true })
    .then(() => console.log('MongoDB connected'))
    .catch(err => {
        switch (err.code) {
            case 'ECONNREFUSED':
                console.error('데이터베이스 서버에 연결할 수 없습니다. 서버가 실행 중인지 확인하세요.');
                break;
            case 'AuthenticationFailed':
                console.error('인증에 실패했습니다. 사용자 이름과 비밀번호를 확인하세요.');
                break;
            default:
                console.error('Unknown error:', err);
        }
    });

마무리

Node.js에서 데이터베이스 연결 실패 문제는 다양한 원인으로 발생할 수 있습니다. 환경 설정, 데이터베이스 서버 상태, 방화벽 및 네트워크 설정, CORS 정책 그리고 에러 메시지 분석 등을 통해 문제를 진단하고 해결할 수 있습니다. 이러한 과정을 통해 안정적으로 데이터베이스와 연결할 수 있으며, 백엔드 개발의 기초를 다질 수 있습니다. 다음 포스트에서는 더 심화된 데이터베이스 트러블슈팅 기법에 대해 다루어 보겠습니다.