MongoDB SQLスキーマ ビルダ CLI

前提条件

MongoDB SQL スキーマ ビルダ CLI を実行する前に、次の要件を満たしていることを確認してください。

• 配置はMongoDB Enterpriseクラスター（ Enterprise Advanced（EA）が自己管理型）または専用クラスター（ M10以上）でMongoDB6.0 以降（Atlas）を実行中専有クラスター（ 以上） CLI は、 MongoDB Community クラスター、無料クラスター、Flex クラスター、または とM2 M5共有 Atlas クラスターをサポートしていません。

• 専有クラスターでは、 SQLでクエリを実行するクラスターごとにSQLインターフェイスが有効になっています。詳細については、 「 SQLインターフェイスサーバーの設定 」を参照してください。

• MongoDB SQL schema Builder CLI は、ご使用のオペレーティング システムとアーキテクチャと互換性があります。

  • Windows x86_64。

  • Linux x86_64 と arm64: OpenSSL 1.0 と glibc 2.26 以降、glibc 2.28 以降を使用する OpenSSL 1.1、または OpenSSL 3.0 と glibc 2.28以降のバージョンMongoDB、安全な接続のために OpenSSL 3.0 以降を推奨しています。

• 接続文字列を使用して、 CLI を実行するマシンからクラスターに接続できます。

• CLI が認証するデータベースユーザーは、最低で以下の権限を持っています。

  • 処理する各データベースの read 権限。この権限により、CLI はコレクションを列挙して分析できます。

  • 処理する各データベースの __sql_schemas コレクションに対する find、insert、update の権限、またはデータベースに対する readWrite ロール。CLI はアップサートで各スキーマを書き込み (write)を行うため、初回の実行でも update 権限が必要です。

  • 専有クラスターでは、__mdb_internal_sqlinterfaceデータベースに対する read特権。

--username および --password フラグを使用して認証情報を提供するか、接続文字列に含めることができます。認証情報を提供しない場合、CLI は認証なしで接続しようとし、警告をログします。

CLI を実行します。

MongoDB SQL スキーマ ビルダ CLI をクラスターに対してコマンドラインから実行し、スキーマを生成または更新します。バイナリの名前は mongodb-schema-manager です。

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

スキーマの保存方法

CLI は、処理する各データベースの __sql_schemas コレクションに名前空間ごとに 1 つのスキーマ ドキュメントを書き込みます。

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

db.getCollection("__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> です。mydb.* のような Glob 構文がサポートされています。複数のパスワードなしを指定するには、フラグを繰り返します。このフラグを省略すると、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 倍。

Unstable スキーマ

コレクションのドキュメントの形状が大きく異なる場合、たとえばフィールド名をマップ キーとして使用するコレクションの場合、CLI は演縁されたスキーマを不安定としてマークします。不安定なスキーマでは、スキーマ ドキュメントの unstable が true に設定され、キャプチャされたフィールドの数が制限され、additionalProperties が true に設定されます。不安定なスキーマでは、名前空間内のデータが完全に表示されない場合があります。

実行によって 1 つ以上の不安定なスキーマが生成されると、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 Interface のインストール

• MongoDB SQL Interface の概要

• MongoDB スキーマ マネージャー 概要 (PDF): MongoDB SQL スキーマ Builder の完全な技術リファレンス。