MongoDB

번역일: 2026년 6월 20일

MongoDB

소개
설치
설정
주요 기능

소개

MongoDB는 가장 널리 사용되는 NoSQL 문서 지향(document-oriented) 데이터베이스입니다. 대량의 쓰기 작업(분석, IoT 등)과 고가용성(자동 페일오버를 포함한 레플리카 셋 구성)이 필요한 환경에 적합하며, 수평 확장을 위한 샤딩도 손쉽게 구성할 수 있습니다. 또한 집계(aggregation), 전문 검색(text search), 지리공간(geospatial) 쿼리 등 강력한 쿼리 기능을 제공합니다.

SQL 데이터베이스처럼 행과 열로 구성된 테이블에 데이터를 저장하는 대신, MongoDB는 각 레코드를 BSON(바이너리 JSON) 형식의 문서로 저장합니다. 애플리케이션은 이 데이터를 JSON 형태로 읽어올 수 있으며, 문서, 배열, 중첩 문서, 바이너리 데이터 등 다양한 데이터 타입을 지원합니다.

Laravel에서 MongoDB를 사용하려면 Composer를 통해 mongodb/laravel-mongodb 패키지를 설치하는 것을 권장합니다. 이 패키지는 MongoDB에서 공식적으로 관리하며, PHP의 기본 MongoDB 드라이버보다 훨씬 풍부한 Eloquent 및 Laravel 기능 통합을 제공합니다:

composer require mongodb/laravel-mongodb

설치

MongoDB 드라이버

MongoDB 데이터베이스에 연결하려면 PHP mongodb 확장(extension)이 필요합니다. Laravel Herd를 사용하거나 php.new를 통해 PHP를 설치했다면 이 확장이 이미 포함되어 있습니다. 직접 설치해야 하는 경우 PECL을 통해 설치할 수 있습니다:

pecl install mongodb

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 사용을 검토해 보세요. Atlas 클러스터에 로컬 애플리케이션에서 접근하려면, 클러스터의 네트워크 설정에서 IP 액세스 목록에 본인의 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 확장이 설치되어 있지 않으면 패키지 설치가 실패합니다. PHP 설정은 CLI 환경과 웹 서버 환경이 다를 수 있으므로, 양쪽 모두에서 확장이 활성화되어 있는지 반드시 확인하세요.

설정

MongoDB 연결은 config/database.php 파일에서 구성합니다. 아래와 같이 mongodb 드라이버를 사용하는 연결 항목을 추가하세요:

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

주요 기능

설정이 완료되면 mongodb 패키지와 데이터베이스 연결을 활용해 다양한 강력한 기능을 사용할 수 있습니다:

Eloquent 모델 사용: 모델을 MongoDB 컬렉션에 저장할 수 있습니다. 기본 Eloquent 기능 외에도 임베디드 관계(embedded relationships) 등 MongoDB 전용 기능을 추가로 제공하며, 원시 쿼리나 집계 파이프라인 같은 MongoDB 드라이버 작업에도 직접 접근할 수 있습니다.
복잡한 쿼리 작성: 쿼리 빌더를 사용해 복잡한 쿼리를 간결하게 표현할 수 있습니다.
캐시 드라이버: mongodb 캐시 드라이버는 TTL 인덱스 등 MongoDB 기능을 활용해 만료된 캐시 항목을 자동으로 제거하도록 최적화되어 있습니다.
큐 드라이버: mongodb 큐 드라이버를 통해 Job을 디스패치하고 처리할 수 있습니다.
GridFS 파일 저장: Flysystem용 GridFS 어댑터를 통해 파일을 GridFS에 저장할 수 있습니다.
데이터베이스 연결이나 Eloquent를 사용하는 대부분의 서드파티 패키지를 MongoDB와 함께 사용할 수 있습니다.

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