mongoose

KO | EN

gitlite — search

#javascript #python #typescript #java #css #html #rust #html5 #hacktoberfest #machine-learning #nodejs #python3

★ 27,473 Open GitHub ↗

비동기 환경에서 작동하도록 설계된 MongoDB 오브젝트 모델링.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Mongoose

Mongoose는 비동기 환경에서 작동하도록 설계된 [MongoDB](https://www.mongodb.org/) 객체 모델링 도구입니다. Mongoose는 [Node.js](https://nodejs.org/en/)와 [Deno](https://deno.land/)(알파)를 지원합니다.

[![Build Status](https://github.com/Automattic/mongoose/workflows/Test/badge.svg)](https://github.com/Automattic/mongoose)
[![NPM version](https://badge.fury.io/js/mongoose.svg)](http://badge.fury.io/js/mongoose)
[![Deno version](https://deno.land/badge/mongoose/version)](https://deno.land/x/mongoose)
[![Deno popularity](https://deno.land/badge/mongoose/popularity)](https://deno.land/x/mongoose)

[![npm](https://nodei.co/npm/mongoose.png)](https://www.npmjs.com/package/mongoose)

## Documentation

공식 문서 웹사이트는 [mongoosejs.com](https://mongoosejs.com/)입니다.

Mongoose 9.0.0 버전이 2025년 11월 21일에 출시되었습니다. [문서 사이트에서 9.0.0의 하위 호환성 파괴 변경 사항(backwards breaking changes)에 대한 자세한 내용](https://mongoosejs.com/docs/migrating_to_9.html)을 확인하실 수 있습니다.

## Support

* [Stack Overflow](http://stackoverflow.com/questions/tagged/mongoose)
* [Bug Reports](https://github.com/Automattic/mongoose/issues/)
* [Mongoose Slack Channel](http://slack.mongoosejs.io/)
* [Help Forum](http://groups.google.com/group/mongoose-orm)
* [MongoDB Support](https://www.mongodb.com/docs/manual/support/)

## Plugins

커뮤니티에서 만든 수백 개의 관련 모듈을 보려면 [플러그인 검색 사이트](https://plugins.mongoosejs.io/)를 확인하세요. 다음으로 [문서](https://mongoosejs.com/docs/plugins.html) 또는 [이 블로그 게시물](http://thecodebarbarian.com/2015/03/06/guide-to-mongoose-plugins)을 통해 자신만의 플러그인을 작성하는 방법을 배워보세요.

## Contributors

풀 리퀘스트(Pull request)는 언제나 환영합니다! 풀 리퀘스트는 `master` 브랜치를 기준으로 생성해주시고 [기여 가이드](https://github.com/Automattic/mongoose/blob/master/CONTRIBUTING.md)를 따라주시기 바랍니다.

풀 리퀘스트에 문서 변경 사항이 포함된 경우, 어떠한 `.html` 파일도 수정하지 **말아주세요**. `.html` 파일은 컴파일된 코드이므로 변경 사항은 `docs/*.pug`, `lib/*.js`, 또는 `test/docs/*.js` 파일에 적용해 주시기 바랍니다.

400명 이상의 모든 [기여자(Contributors)](https://github.com/Automattic/mongoose/graphs/contributors)를 확인해 보세요.

## Installation

먼저 [Node.js](https://nodejs.org/)와 [MongoDB](https://www.mongodb.org/downloads)를 설치한 후, 선호하는 패키지 관리자를 사용하여 `mongoose` 패키지를 설치하세요.

### Using npm

```sh
npm install mongoose
```

### Using pnpm

```sh
pnpm add mongoose
```

### Using Yarn

```sh
yarn add mongoose
```

### Using Bun

```sh
bun add mongoose
```

Mongoose 6.8.0에는 [Deno](https://deno.land/)에 대한 알파 지원도 포함되어 있습니다.

## Importing

```javascript
// Using Node.js `require()`
const mongoose = require('mongoose');

// Using ES6 imports
import mongoose from 'mongoose';
```

또는 다음과 같이 [CommonJS 지원을 위해 Deno의 `createRequire()`를 사용할 수 있습니다](https://deno.land/std@0.113.0/node/README.md?source=#commonjs-modules-loading).

```javascript
import { createRequire } from 'https://deno.land/std@0.177.0/node/module.ts';
const require = createRequire(import.meta.url);

const mongoose = require('mongoose');

mongoose.connect('mongodb://127.0.0.1:27017/test')
  .then(() => console.log('Connected!'));
```

그런 다음 아래 명령어를 사용하여 위 스크립트를 실행할 수 있습니다.

```sh
deno run --allow-net --allow-read --allow-sys --allow-env mongoose-test.js
```

## Mongoose Studio

[Mongoose Studio](https://mongoosestudio.app?utm_source=mongoose&utm_medium=referral&utm_campaign=readme)는 이미 Mongoose를 사용하는 애플리케이션을 위해 Mongoose 팀에서 구축한 무료 오픈소스 브라우저 기반 MongoDB GUI입니다. npm에서 `@mongoosejs/studio`를 설치하여 Express 미들웨어로 앱과 함께 실행하거나 Vercel 또는 Netlify에 배포할 수 있습니다. 이를 통해 데이터를 호스팅된 타사 워크스페이스로 이동하거나 원본 MongoDB 연결 문자열을 공유하지 않고도 문서 조회 및 편집, 자동완성 기능이 있는 기존 모델과 스키마를 이용한 쿼리, 대시보드 구축, GeoJSON 시각화 및 편집, AI 지원 MongoDB 워크플로우를 사용할 수 있습니다.

## Mongoose for Enterprise

Tidelift Subscription의 일부로 제공됩니다.

mongoose와 수많은 다른 패키지의 메인이너들은 여러분이 애플리케이션을 구축하는 데 사용하는 오픈 소스 의존성에 대해 상업적 지원과 유지보수를 제공하기 위해 Tidelift와 협력하고 있습니다. 사용하는 정확한 의존성의 메인이너에게 비용을 지불하면서, 시간을 절약하고 위험을 줄이며 코드 무결성을 향상시키세요. [자세히 알아보기](https://tidelift.com/subscription/pkg/npm-mongoose?utm_source=npm-mongoose&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## 개요

### MongoDB에 연결하기

먼저, 연결을 정의해야 합니다. 앱이 단일 데이터베이스만 사용하는 경우 `mongoose.connect`를 사용해야 합니다. 추가 연결을 생성해야 하는 경우 `mongoose.createConnection`을 사용하세요.

`connect`와 `createConnection` 모두 `mongodb://` URI 또는 `host, database, port, options` 매개변수를 받습니다.

```js
await mongoose.connect('mongodb://127.0.0.1/my_database');
```

연결되면 `Connection` 인스턴스에서 `open` 이벤트가 발생합니다. `mongoose.connect`를 사용하는 경우 `Connection`은 `mongoose.connection`입니다. 그렇지 않은 경우 `mongoose.createConnection`의 반환 값은 `Connection`입니다.

**참고:** *로컬 연결이 실패하면 localhost 대신 127.0.0.1을 사용해 보세요. 로컬 호스트 이름이 변경된 경우 때때로 문제가 발생할 수 있습니다.*

**중요!** Mongoose는 데이터베이스에 연결될 때까지 모든 명령을 버퍼링합니다. 즉, 모델을 정의하거나 쿼리를 실행하기 위해 MongoDB에 연결될 때까지 기다릴 필요가 없습니다.

### 모델 정의하기

모델은 `Schema` 인터페이스를 통해 정의됩니다.

```js
const Schema = mongoose.Schema;
const ObjectId = Schema.ObjectId;

const BlogPost = new Schema({
  author: ObjectId,
  title: String,
  body: String,
  date: Date
});
```

문서의 구조와 저장할 데이터의 타입을 정의하는 것 외에도, 스키마는 다음의 정의를 처리합니다:

* [Validators](https://mongoosejs.com/docs/validation.html) (비동기 및 동기)
* [Defaults](https://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-default)
* [Getters](https://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-get)
* [Setters](https://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-set)
* [Indexes](https://mongoosejs.com/docs/guide.html#indexes)
* [Middleware](https://mongoosejs.com/docs/middleware.html)
* [Methods](https://mongoosejs.com/docs/guide.html#methods) 정의
* [Statics](https://mongoosejs.com/docs/guide.html#statics) 정의
* [Plugins](https://mongoosejs.com/docs/plugins.html)
* [pseudo-JOINs](https://mongoosejs.com/docs/populate.html)

다음 예제는 이러한 기능 중 일부를 보여줍니다:

```js
const Comment = new Schema({
  name: { type: String, default: 'hahaha' },
  age: { type: Number, min: 18, index: true },
  bio: { type: String, match: /[a-z]/ },
  date: { type: Date, default: Date.now },
  buff: Buffer
});

// a setter
Comment.path('name').set(function(v) {
  return capitalize(v);
});

// middleware
Comment.pre('save', function(next) {
  notify(this.get('email'));
  next();
});
```

### 모델에 접근하기

`mongoose.model('ModelName', mySchema)`를 통해 모델을 정의하고 나면, 동일한 함수를 통해 접근할 수 있습니다.

```js
const MyModel = mongoose.model('ModelName');
```

또는 한 번에 모두 수행할 수도 있습니다.

```js
const MyModel = mongoose.model('ModelName', mySchema);
```

첫 번째 인자는 모델이 속한 컬렉션의 *단수* 이름입니다. **Mongoose는 자동으로 모델 이름의 *복수* 버전을 찾습니다.** 예를 들어, 다음을 사용하는 경우

```js
const MyModel = mongoose.model('Ticket', mySchema);
```

`MyModel`은 `ticket` 컬렉션이 아니라 **tickets** 컬렉션을 사용하게 됩니다. 더 자세한 내용은 [model docs](https://mongoosejs.com/docs/api/mongoose.html#mongoose_Mongoose-model)를 읽어보세요.

모델이 준비되면 인스턴스화하고 저장할 수 있습니다:

```js
const instance = new MyModel();
instance.my.key = 'hello';
await instance.save();
```

또는 동일한 컬렉션에서 문서를 찾을 수 있습니다.

```js
await MyModel.find({});
```

`findOne`, `findById`, `update` 등도 사용할 수 있습니다.

```js
const instance = await MyModel.findOne({ /* ... */ });
console.log(instance.my.key); // 'hello'
```

자세한 내용은 [the docs](https://mongoosejs.com/docs/queries.html)를 참고하세요.

**중요!** `mongoose.createConnection()`을 사용하여 별도의 연결을 열었지만 `mongoose.model('ModelName')`을 통해 모델에 접근하려고 하면 활성 데이터베이스 연결에 연결되어 있지 않기 때문에 예상대로 작동하지 않습니다. 이 경우 생성한 연결을 통해 모델에 접근해야 합니다:

```js
const conn = mongoose.createConnection('your connection string');
const MyModel = conn.model('ModelName', schema);
const m = new MyModel();
await m.save(); // works
```

```js
const conn = mongoose.createConnection('your connection string');
const MyModel = mongoose.model('ModelName', schema);
const m = new MyModel();
await m.save(); // does not work b/c the default connection object was never connected
```

### Embedded Documents

첫 번째 예제 스니펫에서는 다음과 같이 생긴 Schema의 키를 정의했습니다:

```txt
comments: [Comment]
```

여기서 `Comment`는 우리가 생성한 `Schema`입니다. 즉, 임베디드 문서를 생성하는 것은 다음과 같이 간단합니다:

```js
// retrieve my model
const BlogPost = mongoose.model('BlogPost');

// create a blog post
const post = new BlogPost();

// create a comment
post.comments.push({ title: 'My comment' });

await post.save();
```

문서를 삭제하는 것도 마찬가지입니다:

```js
const post = await BlogPost.findById(myId);
post.comments[0].deleteOne();
await post.save();
```

임베디드 문서는 모델과 동일한 모든 기능(기본값, 유효성 검사기, 미들웨어)을 지원합니다.

### Middleware

[docs](https://mongoosejs.com/docs/middleware.html) 페이지를 참고하세요.

#### Intercepting and mutating method arguments

미들웨어를 통해 메서드 인수를 가로챌 수 있습니다.

예를 들어, 누군가 문서의 경로(`set`)를 새 값으로 설정할 때마다 문서에 대한 변경 사항을 브로드캐스트할 수 있습니다:

```js
schema.pre('set', function(next, path, val, typel) {
  // `this` is the current Document
  this.emit('set', path, val);

// Pass control to the next pre
  next();
});
```

또한, 들어오는 `method` 인수를 변환하여 후속 미들웨어가 해당 인수에 대해 다른 값을 보도록 할 수 있습니다. 그렇게 하려면 새 값을 `next`에 전달하기만 하면 됩니다:

```js
schema.pre(method, function firstPre(next, methodArg1, methodArg2) {
  // Mutate methodArg1
  next('altered-' + methodArg1.toString(), methodArg2);
});

// pre declaration is chainable
schema.pre(method, function secondPre(next, methodArg1, methodArg2) {
  console.log(methodArg1);
  // => 'altered-originalValOfMethodArg1'

console.log(methodArg2);
  // => 'originalValOfMethodArg2'

// Passing no arguments to `next` automatically passes along the current argument values
  // i.e., the following `next()` is equivalent to `next(methodArg1, methodArg2)`
  // and also equivalent to, with the example method arg
  // values, `next('altered-originalValOfMethodArg1', 'originalValOfMethodArg2')`
  next();
});
```

#### Schema gotcha

스키마에서 사용되는 `type`은 Mongoose 내에서 특별한 의미를 가집니다. 스키마에 중첩 속성으로 `type`을 사용해야 하는 경우 반드시 객체 표기법을 사용해야 합니다:

```js
new Schema({
  broken: { type: Boolean },
  asset: {
    name: String,
    type: String // uh oh, it broke. asset will be interpreted as String
  }
});

new Schema({
  works: { type: Boolean },
  asset: {
    name: String,
    type: { type: String } // works. asset is an object with a type property
  }
});
```

### Driver Access

Mongoose는 [official MongoDB Node.js driver](https://github.com/mongodb/node-mongodb-native) 기반으로 구축되어 있습니다. 각 mongoose 모델은 [native MongoDB driver collection](http://mongodb.github.io/node-mongodb-native/2.1/api/Collection.html)에 대한 참조를 유지합니다. 컬렉션 객체는 `YourModel.collection`을 사용하여 접근할 수 있습니다. 하지만 컬렉션 객체를 직접 사용하면 훅, 유효성 검사 등 모든 mongoose 기능이 우회됩니다. 한 가지 주목할 만한 예외는 `YourModel.collection`이 여전히 명령어를 버퍼링한다는 점입니다. 따라서 `YourModel.collection.find()`는 커서를 반환하지 **않습니다**.

## API 문서

[dox](https://github.com/tj/dox) 및 [acquit](https://github.com/vkarpov15/acquit)을 사용하여 생성된 [Mongoose API documentation](https://mongoosejs.com/docs/api/mongoose.html)을 확인하세요.

## 연관 프로젝트

### MongoDB 러너

* [run-rs](https://www.npmjs.com/package/run-rs)
* [mongodb-memory-server](https://www.npmjs.com/package/mongodb-memory-server)
* [mongodb-topology-manager](https://www.npmjs.com/package/mongodb-topology-manager)

### 비공식 CLI

* [mongoosejs-cli](https://www.npmjs.com/package/mongoosejs-cli)

### 데이터 시딩

* [dookie](https://www.npmjs.com/package/dookie)
* [seedgoose](https://www.npmjs.com/package/seedgoose)
* [mongoose-data-seed](https://www.npmjs.com/package/mongoose-data-seed)

### Express 세션 스토어

* [connect-mongodb-session](https://www.npmjs.com/package/connect-mongodb-session)
* [connect-mongo](https://www.npmjs.com/package/connect-mongo)

## 라이선스

본 소프트웨어 및 관련 문서 파일('소프트웨어')의 복사본을 얻는 모든 사람에게, 사용, 복사, 수정, 병합, 출판, 배포, 서브라이선스, 및/또는 소프트웨어 복사본 판매를 포함하되 이에 제한되지 않는 제한 없는 권한이 본래 무료로 부여되며, 소프트웨어가 제공된 사람들은 다음 조건을 준수해야 합니다.

본 소프트웨어는 상품성, 특정 목적에의 적합성, 비침해 보증을 포함하되 이에 제한되지 않고 명시적이든 묵시적이든 어떠한 보증 없이 '있는 그대로' 제공됩니다. 어떠한 경우에도 작성자나 저작권자는 계약, 불법행위 또는 기타 사유로 인해 소프트웨어와 관련하여 또는 그 사용이나 기타 거래와 관련하여 발생하는 어떠한 청구, 손해 또는 기타 책임에 대해서도 책임을 지지 않습니다.

mongoose

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README