MongoDB SQL 模式构建器 CLI

先决条件

在运行 MongoDB SQL 模式构建器 CLI 之前，请确保满足以下要求：

• Your deployment is either a MongoDB Enterprise cluster (Enterprise Advanced (EA) self-managed) or a dedicated cluster (M10 and above) running MongoDB 6.0 or later (Atlas). The CLI does not support MongoDB Community clusters, Free clusters, Flex clusters, or M2 and M5 shared Atlas clusters.

• 在专用集群上，您需要为每个要使用 SQL 进行查询的集群启用 SQL Interface。欲了解更多信息，请参阅 SQL 界面服务器设置。

• MongoDB SQL 模式 构建者 CLI 与您的操作系统和架构兼容：

  • Windows x86_64。

  • Linux x86_64 和 arm64：OpenSSL 1.0 和 glibc 2.26 或更高版本，OpenSSL 1.1 和 glibc 2.28 或更高版本，或 OpenSSL 3.0 和 glibc 2.28 或更高版本。MongoDB 建议使用 OpenSSL 3.0 或更高版本以实现安全连接。

• 您可以使用连接字符串从运行 CLI 的机器连接到集群。

• CLI 身份验证的数据库用户至少具有：

  • 对于要处理的每个数据库，具有 read 权限。此权限允许 CLI 列举和分析集合。

  • 在您处理的每个数据库中的 __sql_schemas 集合上的 find、insert 和 update 权限，或数据库上的 readWrite 角色。CLI 会以更新或插入（upsert）的方式写入每个模式，因此即使是第一次运行，也需要 update 权限。

  • 在专用集群上，read 数据库上的 __mdb_internal_sqlinterface 权限。

您可以使用 --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集合。

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 接受以下标志。您必须提供 --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接口

• MongoDB SQL接口概述

• MongoDB 模式经理概述 (PDF)：MongoDB SQL 模式构建者的完整技术参考。