시작하기 MongoDB 는 가장 인기 있는 NoSQL 문서 지향 데이터베이스 중 하나입니다. 높은 쓰기 성능(분석이나 IoT에 최적), 고가용성(레플리카 셋에 의한 자동 페일오버), 수평 확장(샤딩), 강력한 쿼리 언어(집계·전문 검색·지리공간 쿼리)가 특징입니다.SQL 데이터베이스의 행·열 형식과 달리 MongoDB의 각 레코드는 BSON(바이너리 JSON) 형식의 문서입니다. 애플리케이션은 이 데이터를 JSON 형식으로 얻을 수 있습니다.
Laravel에서 MongoDB를 사용할 때는 MongoDB 공식 팀이 관리하는 mongodb/laravel-mongodb 패키지 사용을 권장합니다. 이 패키지는 Eloquent 및 Laravel의 다양한 기능과 풍부한 통합을 제공합니다.
MongoDB PHP 드라이버 MongoDB에 접속하려면 mongodb PHP 확장이 필요합니다. Laravel Herd 나 php.new를 사용 중이라면 이미 설치되어 있습니다. 수동으로 설치하려면 PECL을 사용합니다.
설치 상세 사항은 MongoDB PHP 확장 설치 가이드 를 참고하세요.
mongodb PHP 확장이 CLI와 웹 서버 양쪽 모두에서 활성화되어 있는지 확인하세요. 설정이 다를 수 있습니다.
MongoDB 서버 실행 MongoDB Community Server는 로컬 개발용으로 사용할 수 있습니다. Windows, macOS, Linux, Docker에서의 설치 방법은 공식 설치 가이드 를 참고하세요.
Docker를 사용하는 경우: # docker-compose.yml services : mongodb : image : mongo:8 ports : - "27017:27017" environment : MONGO_INITDB_ROOT_USERNAME : root MONGO_INITDB_ROOT_PASSWORD : password MONGO_INITDB_DATABASE : laravel_app volumes : - mongodb_data:/data/db volumes : mongodb_data :
클라우드 호스팅에는 MongoDB Atlas 를 이용할 수 있습니다. Atlas 클러스터에 로컬에서 접근하려면 프로젝트의 IP 접근 목록에 자신의 IP 주소를 추가해야 합니다.
laravel-mongodb 패키지 설치 Composer로 mongodb/laravel-mongodb 패키지를 설치합니다.
composer require mongodb/laravel-mongodb
환경 변수 .env 파일에 MongoDB 접속 정보를 추가합니다.MONGODB_URI = "mongodb://localhost:27017" MONGODB_DATABASE = "laravel_app"
MongoDB Atlas를 사용하는 경우 접속 문자열을 Atlas의 것으로 변경합니다.
MONGODB_URI = "mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<dbname>?retryWrites=true&w=majority" MONGODB_DATABASE = "laravel_app"
config/database.php config/database.php의 connections 배열에 mongodb 연결을 추가합니다.'connections' => [ // ... 기존 연결 설정 ... 'mongodb' => [ 'driver' => 'mongodb' , 'dsn' => env ( 'MONGODB_URI' , 'mongodb://localhost:27017' ), 'database' => env ( 'MONGODB_DATABASE' , 'laravel_app' ), ], ],
MySQL 등의 관계형 DB와 MongoDB를 동시에 사용하는 경우, default는 그대로 두고 mongodb 연결을 추가하기만 하면 됩니다. 모델마다 연결을 전환할 수 있습니다.
주요 기능 Eloquent 모델 MongoDB\Laravel\Eloquent\Model을 상속받으면 일반 Eloquent 모델과 거의 같은 감각으로 MongoDB를 다룰 수 있습니다.<? php namespace App\Models ; use MongoDB\Laravel\Eloquent\ Model ; class Article extends Model { protected $connection = 'mongodb' ; protected $collection = 'articles' ; // 컬렉션명(생략 시 클래스명에서 자동 생성) protected $fillable = [ 'title' , 'body' , 'tags' , 'published_at' , ]; }
MongoDB는 스키마리스이므로 마이그레이션이 필요 없습니다. 문서를 저장하면 컬렉션이 자동으로 생성됩니다.
기본적인 CRUD 작업 일반 Eloquent와 동일한 API로 조작할 수 있습니다.
use App\Models\ Article ; // 생성 $article = Article :: create ([ 'title' => 'MongoDB 입문' , 'body' => 'MongoDB는 문서 지향 데이터베이스입니다.' , 'tags' => [ 'nosql' , 'mongodb' , 'laravel' ], 'published_at' => now (), ]); // 조회 $article = Article :: find ( '64f1a2b3c4d5e6f7a8b9c0d1' ); $articles = Article :: where ( 'tags' , 'nosql' ) -> get (); // 수정 $article -> update ([ 'title' => '개정판 MongoDB 입문' ]); // 삭제 $article -> delete ();
배열·임베디드 문서 MongoDB의 강점인 배열이나 임베디드 문서를 그대로 다룰 수 있습니다.
// 배열 필드에 push $article -> push ( 'tags' , 'database' ); // 배열 필드에서 pull $article -> pull ( 'tags' , 'nosql' ); // 임베디드 문서 쿼리 $articles = Article :: where ( 'meta.author' , 'Taylor' ) -> get ();
쿼리 빌더 MongoDB의 쿼리 빌더를 사용해 복잡한 쿼리를 작성할 수 있습니다. 자세한 내용은 laravel-mongodb 쿼리 빌더 문서 를 참고하세요.
use Illuminate\Support\Facades\ DB ; // 기본 쿼리 $articles = DB :: connection ( 'mongodb' ) -> collection ( 'articles' ) -> where ( 'tags' , 'laravel' ) -> orderBy ( 'published_at' , 'desc' ) -> limit ( 10 ) -> get (); // 집계 파이프라인 $stats = DB :: connection ( 'mongodb' ) -> collection ( 'orders' ) -> raw ( function ( $collection ) { return $collection -> aggregate ([ [ '$group' => [ '_id' => '$status' , 'total' => [ '$sum' => '$amount' ]]], [ '$sort' => [ 'total' => - 1 ]], ]); });
캐시 드라이버 MongoDB 캐시 드라이버는 TTL 인덱스를 사용해 만료된 엔트리를 자동으로 삭제합니다. 자세한 내용은 캐시 드라이버 문서 를 참고하세요.
config/cache.php에 스토어를 추가합니다.'stores' => [ 'mongodb' => [ 'driver' => 'mongodb' , 'connection' => 'mongodb' , 'collection' => 'cache' , ], ],
.env에서 캐시 드라이버를 MongoDB로 변경합니다.큐 드라이버 MongoDB를 큐 드라이버로 사용할 수 있습니다. 자세한 내용은 큐 드라이버 문서 를 참고하세요.
config/queue.php에 연결을 추가합니다.'connections' => [ 'mongodb' => [ 'driver' => 'mongodb' , 'connection' => 'mongodb' , 'collection' => 'jobs' , 'queue' => env ( 'MONGODB_QUEUE' , 'default' ), 'retry_after' => ( int ) env ( 'MONGODB_QUEUE_RETRY_AFTER' , 90 ), 'after_commit' => false , ], ],
.env에서 큐 연결을 MongoDB로 변경합니다.GridFS를 사용한 파일 저장 MongoDB의 GridFS를 사용해 파일을 저장할 수 있습니다. Flysystem용 GridFS 어댑터 를 이용합니다. 자세한 내용은 GridFS 문서 를 참고하세요.
composer require league/flysystem-gridfs
config/filesystems.php에 디스크를 추가합니다.'disks' => [ 'gridfs' => [ 'driver' => 'gridfs' , 'connection' => 'mongodb' , 'database' => env ( 'MONGODB_DATABASE' , 'laravel_app' ), ], ],
use Illuminate\Support\Facades\ Storage ; // 파일 업로드 Storage :: disk ( 'gridfs' ) -> put ( 'file.pdf' , $contents ); // 파일 조회 $contents = Storage :: disk ( 'gridfs' ) -> get ( 'file.pdf' );
벡터 검색(Vector Search) MongoDB Atlas Vector Search 를 사용해 벡터 임베딩 기반 유사도 검색이 가능합니다. 텍스트, 이미지, 오디오 등의 데이터를 벡터화해 저장해 두고, 쿼리 벡터에 가장 가까운 문서를 조회하는 AI/머신러닝 대상 검색 기능입니다.벡터 검색은 MongoDB Atlas 에서만 이용 가능합니다. 로컬 MongoDB Community Server나 자체 호스팅 환경에서는 사용할 수 없습니다. 사전에 Atlas 콘솔에서 Vector Search 인덱스를 생성해 두어야 합니다.
vectorSearch 메서드는 쿼리 빌더에서 사용할 수 있습니다.use App\Models\ Article ; // 쿼리 문자열로부터 임베딩 생성(예: OpenAI API 등) $queryVector = getEmbedding ( 'MongoDB란 무엇인가' ); // float[] 배열 $results = Article :: query () -> vectorSearch ( index : 'vector_index' , // Atlas Vector Search 인덱스명 path : 'embedding' , // 벡터가 저장된 필드명 queryVector : $queryVector , limit : 10 , // 반환할 문서 수 numCandidates : 100 , // 후보 수(ANN 검색 시 지정) ); // 각 문서에는 vectorSearchScore가 부여됨 foreach ( $results as $result ) { echo $result -> title . ': ' . $result -> vectorSearchScore ; }
전문 검색(Scout 엔진) mongodb Scout 엔진을 사용해 Laravel Scout 의 전문 검색 기능을 MongoDB에서 이용할 수 있습니다. 내부적으로 MongoDB Atlas Search 를 사용하며, 퍼지 검색이나 와일드카드 검색도 지원합니다. 자세한 내용은 Scout 엔진 문서 를 참고하세요.MongoDB Scout 엔진도 MongoDB Atlas 에서만 이용 가능합니다. Scout의 인덱스 컬렉션은 모델의 컬렉션과는 다른 별도의 컬렉션을 사용해야 합니다. config/scout.php의 prefix 설정(기본값은 앱 이름)이 자동으로 적용됩니다.
.env에서 Scout 드라이버를 mongodb로 설정합니다.모델에 Searchable 트레이트를 추가합니다.
use Laravel\Scout\ Searchable ; use MongoDB\Laravel\Eloquent\ Model ; class Article extends Model { use Searchable ; // 검색 인덱스에 포함할 필드 지정 public function toSearchableArray () : array { return [ 'title' => $this -> title , 'body' => $this -> body , 'tags' => $this -> tags , ]; } }
Scout 인덱스를 생성하고 기존 데이터를 임포트합니다.
php artisan scout:index articles php artisan scout:import "App\Models\Article"
표준 Scout API로 검색할 수 있습니다.
// 전문 검색 $results = Article :: search ( 'MongoDB Laravel' ) -> get (); // 필터가 있는 검색 $results = Article :: search ( '쿼리 빌더' ) -> where ( 'status' , 'published' ) -> paginate ( 15 );
MySQL과의 병용 Laravel에서는 MySQL과 MongoDB를 동시에 사용할 수 있습니다. 모델마다 $connection 속성으로 연결을 지정합니다.
// MySQL을 사용하는 일반 Eloquent 모델 class User extends \Illuminate\Database\Eloquent\ Model { protected $connection = 'mysql' ; } // MongoDB를 사용하는 모델 class Article extends \MongoDB\Laravel\Eloquent\ Model { protected $connection = 'mongodb' ; }
MySQL 모델과 MongoDB 모델 사이에 릴레이션을 갖게 하려면 하이브리드 릴레이션 을 참고하세요.
pecl install mongodb로 PHP 확장 설치MongoDB 서버 실행(로컬 또는 Docker, 혹은 Atlas)
composer require mongodb/laravel-mongodb로 패키지 설치.env에 MONGODB_URI와 MONGODB_DATABASE 설정config/database.php에 mongodb 연결 추가
특성 MongoDB MySQL 데이터 모델 문서(JSON/BSON) 테이블(행·열) 스키마 스키마리스(유연함) 고정 스키마 확장 수평 확장이 용이 수직 확장이 주류 트랜잭션 멀티 문서 지원(v4+) 완전한 ACID 지원 적합한 용도 로그·분석·IoT·유연한 구조의 데이터 구조화된 데이터·복잡한 릴레이션
기능 설정 위치 Eloquent 모델 MongoDB\Laravel\Eloquent\Model 상속쿼리 빌더 DB::connection('mongodb')->collection(...)캐시 config/cache.php + CACHE_STORE=mongodb큐 config/queue.php + QUEUE_CONNECTION=mongodb파일 저장 config/filesystems.php + GridFS 어댑터벡터 검색 Model::query()->vectorSearch(...) (Atlas 필수)전문 검색 SCOUT_DRIVER=mongodb + Searchable 트레이트 (Atlas 필수)
다음 단계
laravel-mongodb 공식 문서 Eloquent, 쿼리 빌더, 릴레이션 등 전체 기능의 상세 레퍼런스
퀵 스타트 MongoDB와 Laravel의 기본 사용법을 빠르게 학습
데이터베이스 설정 Laravel의 데이터베이스 연결 설정 기본
Eloquent 입문 Eloquent ORM의 기본적인 사용법
