MongoDB SQL 스키마 빌더 CLI

사용 사례

EA 자체 관리형 배포에서 SQL 인터페이스를 실행하고 컬렉션의 스키마를 생성하거나 업데이트해야 할 경우 MongoDB SQL 스키마 빌더 CLI를 사용합니다. CLI는 이 배포 유형에 대한 지원되는 스키마 관리 경로입니다.

CLI는 데이터를 샘플링하지 않습니다. 대신 프로세스하는 각 컬렉션의 모든 문서를 분석하여 생성된 스키마가 컬렉션의 정확한 데이터를 정확히 반영합니다. 문서의 작은 부분에만 나타나는 필드도 스키마에 포함됩니다.

스키마 재생성은 항상 사용자가 시작합니다. CLI는 스키마를 자동으로 또는 예정에 따라 새로 고침하지 않습니다. SQL 인터페이스가 제공된 스키마 정보에 따라 작업하도록 기본 데이터의 형태가 변경될 때마다 스키마를 재생성해야 합니다.

전제 조건

MongoDB SQL 스키마 Builder CLI를 실행하기 전에 다음 요건을 충족하는지 확인합니다.

• 배포서버는 MongoDB Enterprise 클러스터입니다. CLI는 MongoDB Community 클러스터를 지원하지 않습니다.

• CLI를 실행하는 마신에서 연결 문자열(--uri)이나 설정 파일(--file)로 클러스터에 연결할 수 있습니다.

• CLI가 인증하는 데이터베이스 사용자는 최소한 한도로 다음을 가집니다.

  • 처리하려는 각 데이터베이스에 대한 read 권한. 이 권한을 통해 CLI는 컬렉션을 열거하고 분석할 수 있습니다.

  • 프로세스 각 데이터베이스 의 __sql_schemas 컬렉션 에 대한 find, insert 및 update 권한 또는 데이터베이스 에서 readWrite 역할 . CLI 각 스키마 업서트 와 함께 쓰기 (write)하므로 처음 실행 경우에도 update 권한 필요합니다.

--username 및 --password 플래그를 사용하여 자격 증명을 제공하거나 연결 문자열에 포함시킬 수 있습니다. 자격 증명을 제공하지 않으면 CLI는 인증 없이 연결하려고 시도하고 경고를 로그합니다.

CLI 호출

MongoDB SQL Schema Builder CLI를 클러스터에 대하여 명령줄에서 실행하여 스키마를 생성하거나 업데이트할 수 있습니다. 바이너리 이름은 mongodb-schema-manager입니다.

다음 예시는 sales 데이터베이스의 모든 컬렉션을 분석하고 트레이스 로그를 logs 디렉토리에 쓰기 (write)를 위한 예시입니다.

mongodb-schema-manager \
   --uri "mongodb://<host>:<port>" \
   --ns-include "sales.*" \
   --logpath ./logs \
   --verbosity info

실행이 완료되면 CLI는 스키마를 생성하거나 수정한 데이터베이스와 네임스페이스를 인쇄합니다. 어떤 네임스페이스의 다형성 수준이 의미 있는 사용에 너무 높으면 불안정적인 것으로 간주됩니다. CLI는 해당 네임스페이스를 나열합니다. 자세한 내용은 불안정적인 스키마를 참조하세요.

TLS로 연결

MongoDB SQL 스키마 빌더 CLI TLS에 대한 명령줄 플래그를 제공하지 않습니다. TLS 지원 클러스터 에 연결하려면 --uri에 전달하는 연결 문자열 에 TLS 옵션을 지정합니다.

파일 경로에 / 문자를 포함하여 예약된 문자가 포함된 옵션 값을 퍼센트 인코딩합니다. 예시 를 들어 /etc/certs/ca.pem 경로는 %2Fetc%2Fcerts%2Fca.pem 가 됩니다.

다음 예시 TLS를 활성화하고 인증 기관 파일 지정합니다.

mongodb-schema-manager \
   --uri "mongodb://<host>:<port>/?tls=true&tlsCAFile=%2Fetc%2Fcerts%2Fca.pem" \
   --ns-include "sales.*"

배포서버 에 클라이언트 인증서가 필요한 경우 도 설정하다 tlsCertificateKeyFile,tlsCertificateKeyFilePassword 키 파일 암호화됨 경우 도 설정합니다. TLS 연결 문자열 옵션의 전체 목록은 TLS 옵션을 참조하세요.

스키마 저장 방식

CLI는 처리하는 각 데이터베이스의 __sql_schemas 컬렉션에 네임스페이스당 하나의 스키마 문서를 쓰기 (write)를 합니다.

db.__sql_schemas.aggregate([
   { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1 } },
   { $sort: { namespace: 1 } }
])

db.__sql_schemas.aggregate([
   { $match: { _id: "<collection-name>" } },
   { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1, schema: 1 } }
])

CLI 플래그 참조

MongoDB SQL 스키마 빌더 CLI는 다음 플래그를 허용합니다. CLI가 클러스터에 연결할 수 있도록 --uri 또는 --file 을 제공해야 합니다.

-f, --file <CONFIG_FILE>

설정 파일의 경로. 명령줄 인수는 설정 파일의 값보다 우선합니다.

--uri <URI>

클러스터의 연결 문자열입니다.

-u, --username <USERNAME>

인증을 위한 사용자 이름입니다. 연결 문자열에서 사용자 이름을 지정할 수도 있습니다.

-p, --password <PASSWORD>

인증 위한 비밀번호입니다. 연결 문자열 에 비밀번호를 지정할 수도 있습니다.

--ns-include <NS_INCLUDE>

포함할 데이터베이스 및 컬렉션의 형식은 <database_pattern>.<collection_pattern>입니다. Glob 구문은 mydb.* 등 지원됩니다. 플래그를 반복하여 여러 패턴을 지정합니다. 이 플래그를 생략하면 CLI에서 모든 데이터베이스와 컬렉션을 포함합니다. __ 로 시작하는 네임스페이스는 명시적으로 지정하지 않으면 임시적으로 제외됩니다.

--ns-exclude <NS_EXCLUDE>

--ns-include과 동일한 형식으로 제외할 데이터베이스 및 컬렉션입니다. 플래그를 반복하여 여러 패턴을 지정합니다. 이 플래그는 --ns-include보다 우선순위가 높습니다.

--quiet

출력을 줄여 조용 모드를 활성화합니다. 기본값: false.

-o, --logpath <LOGPATH>

CLI가 로그 파일을 쓰기 (write)하는 디렉토리입니다. 로그 파일 이름은 mongodb-schema-manager.log.{date}입니다. 이 플래그를 생략하면 CLI는 로그 파일을 쓰기 (write)를 하지 않습니다.

-v, --verbosity <VERBOSITY>

로그 파일에서 캡처할 로그 수준. --logpath이(가) 필요합니다. trace, debug, info, warn 또는 error를 허용합니다. 기본값: warn.

-a, --action <SCHEMA_ACTION>

스키마에서 수행할 조치입니다. 기본값: merge. 다음 값을 허용합니다.

• merge: 새 스키마를 기존 스키마와 병합합니다. 스키마가 존재하지 않으면 이 조치는 스키마를 생성합니다. 이 조치는 불안정적인 스키마를 업데이트하지 않습니다.

• overwrite: 기존 스키마를 무시하고 재정의합니다. 스키마가 존재하지 않으면 이 조치는 스키마를 생성합니다. 이 조치를 사용하여 불안정적인 스키마를 업데이트합니다.

• clear: 기존 스키마 문서에서 schema 필드를 제거합니다. 스키마가 없는 경우, 이 조치는 메타데이터만 캡처합니다.

--dry-run

스키마를 분석하거나 데이터베이스에 기록하지 않고 가상 실행을 수행합니다. 이 플래그를 사용하여 --ns-include 및 --ns-exclude 패턴을 테스트합니다. 기본값: false.

--resolver <RESOLVER>

DNS 해결이 실패하거나 느린 경우 사용할 DNS 해결사. cloudflare, google 또는 quad9를 허용합니다.

-j, --jobs <JOBS>

동시 스키마 처리 작업의 최대 개수입니다. 0보다 큰 정수여야 합니다. 기본값: 물리적 코어 수의 2배

불안정한 스키마

컬렉션의 문서가 필드 이름을 매핑 키로 사용하는 컬렉션과 같이 형태가 매우 다양한 경우 CLI는 파생된 스키마를 불안정적인 것으로 표시합니다. 불안정적인 스키마는 스키마 문서에서 unstable 을 true 로 설정하고, 캡처되는 필드 수를 제한하며 additionalProperties 를 true으로 설정합니다. 불안정적인 스키마는 네임스페이스의 데이터를 완전히 나타내지 못할 수 있습니다.

실행이 하나 이상의 불안정적인 스키마를 생성하면 CLI가 영향을 받은 네임스페이스를 인쇄합니다.

The following namespaces have unstable schemas. They may not
fully represent the data in the namespace.
Unstable schemas are not updated by the schema-manager by
default. To update them, use the 'overwrite' action.

기본값 merge 조치는 불안정적인 스키마를 업데이트하지 않습니다. 불안정적인 스키마를 업데이트하려면 --action overwrite로 CLI를 실행합니다.

스키마를 재생성할 시기

기본 데이터의 형태가 변경되면(예: 필드 추가, 필드 제거 또는 기존 필드의 데이터 유형 변경) 스키마를 재생성합니다. CLI는 데이터 형태 변경을 자체적으로 감지하지 않으므로 재생성하는 것은 항상 사용자가 시작합니다. 오래된 스키마는 SQL 인터페이스가 컬렉션을 잘못된 테이블 및 컬럼에 매핑하도록 할 수 있습니다.

자세히 알아보기

• 스키마 관리
• MongoDB SQL 인터페이스 설치
• SQL 인터페이스를 사용한 쿼리
• MongoDB SQL 인터페이스 개요

• MongoDB 스키마 관리자 개요 (PDF): MongoDB SQL 스키마 빌더에 대한 완전한 기술 참조 자료입니다.