MongoDB SQL Schema Builder CLIは、SQLインターフェースのEnterprise Advanced (EA)自己管理型配置用のスキーママネジメントツールです。クラスターに対してCLIをダウンロードして実行し、JSON schemaを生成します。SQLインターフェースはこのスキーマを使用して、SQLクエリをMongoDB操作に翻訳します。
このページでは、ツールの概要、実行するために必要なもの、呼び出し方法、および受け入れるフラグについて説明します。スキーママネジメントの概要とその他のサポートされている配置タイプについては、スキーママネジメントを参照してください。
ユースケース
EA 自己管理型配置で SQL インターフェースを実行し、コレクションのスキーマを生成または更新する必要がある場合は、MongoDB SQL Schema Builder CLI を使用します。CLI は、この配置タイプでサポートされているスキーママネジメント パスです。
CLIはデータをサンプルしません。その代わり、処理する各コレクションのすべてのドキュメントを分析するため、生成されるスキーマはコレクション内の正確なデータを正確に反映します。ごく一部のドキュメントにのみ表示されるフィールドでさえもスキーマに含まれます。
スキーマの再生成は常にユーザーが開始します。CLI は、スキーマを自動的にまたは予定に基づいて更新しません。基礎のデータの形状が変更されるたびにスキーマを再生成して、SQL インターフェースが提供されたスキーマ情報で操作するようにする必要があります。
前提条件
MongoDB SQL スキーマ ビルダ 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 スキーマ ビルダ CLI をクラスターに対してコマンドラインから実行し、スキーマを生成または更新します。バイナリの名前は mongodb-schema-manager です。
次の例では、sales データベース内のすべてのコレクションを分析し、トレース ログを logs ディレクトリに書き込みます。
mongodb-schema-manager \ --uri "mongodb://<host>:<port>" \ --ns-include "sales.*" \ --logpath ./logs \ --verbosity info
実行が完了すると、CLI はスキーマを作成または変更したデータベースと名前空間を出力します。ある名前空間のポリモルフィズムのレベルが高すぎて意味のある使用ができない場合、不安定とみなされます。CLI はこれらの名前空間をリストします。詳細については、「不安定なスキーマ」を参照してください。
TLS を使用した接続
MongoDB SQL Schema Builder 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 コレクションに名前空間ごとに 1 つのスキーマ ドキュメントを書き込みます。
重要
__sql_schemasコレクションを SQL インターフェースの予約名前空間として扱います。手動で修正しないでください。CLI を使用して、含まれるスキーマを作成および更新します。
保存されたスキーマを確認する
CLI が生成したスキーマを検討するには、検査するデータベースの __sql_schemas コレクションに対して集計パイプラインを実行します。各ドキュメントには、次のメタデータが報告されます。
lastUpdated: 最新のスキーマ書き込み (write)の日付と時刻。unstable: スキーマが不安定であるかどうか。詳細については、「不安定なスキーマ」を参照してください。
データベース内のすべてのスキーマのステータスをスキーマの全文を出力せずに表示するには、mongosh で次のパイプラインを実行します。
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 は名前が 2 つのアンダースコア (__) で始まるデータベースまたはコレクションを暗黙的に除外します。これには、__sql_schemas コレクション自体も含まれます。これらの名前空間を含めるには、--ns-include を使用して明示的に指定する必要があります。例として、--ns-include "*.__*" には、__ で始まらないデータベース内の __ で始まるコレクションが含まれます。
CLI は、ビュー パイプラインと、パイプラインが参照するソース コレクションのスキーマからビューのスキーマを導出します。通常の状況では、CLI はビューをサンプルしません。ビューの導出されたスキーマが正確であることを確保するには、まずソース コレクションの最新のスキーマを生成します。
ソースコレクションにスキーマが存在しない場合、または CLI が使用可能なソースコレクションスキーマからスキーマを引き出せない場合、CLI はビューの実行とその出力ドキュメントのサンプリングにフォールバックします。
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 スキーマ マネージャー 概要 (PDF): MongoDB SQL スキーマ Builder の完全な技術リファレンス。