MongoDB

업데이트됨

번역일: 2026년 9월 14일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 9월 14일
번역 갱신: 2026년 9월 14일

MongoDB

소개
설치
설정
주요 기능

소개

MongoDB는 가장 널리 사용되는 NoSQL 문서 지향 데이터베이스 중 하나입니다. 높은 쓰기 처리량(분석 시스템이나 IoT 서비스에 유용)과 뛰어난 가용성(자동 장애 조치가 가능한 복제 셋을 손쉽게 구성할 수 있음)이 장점으로 꼽힙니다. 또한 샤딩을 통한 수평적 확장이 쉽고, 집계(aggregation), 텍스트 검색, 지리 공간 쿼리 등을 지원하는 강력한 쿼리 언어를 제공합니다.

SQL 데이터베이스가 행과 열로 구성된 테이블에 데이터를 저장하는 것과 달리, MongoDB의 각 레코드는 BSON(데이터의 이진 표현 형식)으로 기술된 "문서(document)"입니다. 애플리케이션은 이 데이터를 JSON 형태로 조회할 수 있으며, 문서, 배열, 임베디드 문서, 바이너리 데이터 등 다양한 데이터 타입을 지원합니다.

Laravel에서 MongoDB를 사용하기 전에, Composer를 통해 mongodb/laravel-mongodb 패키지를 설치하는 것을 권장합니다. laravel-mongodb 패키지는 MongoDB에서 공식적으로 관리하는 패키지이며, PHP 자체에서도 MongoDB 드라이버를 통해 MongoDB를 네이티브로 지원하지만 Laravel MongoDB 패키지를 사용하면 Eloquent를 비롯한 여러 Laravel 기능과 훨씬 더 풍부하게 통합할 수 있습니다.

composer require mongodb/laravel-mongodb

설치

MongoDB 드라이버

MongoDB 데이터베이스에 연결하려면 mongodb PHP 확장이 필요합니다. Laravel Herd로 로컬 개발 환경을 구성했거나 php.new를 통해 PHP를 설치했다면 이 확장이 이미 설치되어 있을 것입니다. 만약 수동으로 설치해야 한다면 PECL을 통해 설치할 수 있습니다.

pecl install mongodb

또는 PHP 공식 확장 설치 도구인 PIE를 사용해 설치할 수도 있습니다.

pie install mongodb/mongodb-extension

MongoDB PHP 확장 설치에 대한 더 자세한 내용은 MongoDB PHP 확장 설치 안내 문서를 참고하세요.

MongoDB 서버 실행하기

MongoDB Community Server를 사용하면 로컬 환경에서 직접 MongoDB를 실행할 수 있으며, Windows, macOS, Linux는 물론 Docker 컨테이너 형태로도 설치할 수 있습니다. 설치 방법은 MongoDB Community 공식 설치 가이드를 참고하세요.

MongoDB 서버의 연결 문자열은 .env 파일에 설정합니다.

MONGODB_URI="mongodb://localhost:27017"
MONGODB_DATABASE="laravel_app"

클라우드 환경에서 MongoDB를 운영하고 싶다면 MongoDB Atlas 사용을 고려해 볼 수 있습니다. 로컬 애플리케이션에서 MongoDB Atlas 클러스터에 접속하려면, 프로젝트의 IP 접근 목록(IP Access List)에 현재 사용 중인 IP 주소를 클러스터 네트워크 설정에 추가해야 합니다.

MongoDB Atlas의 연결 문자열도 마찬가지로 .env 파일에 설정합니다.

MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<dbname>?retryWrites=true&w=majority"
MONGODB_DATABASE="laravel_app"

Laravel MongoDB 패키지 설치

마지막으로 Composer를 사용해 Laravel MongoDB 패키지를 설치합니다.

composer require mongodb/laravel-mongodb

NOTE

mongodb PHP 확장이 설치되어 있지 않으면 패키지 설치가 실패합니다. CLI 환경과 웹 서버 환경의 PHP 설정이 서로 다를 수 있으므로, 두 환경 모두에서 확장이 활성화되어 있는지 반드시 확인하세요.

설정

MongoDB 연결은 애플리케이션의 config/database.php 설정 파일을 통해 구성합니다. 이 파일에 mongodb 드라이버를 사용하는 mongodb 연결을 추가하세요.

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => env('MONGODB_URI', 'mongodb://localhost:27017'),
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],
],

주요 기능

설정을 마쳤다면 이제 애플리케이션에서 mongodb 패키지와 데이터베이스 연결을 활용해 다양한 강력한 기능을 사용할 수 있습니다.

Eloquent 사용하기: 모델을 MongoDB 컬렉션에 저장할 수 있습니다. Laravel MongoDB 패키지는 표준 Eloquent 기능 외에도 임베디드 관계(embedded relationships) 같은 추가 기능을 제공합니다. 또한 MongoDB 드라이버에 직접 접근할 수 있어 원시 쿼리(raw query)나 집계 파이프라인(aggregation pipeline) 같은 작업도 실행할 수 있습니다.
복잡한 쿼리 작성: 쿼리 빌더를 통해 복잡한 쿼리를 작성할 수 있습니다.
유사도 / 벡터 검색: 벡터 임베딩과 Eloquent의 vectorSearch 메서드를 사용해 유사도 검색을 수행할 수 있습니다.
mongodb 캐시 드라이버: TTL 인덱스와 같은 MongoDB의 기능을 활용해 만료된 캐시 항목을 자동으로 제거하도록 최적화되어 있습니다.
큐 Job 디스패치 및 처리: mongodb 큐 드라이버로 큐에 등록된 Job을 디스패치하고 처리할 수 있습니다.
GridFS를 이용한 파일 저장: Flysystem용 GridFS 어댑터를 통해 파일을 저장할 수 있습니다.
전문 검색(Full-text search): mongodb Scout 엔진을 사용해 전문 검색을 구현할 수 있습니다.
데이터베이스 연결이나 Eloquent를 사용하는 대부분의 서드파티 패키지도 MongoDB와 함께 사용할 수 있습니다.

MongoDB와 Laravel을 함께 사용하는 방법을 더 자세히 알아보려면 MongoDB의 빠른 시작 가이드를 참고하세요.