서버 업그레이드를 위한 MongoDB Stable API

Stable API란 무엇이며 이를 사용해야 하나요?

MongoDB Stable API(이전에는 Versioned API로 표시됨)를 사용하면 원하는 대로 MongoDB 서버를 업그레이드할 수 있으며, MongoDB 버전 간의 동작 변경으로 인해 애플리케이션이 중단되지 않도록 할 수 있습니다.

MongoDB 5.0에는 MongoDB 서버 제품과 통신하는 애플리케이션을 위한 Stable API가 도입되었습니다. Stable API를 사용하면 애플리케이션이 실행되는 MongoDB API 버전을 지정할 수 있습니다.

Stable API는 애플리케이션에 장기적인 API 안정성을 제공하며, 더 잦은 출시와 자동 서버 업그레이드를 지원합니다. 이를 통해 애플리케이션은 이전 버전과의 호환성이 손상되는 변경에 관한 위험 없이 빠르게 출시된 기능을 활용할 수 있습니다.

The default behavior for your driver connection continues to function as expected, even if you do not explicitly specify an apiVersion.

Stable API는 애플리케이션이 데이터를 읽고 쓰고, 컬렉션과 인덱스를 만들고, 기타 일반적인 작업을 수행하는 데 사용하는 MongoDB 명령 하위 집합을 포함합니다.

이전 버전과의 호환성 보장

서버 업그레이드로 인해 애플리케이션에 중요한 동작 변경이 발생하지 않습니다. 이러한 보장은 새 서버가 지정된 API 버전을 지원하는 한 유지됩니다.

이전 버전과의 호환성을 보장하려면 애플리케이션이 반드시 다음과 같아야 합니다.

• API 버전 선언

• 지정된 API 버전에서 지원되는 명령 및 기능만 사용

• 지원되는 공식 드라이버 버전으로 배포

API 버전 선언

Stable API를 사용하려면 최신 드라이버로 업그레이드하고 애플리케이션의 MongoClient를 생성합니다.

"1" 이 현재 사용 가능한 유일한 API 버전입니다.

기본적으로 클라이언트는 엄격하지 않습니다. 엄격하지 않은 클라이언트를 사용하면 Stable API에 속하는지 여부에 관계없이 모든 명령을 실행할 수 있습니다.

클라이언트 API 버전 확인

serverStatus 명령을 사용하여 애플리케이션에 구성된 API 버전을 확인하세요. MongoDB 인스턴스에 연결된 각 애플리케이션에 대해 appname이 apiVersions 문서에 나타납니다.

자세한 내용은 metrics.apiVersions를 참조하세요.

db.runCommand( { serverStatus: 1 } ).metrics.apiVersions

엄격한 클라이언트 생성

A strict client rejects all commands outside of the Stable API. Attempts to use commands outside of the Stable API receive the APIVersionError response.

엄격한 클라이언트는 쿼리 계획 및 실행 중에 지원되지 않는 인덱스 유형도 무시합니다.

샘플 코드를 사용하여 엄격한 클라이언트를 생성합니다.

Stable API 명령으로 마이그레이션

애플리케이션을 Stable API를 사용하도록 마이그레이션하려면 다음을 수행해야 합니다.

1. 새로운 MongoClient 옵션으로 애플리케이션의 테스트 모음을 실행하세요.

2. Stable API 외부에서 사용 중인 명령과 기능을 확인합니다.

3. Stable API의 대체 명령 및 기능으로 마이그레이션하세요.

애플리케이션이 Stable API에 정의된 명령과 기능만 사용하는 경우, 새로운 MongoClient 옵션으로 재배포할 수 있으며, 향후 서버 업그레이드가 애플리케이션에 부정적인 영향을 미치지 않을 것이라고 확신할 수 있습니다.

Stable API 외부에서 명령어 및 기능을 사용하는 방법

Stable API 외부의 명령과 기능을 사용하려면 엄격하지 않은 클라이언트를 사용하여 배포서버에 연결할 수 있습니다. 기본적으로 클라이언트는 엄격하지 않습니다.

엄격하지 않은 클라이언트를 생성하려면 다음 샘플 코드를 사용하세요.

이 엄격하지 않은 클라이언트를 사용하면 Stable API 외부에서 명령을 실행할 수 있습니다. 예를 들어, 이 엄격하지 않은 클라이언트를 사용하면 createUser 명령을 실행할 수 있습니다.

Stable API 명령

Stable API V1에 포함된 데이터베이스 명령은 사용 중인 MongoDB 버전에 따라 다릅니다. Stable API에 포함된 데이터베이스 명령과 해당 명령이 도입된 MongoDB 버전을 확인하려면 Stable API 변경 로그를 참조하세요.

매개변수

애플리케이션의 MongoDB 드라이버 연결 코드에서 Stable API에 대해 다음과 같은 선택적 매개 변수를 지정할 수 있습니다. 자세한 내용은 애플리케이션에서 사용하는 드라이버의 MongoDB 드라이버 설명서를 참조하세요.

행동

Stable API 오류 응답

이 표에는 문제가 있는 Stable API 요청에 대한 오류 응답이 제시되어 있습니다.