> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

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

## 시작하기

[MongoDB](https://www.mongodb.com/resources/products/fundamentals/why-use-mongodb)는 가장 인기 있는 NoSQL 문서 지향 데이터베이스 중 하나입니다. 높은 쓰기 성능(분석이나 IoT에 최적), 고가용성(레플리카 셋에 의한 자동 페일오버), 수평 확장(샤딩), 강력한 쿼리 언어(집계·전문 검색·지리공간 쿼리)가 특징입니다.

SQL 데이터베이스의 행·열 형식과 달리 MongoDB의 각 레코드는 BSON(바이너리 JSON) 형식의 문서입니다. 애플리케이션은 이 데이터를 JSON 형식으로 얻을 수 있습니다.

```mermaid theme={null}
flowchart LR
    A["Laravel<br>애플리케이션"] --> B["mongodb/laravel-mongodb<br>패키지"]
    B --> C["MongoDB PHP 드라이버"]
    C --> D["MongoDB 서버"]

    subgraph features ["주요 용도"]
        E["Eloquent 모델"]
        F["쿼리 빌더"]
        G["캐시 드라이버"]
        H["큐 드라이버"]
        I["GridFS 파일 저장"]
        J["벡터 검색"]
        K["전문 검색 (Scout)"]
    end

    B --> E
    B --> F
    B --> G
    B --> H
    B --> I
    B --> J
    B --> K
```

<Info>
  Laravel에서 MongoDB를 사용할 때는 MongoDB 공식 팀이 관리하는 `mongodb/laravel-mongodb` 패키지 사용을 권장합니다. 이 패키지는 Eloquent 및 Laravel의 다양한 기능과 풍부한 통합을 제공합니다.
</Info>

## 설치

### MongoDB PHP 드라이버

MongoDB에 접속하려면 `mongodb` PHP 확장이 필요합니다. [Laravel Herd](https://herd.laravel.com)나 `php.new`를 사용 중이라면 이미 설치되어 있습니다. 수동으로 설치하려면 PECL을 사용합니다.

```shell theme={null}
pecl install mongodb
```

설치 상세 사항은 [MongoDB PHP 확장 설치 가이드](https://www.php.net/manual/en/mongodb.installation.php)를 참고하세요.

<Warning>
  `mongodb` PHP 확장이 CLI와 웹 서버 양쪽 모두에서 활성화되어 있는지 확인하세요. 설정이 다를 수 있습니다.
</Warning>

### MongoDB 서버 실행

MongoDB Community Server는 로컬 개발용으로 사용할 수 있습니다. Windows, macOS, Linux, Docker에서의 설치 방법은 [공식 설치 가이드](https://docs.mongodb.com/manual/administration/install-community/)를 참고하세요.

**Docker를 사용하는 경우:**

```yaml theme={null}
# 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:
```

```shell theme={null}
docker compose up -d
```

클라우드 호스팅에는 [MongoDB Atlas](https://www.mongodb.com/cloud/atlas)를 이용할 수 있습니다. Atlas 클러스터에 로컬에서 접근하려면 프로젝트의 IP 접근 목록에 자신의 IP 주소를 추가해야 합니다.

### laravel-mongodb 패키지 설치

Composer로 `mongodb/laravel-mongodb` 패키지를 설치합니다.

```shell theme={null}
composer require mongodb/laravel-mongodb
```

## 설정

### 환경 변수

`.env` 파일에 MongoDB 접속 정보를 추가합니다.

```ini theme={null}
MONGODB_URI="mongodb://localhost:27017"
MONGODB_DATABASE="laravel_app"
```

MongoDB Atlas를 사용하는 경우 접속 문자열을 Atlas의 것으로 변경합니다.

```ini theme={null}
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` 연결을 추가합니다.

```php theme={null}
'connections' => [

    // ... 기존 연결 설정 ...

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

],
```

<Tip>
  MySQL 등의 관계형 DB와 MongoDB를 동시에 사용하는 경우, `default`는 그대로 두고 `mongodb` 연결을 추가하기만 하면 됩니다. 모델마다 연결을 전환할 수 있습니다.
</Tip>

## 주요 기능

### Eloquent 모델

`MongoDB\Laravel\Eloquent\Model`을 상속받으면 일반 Eloquent 모델과 거의 같은 감각으로 MongoDB를 다룰 수 있습니다.

```php theme={null}
<?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',
    ];
}
```

<Info>
  MongoDB는 스키마리스이므로 마이그레이션이 필요 없습니다. 문서를 저장하면 컬렉션이 자동으로 생성됩니다.
</Info>

#### 기본적인 CRUD 작업

일반 Eloquent와 동일한 API로 조작할 수 있습니다.

```php theme={null}
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의 강점인 배열이나 임베디드 문서를 그대로 다룰 수 있습니다.

```php theme={null}
// 배열 필드에 push
$article->push('tags', 'database');

// 배열 필드에서 pull
$article->pull('tags', 'nosql');

// 임베디드 문서 쿼리
$articles = Article::where('meta.author', 'Taylor')->get();
```

### 쿼리 빌더

MongoDB의 쿼리 빌더를 사용해 복잡한 쿼리를 작성할 수 있습니다. 자세한 내용은 [laravel-mongodb 쿼리 빌더 문서](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/)를 참고하세요.

```php theme={null}
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 인덱스를 사용해 만료된 엔트리를 자동으로 삭제합니다. 자세한 내용은 [캐시 드라이버 문서](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/cache/)를 참고하세요.

`config/cache.php`에 스토어를 추가합니다.

```php theme={null}
'stores' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'cache',
    ],

],
```

`.env`에서 캐시 드라이버를 MongoDB로 변경합니다.

```ini theme={null}
CACHE_STORE=mongodb
```

### 큐 드라이버

MongoDB를 큐 드라이버로 사용할 수 있습니다. 자세한 내용은 [큐 드라이버 문서](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/)를 참고하세요.

`config/queue.php`에 연결을 추가합니다.

```php theme={null}
'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로 변경합니다.

```ini theme={null}
QUEUE_CONNECTION=mongodb
```

### GridFS를 사용한 파일 저장

MongoDB의 GridFS를 사용해 파일을 저장할 수 있습니다. [Flysystem용 GridFS 어댑터](https://flysystem.thephpleague.com/docs/adapter/gridfs/)를 이용합니다. 자세한 내용은 [GridFS 문서](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/filesystems/)를 참고하세요.

```shell theme={null}
composer require league/flysystem-gridfs
```

`config/filesystems.php`에 디스크를 추가합니다.

```php theme={null}
'disks' => [

    'gridfs' => [
        'driver' => 'gridfs',
        'connection' => 'mongodb',
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],
```

```php theme={null}
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](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/fundamentals/vector-search/)를 사용해 벡터 임베딩 기반 유사도 검색이 가능합니다. 텍스트, 이미지, 오디오 등의 데이터를 벡터화해 저장해 두고, 쿼리 벡터에 가장 가까운 문서를 조회하는 AI/머신러닝 대상 검색 기능입니다.

<Info>
  벡터 검색은 **MongoDB Atlas**에서만 이용 가능합니다. 로컬 MongoDB Community Server나 자체 호스팅 환경에서는 사용할 수 없습니다. 사전에 Atlas 콘솔에서 Vector Search 인덱스를 생성해 두어야 합니다.
</Info>

`vectorSearch` 메서드는 쿼리 빌더에서 사용할 수 있습니다.

```php theme={null}
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](/ko/scout)의 전문 검색 기능을 MongoDB에서 이용할 수 있습니다. 내부적으로 **MongoDB Atlas Search**를 사용하며, 퍼지 검색이나 와일드카드 검색도 지원합니다. 자세한 내용은 [Scout 엔진 문서](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/scout/)를 참고하세요.

<Info>
  MongoDB Scout 엔진도 **MongoDB Atlas**에서만 이용 가능합니다. Scout의 인덱스 컬렉션은 모델의 컬렉션과는 다른 별도의 컬렉션을 사용해야 합니다. `config/scout.php`의 `prefix` 설정(기본값은 앱 이름)이 자동으로 적용됩니다.
</Info>

`.env`에서 Scout 드라이버를 `mongodb`로 설정합니다.

```ini theme={null}
SCOUT_DRIVER=mongodb
```

모델에 `Searchable` 트레이트를 추가합니다.

```php theme={null}
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 인덱스를 생성하고 기존 데이터를 임포트합니다.

```shell theme={null}
php artisan scout:index articles
php artisan scout:import "App\Models\Article"
```

표준 Scout API로 검색할 수 있습니다.

```php theme={null}
// 전문 검색
$results = Article::search('MongoDB Laravel')->get();

// 필터가 있는 검색
$results = Article::search('쿼리 빌더')
    ->where('status', 'published')
    ->paginate(15);
```

## MySQL과의 병용

Laravel에서는 MySQL과 MongoDB를 동시에 사용할 수 있습니다. 모델마다 `$connection` 속성으로 연결을 지정합니다.

```mermaid theme={null}
flowchart TD
    A["Laravel 애플리케이션"] --> B["UserController"]
    A --> C["ArticleController"]
    B --> D["User 모델\n$connection = 'mysql'"]
    C --> E["Article 모델\n$connection = 'mongodb'"]
    D --> F["MySQL"]
    E --> G["MongoDB"]
```

```php theme={null}
// MySQL을 사용하는 일반 Eloquent 모델
class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

// MongoDB를 사용하는 모델
class Article extends \MongoDB\Laravel\Eloquent\Model
{
    protected $connection = 'mongodb';
}
```

<Info>
  MySQL 모델과 MongoDB 모델 사이에 릴레이션을 갖게 하려면 [하이브리드 릴레이션](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/relationships/)을 참고하세요.
</Info>

## 정리

<AccordionGroup>
  <Accordion title="설치 체크리스트">
    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` 연결 추가
  </Accordion>

  <Accordion title="MongoDB와 MySQL의 사용 구분">
    | 특성     | MongoDB               | MySQL             |
    | ------ | --------------------- | ----------------- |
    | 데이터 모델 | 문서(JSON/BSON)         | 테이블(행·열)          |
    | 스키마    | 스키마리스(유연함)            | 고정 스키마            |
    | 확장     | 수평 확장이 용이             | 수직 확장이 주류         |
    | 트랜잭션   | 멀티 문서 지원(v4+)         | 완전한 ACID 지원       |
    | 적합한 용도 | 로그·분석·IoT·유연한 구조의 데이터 | 구조화된 데이터·복잡한 릴레이션 |
  </Accordion>

  <Accordion title="기능별 사용 방법">
    | 기능          | 설정 위치                                                 |
    | ----------- | ----------------------------------------------------- |
    | 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 필수) |
  </Accordion>
</AccordionGroup>

## 다음 단계

<CardGroup cols={2}>
  <Card title="laravel-mongodb 공식 문서" icon="book" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/">
    Eloquent, 쿼리 빌더, 릴레이션 등 전체 기능의 상세 레퍼런스
  </Card>

  <Card title="퀵 스타트" icon="rocket" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/quick-start/">
    MongoDB와 Laravel의 기본 사용법을 빠르게 학습
  </Card>

  <Card title="데이터베이스 설정" icon="database" href="/ko/database">
    Laravel의 데이터베이스 연결 설정 기본
  </Card>

  <Card title="Eloquent 입문" icon="table" href="/ko/eloquent">
    Eloquent ORM의 기본적인 사용법
  </Card>
</CardGroup>


## Related topics

- [검색](/ko/search.md)