감성개발자의 Blog

Article

Laravel 서버리스 환경에서 PostgreSQL 드라이버 오류 해결

서버리스 환경에서 나타나는 특이한 에러

AWS Lambda나 다른 서버리스 플랫폼에서 Laravel을 실행할 때 다음과 같은 에러가 발생하기도 합니다:

could not find driver (Connection: pgsql, SQLSTATE[HY000])

흥미로운 점은 로컬 개발 환경이나 일반 서버에서는 정상 작동하지만, 서버리스 환경에서만 이 문제가 발생한다는 것입니다.

왜 이런 일이 발생할까

서버리스 환경은 일반적인 서버와 달리 최소한의 패키지만 포함합니다. 비용 최적화와 빠른 시작 속도를 위해 필수가 아닌 것들은 기본으로 설치되지 않습니다. PHP 확장 중 pdo_pgsql도 마찬가지로 기본 제공되지 않을 수 있습니다.

로컬 개발 환경에서는 이미 pdo_pgsql이 설치되어 있어서 자동으로 로드되지만, 서버리스 환경에서는 명시적으로 로드하도록 설정해야 합니다.

단계별 해결 방법

1단계: PHP 설정 폴더 생성

프로젝트 루트에 다음과 같은 디렉토리 구조를 생성합니다:

mkdir -p php/conf.d

서버리스 배포 시에 이 폴더가 패키징에 포함되도록 설정합니다.

2단계: PHP 확장 설정 파일 작성

php/conf.d/pgsql.ini 파일을 생성하고 다음 내용을 작성합니다:

extension=pdo_pgsql

이 파일은 매우 간단합니다. 단 한 줄이면 충분합니다. PHP가 시작될 때 이 설정을 읽고 pdo_pgsql 확장을 자동으로 로드합니다.

3단계: 배포 설정에 폴더 포함

AWS SAM을 사용하는 경우: template.yaml에서 Lambda 함수의 handler를 정의할 때, 코드 디렉토리를 지정합니다. php 폴더가 포함되어 있는지 확인하세요.

Serverless Framework를 사용하는 경우: serverless.yml에서:

package:
  include:
    - php/**

직접 Lambda 함수를 패키징하는 경우: ZIP 파일에 php 폴더를 반드시 포함시키세요:

zip -r function.zip php/ src/ vendor/

다른 PHP 확장도 필요한 경우

같은 방식으로 다른 확장들도 추가할 수 있습니다. php/conf.d/pgsql.ini 파일에 여러 줄을 작성하면 됩니다:

extension=pdo_pgsql
extension=pdo_mysql
extension=json
extension=xml
extension=curl

또는 각 확장마다 별도 파일을 만들어도 괜찮습니다:

php/conf.d/
├── pgsql.ini
├── mysql.ini
└── other-extensions.ini

배포 후 검증

배포 후에는 반드시 데이터베이스 연결을 테스트하세요. Laravel 명령어로 확인할 수 있습니다:

php artisan tinker
>>> DB::connection('pgsql')->select('SELECT 1');

또는 간단한 테스트 API 엔드포인트를 만들어 확인하는 것도 좋습니다:

Route::get('/db-test', function () {
    try {
        $result = DB::connection('pgsql')->select('SELECT NOW()');
        return response()->json(['success' => true, 'time' => $result[0]->now]);
    } catch (\Exception $e) {
        return response()->json(['error' => $e->getMessage()], 500);
    }
});

자주 발생하는 오류와 해결책

확장은 로드되었으나 연결 실패:

  • 데이터베이스 호스트, 포트, 자격증명이 올바른지 확인
  • 보안 그룹(Security Group) 설정 확인
  • 환경 변수가 올바르게 설정되었는지 확인

php/conf.d 폴더가 무시됨:

  • 배포 설정에 php/** 또는 php/ 폴더를 명시적으로 포함했는지 확인
  • ZIP 파일에 폴더가 루트부터 포함되었는지 확인

여러 확장 로드 실패:

  • 각 확장이 실제로 컴파일되어 있는지 확인
  • 확장 이름의 대소문자 확인 (보통 소문자)

최종 체크리스트

배포 전에 다음을 확인하세요:

  • php/conf.d/pgsql.ini 파일 생성
  • extension=pdo_pgsql 내용 확인
  • 배포 설정에 php 폴더 포함
  • 배포 후 데이터베이스 연결 테스트
  • Laravel 로그에서 에러 메시지 확인
  • 환경 변수(DB_HOST, DB_DATABASE 등) 설정 확인

마치며

서버리스 환경에서의 PHP 드라이버 문제는 간단한 설정 파일로 완전히 해결됩니다. 처음에는 왜 로컬에서는 되는데 서버리스에서는 안 되는지 당황할 수 있지만, 원인을 이해하면 쉽게 해결할 수 있습니다.

이 방법은 PostgreSQL뿐 아니라 MySQL, Redis, Memcached 등 다른 PHP 드라이버가 필요할 때도 같은 방식으로 적용할 수 있습니다. 서버리스 환경에서 Laravel을 안정적으로 운영하기 위해서는 최소한의 설정 파일들이 배포 패키지에 포함되도록 하는 것이 중요합니다.

댓글