MongoDB SQL 模式构建器 CLI

用例

在 EA 自管理部署中运行 SQL 接口并需要为集合生成或更新模式时，请使用 MongoDB SQL 模式构建者 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 会以更新或插入（upsert）的方式写入每个模式，因此即使是第一次运行，也需要 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 模式构建者 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集合。

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 接受以下标志。您必须提供 --uri 或 --file，以便 CLI 连接到您的集群。

-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 写入日志文件的目录。日志文件命名为 mongodb-schema-manager.log.{date}。如果您忽略此标志，CLI 将不写入日志文件。

-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 的整数。默认：物理内核数的两倍。

不稳定模式

当集合的文档形状差异很大时（例如，使用字段名称作为映射键的集合），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模式生成器的完整技术参考。