ts-migrate-mongoose를 사용한 MongoDB 마이그레이션 처리 방법

데이터베이스 마이그레이션은 데이터베이스에 대한 수정 사항입니다. 이러한 수정 사항에는 테이블의 스키마 변경, 레코드 집합의 데이터 업데이트, 데이터 시딩 또는 레코드 범위 삭제가 포함될 수 있습니다.

데이터베이스 마이그레이션은 일반적으로 애플리케이션이 시작되기 전에 실행되며, 동일한 데이터베이스에 대해 한 번 이상 성공적으로 실행되지 않습니다. 데이터베이스 마이그레이션 도구는 데이터베이스에서 실행된 마이그레이션의 이력을 저장하여 향후 목적에 따라 추적할 수 있도록 합니다.

이 기사에서는 최소한의 Node.js API 애플리케이션에서 데이터베이스 마이그레이션을 설정하고 실행하는 방법을 배우게 됩니다. 우리는 ts-migrate-mongoose와 npm 스크립트를 사용하여 마이그레이션을 생성하고 MongoDB 데이터베이스에 데이터를 시딩할 것입니다. ts-migrate-mongoose는 TypeScript 코드와 CommonJS 코드에서 마이그레이션 스크립트를 실행하는 것을 지원합니다.

ts-migrate-mongoose는 mongoose를 객체-데이터 매퍼로 사용하는 Node.js 프로젝트를 위한 마이그레이션 프레임워크입니다. 마이그레이션 스크립트를 작성하기 위한 템플릿을 제공합니다. 또한 스크립트를 프로그래밍 방식으로 및 CLI에서 실행하기 위한 구성을 제공합니다.

프로젝트 설정 방법

데이터베이스 마이그레이션을 위해 ts-migrate-mongoose를 사용하려면 다음이 필요합니다:

mongoose가 종속성으로 설치된 Node.js 프로젝트.
프로젝트에 연결된 MongoDB 데이터베이스.
MongoDB Compass(선택 사항 – 데이터베이스의 변경 사항을 확인할 수 있음).

쉽게 사용하기 위해 만들어진 시작 레포지토리인 ts-migrate-mongoose-starter-repo를 클론하여 환경 변수를 채우고 npm start 명령어를 실행하여 애플리케이션을 시작합니다.

http://localhost:8000에 브라우저나 Postman과 같은 API 클라이언트로 방문하면 서버가 예상대로 작동하는 것을 나타내는 “Hello there!” 텍스트가 반환됩니다.

프로젝트를 위해 ts-migrate-mongoose를 구성하는 방법

프로젝트를 위해 ts-migrate-mongoose를 구성하려면 다음 명령어로 ts-migrate-mongoose를 설치합니다:

npm install ts-migrate-mongoose

ts-migrate-mongoose는 JSON 파일, TypeScript 파일, .env 파일 또는 CLI를 통해 구성할 수 있습니다. 구성 내용에 데이터베이스 비밀번호가 포함될 수 있기 때문에 일반적으로 .env 파일을 사용하는 것이 좋습니다. .env 파일은 일반적으로 .gitignore 파일을 통해 숨겨져 있어 공개에 노출되지 않으므로 더 안전하게 사용할 수 있습니다. 이 프로젝트에서는 ts-migrate-mongoose 구성에 .env 파일을 사용할 것입니다.

다음 키와 그 값이 포함된 파일이어야 합니다:

MIGRATE_MONGO_URI – 몽고 데이터베이스의 URI. 데이터베이스 URL과 동일합니다.
MIGRATE_MONGO_COLLECTION – 마이그레이션을 저장해야 하는 컬렉션(또는 테이블)의 이름입니다. 기본값은 migrations이며 이 프로젝트에서 사용되는 값입니다. ts-migrate-mongoose는 마이그레이션을 MongoDB에 저장합니다.
MIGRATE_MIGRATIONS_PATH – 마이그레이션 스크립트를 저장하고 읽기 위한 폴더 경로입니다. 기본값은 ./migrations이며 이 프로젝트에서 사용되는 값입니다.

ts-migrate-mongoose를 사용하여 사용자 데이터를 시드하는 방법

프로젝트를 만들고 몽고 데이터베이스에 성공적으로 연결했습니다. 이 시점에서 데이터베이스에 사용자 데이터를 시드하려고 합니다. 다음을 수행해야 합니다:

사용자 컬렉션(또는 테이블)을 생성
데이터를 시드하는 마이그레이션 스크립트를 만들기 위해 ts-migrate-mongoose 사용
애플리케이션이 시작되기 전에 사용자 데이터를 시드하기 위해 ts-migrate-mongoose를 사용하여 마이그레이션 실행

1. Mongoose를 사용하여 사용자 Collection 생성

Mongoose 스키마를 사용하여 사용자 컬렉션(또는 테이블)을 생성할 수 있습니다. 사용자 문서(또는 레코드)에는 다음 필드(또는 열)가 있습니다: email, favouriteEmoji 및 yearOfBirth.

사용자 컬렉션을 위한 Mongoose 스키마를 만들려면 프로젝트의 루트에 다음 코드 스니펫을 포함하는 user.model.js 파일을 만듭니다:

const mongoose = require("mongoose");

const userSchema = new mongoose.Schema(
  {
    email: {
      type: String,
      lowercase: true,
      required: true,
    },
    favouriteEmoji: {
      type: String,
      required: true,
    },
    yearOfBirth: {
      type: Number,
      required: true,
    },
  },
  {
    timestamps: true,
  }
);

module.exports.UserModel = mongoose.model("User", userSchema);

2. ts-migrate-mongoose로 마이그레이션 스크립트 생성

ts-migrate-mongoose는 마이그레이션 스크립트를 생성하는 데 사용할 수 있는 CLI 명령을 제공합니다.

프로젝트의 루트 폴더에서 npx migrate create <name-of-script>를 실행하면 MIGRATE_MIGRATIONS_PATH 폴더(./migrations 우리의 경우)에 스크립트가 생성됩니다. <name-of-script>은 스크립트 파일이 생성될 때 가질 이름입니다.

사용자 데이터를 씨드하기 위한 마이그레이션 스크립트를 만들려면 다음을 실행하십시오:

npx migrate create seed-users

해당 명령은 ./migrations 폴더에 <timestamp>-seed-users.ts 형식의 이름을 가진 파일을 생성합니다. 파일에는 다음 코드 스니펫 내용이 포함됩니다:

// 여기서 모델을 가져옵니다

export async function up (): Promise<void> {
  // 마이그레이션을 작성합니다
}

export async function down (): Promise<void> {
  // 마이그레이션을 작성합니다
}

up 함수는 마이그레이션을 실행하는 데 사용됩니다. down 함수는 up 함수가 실행하는 작업을 필요한 경우 반전하는 데 사용됩니다. 우리의 경우에는 데이터베이스에 사용자를 씨드하려고 합니다. up 함수에는 데이터베이스에 사용자를 씨드하는 코드가 포함되고, down 함수에는 up 함수에서 생성된 사용자를 삭제하는 코드가 포함됩니다.

만일 MongoDB Compass로 데이터베이스를 검사한다면, 마이그레이션 컬렉션에는 다음과 같은 문서가 있을 것입니다:

{
  "_id": ObjectId("6744740465519c3bd9c1a7d1"),
  "name": "seed-users",
  "state": "down",
  "createdAt": 2024-11-25T12:56:36.316+00:00,
  "updatedAt": 2024-11-25T12:56:36.316+00:00,
  "__v": 0
}

마이그레이션 문서의 state 필드는 down으로 설정되어 있습니다. 성공적으로 실행되면, up으로 변경됩니다.

./migrations/<timestamp>-seed-users.ts의 코드를 아래 스니펫의 코드로 업데이트할 수 있습니다:

require("dotenv").config() // 환경 변수 로드
const db = require("../db.js")
const { UserModel } = require("../user.model.js");

const seedUsers = [
  { email: "[email protected]", favouriteEmoji: "🏃", yearOfBirth: 1997 },
  { email: "[email protected]", favouriteEmoji: "🍏", yearOfBirth: 1998 },
];

export async function up (): Promise<void> {
  await db.connect(process.env.MONGO_URI)
  await UserModel.create(seedUsers);}

export async function down (): Promise<void> {
  await db.connect(process.env.MONGO_URI)
  await UserModel.delete({
    email: {
      $in: seedUsers.map((u) => u.email),
    },
  });
}

3. 애플리케이션이 시작되기 전에 마이그레이션 실행하기

ts-migrate-mongoose는 마이그레이션 스크립트의 up 및 down 함수를 실행할 CLI 명령어를 제공합니다.

npx migrate up <name-of-script>로 특정 스크립트의 up 함수를 실행할 수 있습니다. npx migrate up으로 데이터베이스에서 state가 down인 모든 스크립트의 up 함수를 실행할 수 있습니다.

애플리케이션이 시작되기 전에 마이그레이션을 실행하려면 npm 스크립트를 사용합니다. pre 접두사가 있는 npm 스크립트는 pre 접두사가 없는 스크립트보다 먼저 실행됩니다. 예를 들어, dev 스크립트와 predev 스크립트가 있다면 dev 스크립트를 npm run dev로 실행할 때 predev 스크립트가 자동으로 dev 스크립트보다 먼저 실행됩니다.

이러한 npm 스크립트 기능을 활용하여 ts-migrate-mongoose 명령을 prestart 스크립트에 배치하여 마이그레이션이 start 스크립트보다 먼저 실행되도록 할 것입니다.

package.json 파일을 업데이트하여 ts-migrate-mongoose 명령을 실행하여 프로젝트의 마이그레이션 스크립트의 up 함수를 실행하는 prestart 스크립트를 추가하세요.

  "scripts": {
    "prestart": "npx migrate up",
    "start": "node index.js"
  },

이 설정을 통해 애플리케이션을 시작하기 위해 npm run start를 실행할 때, prestart 스크립트가 실행되어 ts-migrate-mongoose를 사용하여 마이그레이션을 실행하고 데이터베이스에 시드를 심기 위해 애플리케이션이 시작됩니다.

npm run start를 실행한 후 아래 스니펫과 유사한 내용이 있어야 합니다:

Synchronizing database with file system migrations...
MongoDB connection successful
up: 1732543529744-seed-users.ts 
All migrations finished successfully

> [email protected] start
> node index.js

MongoDB connection successful                      
Server listening on port 8000

현재 이 문서의 이 시점에서 코드베이스의 현재 상태를 확인하려면 저장소의 seed-users 브랜치를 확인하세요.

시드 데이터를 가져오기 위한 API 엔드포인트 구축 방법

데이터베이스에서 시드된 사용자 데이터를 가져오기 위한 API 엔드포인트를 구축할 수 있습니다. server.js 파일에서 아래 스니펫에 있는 코드로 코드를 업데이트하세요.

const { UserModel } = require("./user.model.js")

module.exports = async function (req, res) {
  const users = await UserModel.find({}) // 데이터베이스의 모든 사용자 가져오기

  res.writeHead(200, { "Content-Type": "application/json" });
  return res.end(JSON.stringify({ // 가져온 사용자 데이터의 JSON 표현 반환
    users: users.map((u) => ({
      email: u.email,
      favouriteEmoji: u.favouriteEmoji,
      yearOfBirth: u.yearOfBirth,
      createdAt: u.createdAt
    }))
  }, null, 2));
};

애플리케이션을 시작하고 Postman이나 브라우저를 사용하여 http://localhost:8000을 방문하면 아래와 유사한 JSON 응답을 받습니다:

{
  "users": [
    {
      "email": "[email protected]",
      "favouriteEmoji": "🏃",
      "yearOfBirth": 1997,
      "createdAt": "2024-11-25T14:18:55.416Z"
    },
    {
      "email": "[email protected]",
      "favouriteEmoji": "🍏",
      "yearOfBirth": 1998,
      "createdAt": "2024-11-25T14:18:55.416Z"
    }
  ]
}

애플리케이션을 다시 실행하면 이제 마이그레이션 스크립트가 더 이상 실행되지 않는 것을 알 수 있습니다. 왜냐하면 마이그레이션의 state가 성공적으로 실행된 후에는 이제 up이 될 것이기 때문입니다.

이 문서의 현재 코드 상태를 확인하려면 저장소의 fetch-users 브랜치를 확인하십시오.

결론

마이그레이션은 응용 프로그램을 구축할 때 유용하며 테스트를 위해 초기 데이터를 씨드하거나 관리자 사용자를 씨드하거나 열을 추가하거나 제거하여 데이터베이스 스키마를 업데이트하거나 한 번에 많은 레코드의 열 값을 업데이트해야 할 때 유용합니다.

ts-migrate-mongoose는 MongoDB와 함께 Mongoose를 사용하는 경우 Node.js 애플리케이션의 마이그레이션을 실행하기 위한 프레임워크를 제공하는 데 도움이 될 수 있습니다.

목차