Laravel 서버리스(Bref)에서 could not find driver (pgsql) 해결하기

Laravel 애플리케이션을 AWS Lambda에 올리고 PostgreSQL에 붙이려는데 이런 에러가 나올 때가 있다.

PDOException: could not find driver (Connection: pgsql, SQL: select * from ...)

로컬에서는 잘 되던 게 Lambda에서만 터진다. 원인은 런타임 이미지에 PDO PostgreSQL 확장이 안 들어 있어서다.

왜 이런 일이 생기나

서버리스 PHP 런타임(Bref 등)은 Lambda의 용량 제한 때문에 확장을 최소한만 넣어서 배포한다. MySQL용 pdo_mysql은 기본 포함이지만 pdo_pgsql은 빠져 있는 경우가 많다.

로컬 개발 환경의 PHP에는 대부분 둘 다 깔려 있으니 로컬 테스트에서는 안 잡힌다. 배포하고 나서야 발견하게 되는 전형적인 케이스다.

해결: php/conf.d 에 확장 활성화 파일 추가

프로젝트 루트에 다음 경로로 디렉터리와 파일을 만든다.

프로젝트루트/
└── php/
    └── conf.d/
        └── pgsql.ini

파일 내용은 한 줄이면 된다.

extension=pdo_pgsql

Bref는 배포 시 php/conf.d 아래의 .ini 파일을 자동으로 읽어 런타임 설정에 반영한다. 별도 설정 없이 이 경로에 두기만 하면 된다.

serverless.yml 확인

레이어에 확장이 실제로 포함되는지도 같이 봐야 한다. Bref는 확장별 레이어를 따로 제공한다.

functions:
  web:
    handler: public/index.php
    layers:
      - ${bref:layer.php-83-fpm}
      - ${bref-extra:pgsql-php-83}

bref-extra 플러그인을 쓰면 pgsql, redis, gd 같은 추가 확장을 레이어로 붙일 수 있다. serverless-lift나 Bref 버전에 따라 이름이 조금씩 다르니 사용 중인 버전 문서를 확인하는 게 좋다.

배포 후 확인하는 법

확장이 제대로 올라갔는지는 Lambda에서 직접 확인하는 게 빠르다.

# 로컬에서 Lambda 함수 호출
vendor/bin/bref cli 함수이름 -- artisan tinker

# 또는 간단한 라우트 하나 만들어서
Route::get('/_ext', fn() => implode(', ', get_loaded_extensions()));

pdo_pgsql 이 목록에 있으면 성공이다.

같은 원리로 자주 겪는 것들

이 에러는 pgsql만의 문제가 아니다. 서버리스 환경에서 확장이 빠져서 나는 에러는 패턴이 같다.

• could not find driver → PDO 드라이버 누락 (pgsql, sqlsrv 등)
• Class "Redis" not found → redis 확장 누락
• Call to undefined function imagecreate() → gd 확장 누락
• Call to undefined function bcadd() → bcmath 확장 누락

전부 같은 방식으로 접근하면 된다. 해당 확장 레이어를 추가하고, 필요하면 php/conf.d에 extension= 한 줄을 넣는다.

그 전에 한 가지 더 확인할 것

드라이버 문제가 아닌데 같은 에러가 나는 경우도 있다. config/database.php의 커넥션 이름이 잘못됐거나, .env의 DB_CONNECTION 값이 오타인 경우다.

DB_CONNECTION=pgsql   # pgsql 이 맞는지 확인 (postgres, postgresql 아님)

에러 메시지에 (Connection: pgsql) 이라고 커넥션명이 찍히니, 그 값이 config/database.php에 정의된 키와 일치하는지 먼저 보면 시간을 아낄 수 있다.

정리

• 서버리스 PHP 런타임은 용량 때문에 확장을 최소한만 포함한다
• php/conf.d/pgsql.ini 에 extension=pdo_pgsql 추가
• 레이어에도 해당 확장이 포함돼 있어야 한다 (bref-extra)
• get_loaded_extensions() 로 배포 후 확인
• redis, gd, bcmath 등 다른 확장 누락도 같은 방식으로 해결