MongoDB

Laravel 애플리케이션에서 MongoDB를 사용하는 방법. 드라이버 설치부터 설정, Eloquent 모델, 쿼리 빌더, 캐시·큐 드라이버로서의 활용까지 설명합니다.

​

시작하기

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을 사용합니다.

pecl install mongodb

설치 상세 사항은 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:

docker compose up -d

클라우드 호스팅에는 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로 변경합니다.

CACHE_STORE=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로 변경합니다.

QUEUE_CONNECTION=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로 설정합니다.

SCOUT_DRIVER=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 모델 사이에 릴레이션을 갖게 하려면 하이브리드 릴레이션을 참고하세요.

​

정리

설치 체크리스트

1. pecl install mongodb로 PHP 확장 설치
2. MongoDB 서버 실행(로컬 또는 Docker, 혹은 Atlas)
3. composer require mongodb/laravel-mongodb로 패키지 설치
4. .env에 MONGODB_URI와 MONGODB_DATABASE 설정
5. config/database.php에 mongodb 연결 추가

MongoDB와 MySQL의 사용 구분

특성	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의 기본적인 사용법