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

Laravel에서 'Database query timeout' 오류 해결법

by blogfine 2025. 4. 4.

Laravel에서 'Database query timeout' 오류란?

Laravel에서 'Database query timeout' 오류는 데이터베이스 쿼리가 너무 오래 걸려서 시간 초과가 발생했을 때 발생하는 오류입니다. 이는 데이터베이스에서 쿼리가 너무 많은 리소스를 사용하거나 쿼리 성능이 낮아서 발생할 수 있습니다. Laravel에서 이 오류가 발생하면 애플리케이션이 정상적으로 데이터를 조회할 수 없게 되어, 사용자는 해당 기능을 사용할 수 없게 됩니다. 이 문제를 해결하려면 쿼리 최적화와 설정 조정이 필요합니다.

'Database query timeout' 오류의 원인

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

  • 쿼리 성능 문제: 쿼리가 복잡하거나 비효율적으로 작성되어 실행 시간이 오래 걸리면 시간 초과가 발생할 수 있습니다.
  • 데이터베이스 서버 부하: 서버가 과부하 상태에 있거나, 너무 많은 요청이 동시에 처리되면 쿼리 실행 시간이 길어질 수 있습니다.
  • 네트워크 문제: 네트워크 연결 문제로 인해 데이터베이스와의 통신이 지연될 수 있습니다.
  • 타임아웃 설정 부족: Laravel 애플리케이션의 데이터베이스 연결 설정에서 타임아웃 시간이 너무 짧게 설정되었을 수 있습니다.

'Database query timeout' 오류 발생 예시

아래는 'Database query timeout' 오류가 발생할 수 있는 상황의 예시입니다:

Illuminate\Database\QueryException
  SQLSTATE[HY000]: General error: 2006 MySQL server has gone away

위와 같은 오류 메시지는 쿼리가 너무 오래 실행되어 MySQL 서버에서 쿼리 요청을 처리하지 못했을 때 발생합니다. 이는 데이터베이스 쿼리가 시간 초과로 인해 중단되었음을 의미합니다.

'Database query timeout' 오류 해결법

이 오류를 해결하려면 다음과 같은 방법들을 시도할 수 있습니다:

1. 쿼리 최적화

쿼리의 성능이 문제가 될 수 있으므로 쿼리를 최적화하는 것이 중요합니다. 다음은 쿼리 최적화를 위한 방법들입니다:

  • 인덱스 추가: 자주 검색되는 열에 인덱스를 추가하면 쿼리 성능을 개선할 수 있습니다. 예를 들어, WHERE 절이나 JOIN 조건에 사용되는 열에 인덱스를 추가하여 검색 속도를 높일 수 있습니다.
  • 불필요한 JOIN 제거: 여러 테이블을 조인할 때 필요하지 않은 테이블을 제거하거나, 서브쿼리로 대체하면 쿼리 성능을 개선할 수 있습니다.
  • 데이터 양 제한: 쿼리에서 반환하는 데이터 양을 제한하면, 실행 시간이 단축됩니다. 예를 들어, LIMIT 절을 사용하여 반환되는 레코드 수를 제한할 수 있습니다.

2. 데이터베이스 서버 성능 향상

데이터베이스 서버의 성능이 낮으면 쿼리 실행 시간이 길어질 수 있습니다. 서버 성능을 향상시키기 위해 다음을 고려할 수 있습니다:

  • 서버 리소스 추가: 데이터베이스 서버에 더 많은 CPU, RAM, 디스크 I/O를 추가하여 성능을 향상시킬 수 있습니다.
  • 쿼리 캐싱: 자주 실행되는 쿼리에 대해 캐싱을 사용하면 서버 부하를 줄이고 성능을 향상시킬 수 있습니다.

3. 데이터베이스 연결 타임아웃 시간 늘리기

Laravel에서는 .env 파일에서 데이터베이스 연결에 대한 설정을 관리합니다. 이 파일에서 데이터베이스 연결의 타임아웃 시간을 늘려 쿼리가 실행될 수 있도록 설정할 수 있습니다. 예를 들어, MySQL의 타임아웃을 늘리려면 DB_TIMEOUT 설정을 추가할 수 있습니다. .env 파일에 아래와 같은 설정을 추가하세요:

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
DB_TIMEOUT=60

위 설정에서 DB_TIMEOUT 값을 늘리면 Laravel이 MySQL 데이터베이스에 연결할 때 기다리는 시간이 늘어납니다. 이렇게 하면 긴 실행 시간의 쿼리가 타임아웃되지 않고 정상적으로 실행될 수 있습니다.

4. 데이터베이스 커넥션 풀 설정 확인

Laravel에서 사용하는 데이터베이스 커넥션 풀의 설정을 점검해 보세요. 커넥션 풀 크기가 너무 작으면 데이터베이스 연결 요청이 대기 상태로 들어가고, 이로 인해 쿼리가 타임아웃될 수 있습니다. config/database.php 파일에서 연결 수를 늘려 쿼리가 원활하게 실행될 수 있도록 할 수 있습니다:


'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'forge'),
    'username' => env('DB_USERNAME', 'forge'),
    'password' => env('DB_PASSWORD', ''),
    'unix_socket' => env('DB_SOCKET', ''),
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix' => '',
    'strict' => true,
    'engine' => null,
    'options'   => [
        PDO::ATTR_TIMEOUT => 60, // 커넥션 타임아웃 시간 늘리기
    ],
],

위 설정에서 PDO::ATTR_TIMEOUT 옵션을 사용하여 커넥션 타임아웃 시간을 늘릴 수 있습니다. 이를 통해 데이터베이스 연결 문제를 해결할 수 있습니다.

5. 쿼리 로그 활성화 및 디버깅

쿼리 로그를 활성화하여 어떤 쿼리가 실행되고 있는지 확인할 수 있습니다. DB::listen 메서드를 사용하여 쿼리를 로그로 기록하고, 쿼리 실행 시간이 오래 걸리는 부분을 파악할 수 있습니다:


DB::listen(function($query) {
    logger($query->sql);
    logger($query->time);
});

위 코드를 사용하면 쿼리 실행 시간과 쿼리 자체를 로그에 기록할 수 있습니다. 이를 통해 쿼리 성능 문제를 찾아내고 해결할 수 있습니다.

정리

'Database query timeout' 오류는 데이터베이스 쿼리가 너무 오래 실행되어 시간 초과가 발생할 때 나타나는 오류입니다. 이 오류를 해결하려면 쿼리 성능 최적화, 데이터베이스 서버 성능 향상, 타임아웃 시간 늘리기 등 여러 방법을 시도할 수 있습니다. 또한, Laravel에서 제공하는 설정을 통해 타임아웃 시간을 늘리거나, 쿼리 로그를 통해 문제를 디버깅하는 방법도 유용합니다. 위 방법들을 통해 데이터베이스 쿼리의 시간 초과 문제를 해결하고, 애플리케이션의 성능을 개선할 수 있습니다.

티스토리툴바