변경 스트림

가용성

변경 스트림은 복제본 세트 및 샤드 클러스터에 사용할 수 있습니다:

• 스토리지 엔진

  복제본 세트와 샤드 클러스터는 WiredTiger 스토리지 엔진을 사용해야 합니다. Change Stream은 MongoDB의 미사용 데이터 암호화 기능을 사용하는 배포에서도 사용할 수 있습니다.

• 복제본 세트 프로토콜 버전.

  복제본 세트와 샤드 클러스터는 복제본 세트 프로토콜 버전 1(pv1)를 사용해야 합니다.

• 읽기 고려 '대다수' 활성화

  MongoDB 4.2부터는 "majority" 읽기 고려 지원 여부와 관계없이 변경 스트림을 사용할 수 있습니다. 읽기 고려 majority 지원은 활성화(기본값)하거나 비활성화하여 변경 스트림을 사용할 수 있습니다.

  MongoDB 4.0 이하 버전에서는 "majority" 읽기 고려 지원을 (기본값으로) 사용하도록 설정한 경우에만 변경 스트림을 사용할 수 있습니다.

연결

변경 스트림에 대한 연결은 +srv 연결 옵션과 함께 DNS 시드 목록을 사용하거나 연결 문자열에 서버를 개별적으로 나열하여 사용할 수 있습니다.

드라이버가 변경 스트림에 대한 연결을 잃거나 연결이 다운되면 클러스터 내 읽기 설정이 일치하는 다른 노드를 통해 변경 스트림에 대한 연결을 다시 설정하려고 시도합니다. 드라이버가 올바른 읽기 설정을 가진 노드를 찾을 수 없으면 예외가 발생합니다.

자세한 내용은 연결 문자열 URI 형식을 참조하세요.

컬렉션, 데이터베이스 또는 배포 보기

다음에 대한 change stream을 열 수 있습니다.

Change Stream 성능 고려 사항

데이터베이스에 대해 열려 있는 변경 스트림의 양이 연결 풀 크기를 초과할 경우 알림 지연이 발생할 수 있습니다. 각 변경 스트림은 다음 이벤트를 기다리는 시간 동안 변경 스트림에 대한 연결과 GetMore 작업을 사용합니다. 지연 시간 문제를 방지하려면 풀 크기가 열려 있는 변경 스트림 수보다 큰지 확인해야 합니다. 자세한 내용은 MaxPoolSize 설정을 참조하세요.

Change Stream 열기

변경 스트림을 열려면 다음을 수행합니다.

• 복제본 세트의 경우 데이터 보유 멤버 중 하나에서 변경 스트림 열기 작업을 실행할 수 있습니다.

• 샤드 클러스터의 경우 mongos에서 변경 스트림 열기 작업을 실행해야 합니다.

다음 예시는 컬렉션에 대한 변경 스트림을 열고 커서를 반복하여 변경 스트림 문서를 조회합니다. [1]

➤ 오른쪽 상단의 언어 선택 드롭다운 메뉴를 사용하여 이 페이지에 있는 예제의 언어를 설정하세요.

커서에서 데이터 변경 이벤트를 조회하려면 변경 스트림 커서를 반복합니다. 변경 스트림 이벤트에 대한 자세한 내용은 Change Events를 참조하세요.

변경 스트림 커서 는 다음 중 하나가 발생할 때까지 열린 상태로 유지됩니다.

• 커서가 명시적으로 닫힙니다.

• 무효화 이벤트가 발생합니다. 예를 들어 컬렉션 삭제 또는 이름 바꾸기가 있습니다.

• MongoDB 배포에 대한 연결이 닫히거나 시간 초과됩니다. 자세한 내용은 Cursor Behaviors를 참조하십시오.

• 배포가 분할된 클러스터인 경우 분할 제거로 인해 열린 변경 스트림 커서가 닫힐 수 있으며 닫힌 변경 스트림 커서가 완전히 재개되지 않을 수 있습니다.

Change Stream 출력 수정

➤ 오른쪽 상단의 언어 선택 드롭다운 메뉴를 사용하여 이 페이지에 있는 예제의 언어를 설정하세요.

업데이트 작업에 대한 전체 문서 조회

기본적으로 변경 스트림은 업데이트 작업 중에 필드의 델타만 반환합니다. 그러나 업데이트된 문서의 가장 최근 과반수 커밋 버전을 반환하도록 변경 스트림을 구성할 수 있습니다.

➤ 오른쪽 상단의 언어 선택 드롭다운 메뉴를 사용하여 이 페이지에 있는 예제의 언어를 설정하세요.

변경 스트림 다시 시작

변경 스트림은 커서를 열 때 재개 토큰을 resumeAfter 또는 startAfter로 지정하여 재개할 수 있습니다.

snippet install resumetoken
decodeResumeToken('<RESUME TOKEN>')

npx mongodb-resumetoken-decoder <RESUME TOKEN>

{
   "_id": {
      "_data": "82635019A0000000012B042C0100296E5A1004AB1154ACACD849A48C61756D70D3B21F463C6F7065726174696F6E54797065003C696E736572740046646F63756D656E744B65790046645F69640064635019A078BE67426D7CF4D2000004"
    },
    "operationType": "insert",
    "clusterTime": Timestamp({ "t": 1666193824, "i": 1 }),
    "collectionUUID": new UUID("ab1154ac-acd8-49a4-8c61-756d70d3b21f"),
    "wallTime": ISODate("2022-10-19T15:37:04.604Z"),
    "fullDocument": {
       "_id": ObjectId("635019a078be67426d7cf4d2"'),
       "name": "Giovanni Verga"
    },
    "ns": {
       "db": "test",
       "coll": "names"
    },
    "documentKey": {
       "_id": ObjectId("635019a078be67426d7cf4d2")
    }
}

{
   "cursor": {
      "firstBatch": [],
      "postBatchResumeToken": {
         "_data": "8263515EAC000000022B0429296E1404"
      },
      "id": Long("4309380460777152828"),
      "ns": "test.names"
   },
   "ok": 1,
   "$clusterTime": {
      "clusterTime": Timestamp({ "t": 1666277036, "i": 1 }),
      "signature": {
         "hash": Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
         "keyId": Long("0")
      }
   },
   "operationTime": Timestamp({ "t": 1666277036, "i": 1 })
}

{
   "cursor": {
      "nextBatch": [],
      "postBatchResumeToken": {
         "_data": "8263515979000000022B0429296E1404"
      },
      "id": Long("7049907285270685005"),
      "ns": "test.names"
   },
   "ok": 1,
   "$clusterTime": {
      "clusterTime": Timestamp( { "t": 1666275705, "i": 1 } ),
      "signature": {
         "hash": Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
         "keyId": Long("0")
      }
   },
   "operationTime": Timestamp({ "t": 1666275705, "i": 1 })
}

사용 사례

변경 스트림은 데이터 변경이 지속되면 다운스트림 시스템에 알려주므로 비즈니스 시스템에 의존하는 아키텍처에 도움이 될 수 있습니다. 예를 들어, 변경 스트림은 개발자가 추출, 변환 및 로드(ETL) 서비스, 플랫폼 간 동기화, 협업 기능 및 알림 서비스를 구현할 때 시간을 절약할 수 있습니다.

액세스 제어

인증 및 권한 부여를 집행하는 배포의 경우

• 특정 컬렉션에 대한 변경 스트림을 열려면 애플리케이션에 해당 컬렉션에 대해 changeStream 및 find 조치를 부여할 수 있는 권한이 있어야 합니다.

  { resource: { db: <dbname>, collection: <collection> }, actions: [ "find", "changeStream" ] }

• 단일 데이터베이스에서 변경 스트림을 열려면 애플리케이션에 데이터베이스의 모든 비system 컬렉션에 대해 changeStream및 find작업을 수행할 수 있는 권한이 있어야 합니다.

  { resource: { db: <dbname>, collection: "" }, actions: [ "find", "changeStream" ] }

• 전체 배포에서 change stream을 열려면 애플리케이션에 배포의 모든 데이터베이스에 대해system 이 아닌 모든 collection에 대해 changeStream 및 find 조치를 허용하는 권한이 있어야 합니다.

  { resource: { db: "", collection: "" }, actions: [ "find", "changeStream" ] }

이벤트 알림

변경 스트림은 복제본 집합에 있는 대부분의 데이터 보유 멤버에 지속된 데이터 변경 내용에 대해서만 알립니다. 이렇게 하면 오류 시나리오에서 지속적인 대다수 커밋 변경 사항에 대해서만 알림이 트리거됩니다.

예를 들어 프라이머리에 대해 열린 change stream 커서가 있는 3-노드 복제본 세트가 있다고 가정해 봅시다. 클라이언트가 삽입 연산을 실행하는 경우 change stream은 해당 삽입이 대부분의 데이터 보유 노드에 지속된 경우에만 애플리케이션에 데이터 변경을 알립니다.

작업이 트랜잭션과 연결된 경우, 변경 이벤트 문서에 txnNumber 및 lsid가 포함됩니다.

데이터 정렬

변경 스트림은 명시적인 데이터 정렬이 제공되지 않는 한 simple 이진 비교를 사용합니다.

스트림 및 고아 문서 변경

MongoDB 5.3부터는 범위 마이그레이션 중에 고아 문서에 대한 업데이트에 대한 변경 스트림 이벤트가 생성되지 않습니다.

전후 이미지를 포함하는 문서의 Change Streams

MongoDB 6.0부터는 변경 스트림 이벤트를 사용하여 문서의 변경 전후 버전(문서의 전후 이미지)을 출력할 수 있습니다.

• 사전 이미지는 문서가 교체, 업데이트 또는 삭제되기 전의 문서입니다. 삽입된 문서에는 사전 이미지가 없습니다.

• 사후 이미지는 문서가 삽입, 교체, 업데이트된 후의 문서입니다. 삭제된 문서에 대한 사후 이미지가 없습니다.

• db.createCollection(), create 또는 collMod을(를) 사용하는 컬렉션에 대해 changeStreamPreAndPostImages을(를) 활성화하세요.

이미지가 다음과 같은 경우 change stream 이벤트에 사전 및 사후 이미지를 사용할 수 없습니다.

• 문서 업데이트 또는 삭제 작업 시 collection에서 활성화되지 않았습니다.

• expireAfterSeconds에서 전후 이미지 보존 시간 설정 이후에 제거됩니다.

  • 다음 예시에서는 전체 클러스터에서 expireAfterSeconds를 100초로 설정합니다.

    use admin
    db.runCommand( {
       setClusterParameter:
          { changeStreamOptions: {
             preAndPostImages: { expireAfterSeconds: 100 }
          } }
    } )

  • 다음 예제에서는 expireAfterSeconds 등 현재 changeStreamOptions 설정을 반환합니다.

    db.adminCommand( { getClusterParameter: "changeStreamOptions" } )

  • expireAfterSeconds를 off로 설정하면 기본 보존 정책이 사용되며, 해당 change stream 이벤트가 oplog에서 제거될 때까지 사전 및 사후 이미지가 보존됩니다.

  • change stream 이벤트가 oplog에서 제거되면 expireAfterSeconds 사전 및 사후 이미지 보존 시간에 관계없이 해당 사전 및 사후 이미지도 삭제됩니다.

추가 고려 사항

• 전후 이미지를 활성화하면 저장 공간이 소모되고 처리 시간이 늘어납니다. 필요한 경우에만 전후 이미지를 활성화하세요.

• 변경 스트림 이벤트 크기를 16메가바이트 미만으로 제한합니다. 이벤트 크기를 제한하려면 다음을 수행하면 됩니다.

  • 문서 크기를 8메가바이트로 제한합니다. updateDescription과 같은 다른 change stream 이벤트 필드가 크지 않은 경우 change stream 출력에서 사전 및 사후 이미지를 동시에 요청할 수 있습니다.

  • updateDescription과 같은 다른 change stream 이벤트 필드가 크지 않은 경우 최대 16메가바이트 문서에 대해 change stream 출력에서 사후 이미지만 요청합니다.

  • 다음과 같은 경우 최대 16메가바이트의 문서에 대해 change stream 출력에서 사전 이미지만 요청합니다.

    • 문서 업데이트가 문서 구조나 내용의 작은 부분에만 영향을 미칩니다. 그리고

    • replace 변경 이벤트를 발생시키지 않습니다. replace 이벤트에는 항상 후이미지가 포함됩니다.

• 사전 이미지를 요청하려면 db.collection.watch()에서 fullDocumentBeforeChange를 required 또는 whenAvailable로 설정합니다. 사후 이미지를 요청하려면 동일한 방법으로 fullDocument를 설정합니다.

• 사전 이미지가 config.system.preimages 컬렉션에 기록됩니다.

  • config.system.preimages collection은 커질 수 있습니다. collection 크기를 제한하려면 앞서 표시된 대로 사전 이미지에 대해 expireAfterSeconds 시간을 설정할 수 있습니다.

  • 사전 이미지는 백그라운드 프로세스가 비동기적으로 제거합니다.

변경 스트림 출력에 대한 전체 예시는 전후 이미지를 포함하는 문서의 Change Streams를 참조하세요.