/ /

`mongosqld`

说明

注意

MongoDB Connector for BI 和相关实用程序与所有当前支持的 MongoDB 服务器版本兼容。

mongosqld accepts incoming requests from a SQL client and proxies those requests to a mongod or mongos instance.

使用

2.3 版新增功能：

You can start mongosqld either with a schema file in .drdl format using the --schema option or by sampling data from a MongoDB instance to create the schema.

You can specify which namespace or namespaces to sample data from with the --sampleNamespaces option. If you don't specify any namespaces or a schema file, mongosqld samples data from all databases in the target MongoDB instance except the admin and local databases.

You can specify a database in which to store schema information with the --schemaSource option. Otherwise, mongosqld holds the schema in memory.

使用模式文件启动 `mongosqld`

Use the --schema option to specify a schema file when starting mongosqld.

mongosqld --schema /path/to/schema-file.drdl

使用 mongodrdl 从 MongoDB 实例中创建模式文件。

使用模式数据库启动 `mongosqld`

Use the --schemaSource option to specify a database to store schema information.

mongosqld --schemaSource sampleDb

`mongosqld`使用指定的命名空间启动

Use the --sampleNamespaces option to specify databases and collections for mongosqld to sample data from to create the schema.

mongosqld --sampleNamespaces contacts.addresses

请参阅下面更多的使用示例。

MongoDB 用户权限

If your MongoDB instance uses authentication, your BI Connector instance must also use authentication. The user that connects to MongoDB via the mongosqld program must have permission to read from all the namespaces you wish to sample data from.

有关 BI Connector 中 MongoDB 用户权限的更多详细信息，请参阅缓存采样的用户权限。

有关 MongoDB 用户和角色的更多信息，请参阅基于角色的访问控制。

See the example below of mongosqld with authentication.

默认最低 TLS 版本

2.6版本新增。

所有客户端连接的默认最低 TLS1.1mongosqld 版本为。这包括与的传入客户端连接以及与MongoDB的传出连接。

You can adjust this setting for incoming connections with the --minimumTLSVersion option and for outgoing connections with the --mongo-minimumTLSVersion option.

命令行选项

核心选项

--help: Returns information on the options and use of mongosqld.

--addr

默认值：127.0.0.1:3307

指定要监听的主机地址。

--version: Returns the mongosqld release number.

--config <path>: 指定配置文件的路径。

--mongo-uri <uri>

默认值：mongodb://localhost:27017

指定要连接到的 MongoDB 连接字符串。

The --mongo-uri option supports the following options within the connection string:

有关这些 URI 选项的详细信息，请参阅读取偏好（read preference）选项和副本集选项。

For options set in the Mongo URI not included in the list above, use the equivalent mongosqld option. For the complete list of mongosqld options, see Command Line Options.

注意

Instead of specifying a username and password in your connection string, run mongosqld with the --auth option to direct mongosqld to pass the authentication credentials provided by the SQL client to the MongoDB server.

Similarly, instead of enabling ssl in the connection string, run mongosqld with --mongo-ssl.

要禁用自动副本集服务器发现逻辑并强制连接到指定服务器，请使用 connect=direct 选项。

mongosqld --mongo-uri "mongodb://<hostname>:<port>/?connect=direct"

URI options not in the list above nor in the list of supported mongosqld options are not supported.

--mongo-versionCompatibility <version-number>

限制mongosqld 使用指定版本的MongoDB支持的功能。仅当与成员使用不同MongoDB版本的副本集一起使用或执行MongoDB滚动升级时才需要。仅支持MongoDB版本.3 2或更高版本。

示例，如果您的副本集包含运行MongoDB3.2 的成员和运行MongoDB3.4 的其他成员，设立以下选项以限制mongosqld 仅使用MongoDB3 支持的功能。2 ：

mongosqld --mongo-versionCompatibility 3.2

--maxVarcharLength <length>: 2.2版本新增。
Specifies the maximum length, in characters, for all varchar fields. If mongosqld encounters a string that is longer than the maximum length, mongosqld truncates it to the maximum length and logs a warning.

--mongo-username <username>, -u <username>: 2.3版本新增。
Specifies the authentication username to use for schema discovery. Only required if --auth is enabled. The user specified by --mongo-username must be a valid MongoDB user with the listDatabases privilege. See mongosqld User Permissions.

--mongo-password <password>, -p <password>: 2.3版本新增。
Specifies the authentication password to use for schema discovery. Only required if --auth is enabled. Use in conjunction with --mongo-username.

--mongo-authenticationSource <auth-db-name>

默认值：admin

2.3版本新增。

Specifies the database that holds the credentials for the schema discovery user. Only available if --auth is enabled. Use in conjunction with credential options --mongo-username and --mongo-password.

--mongo-authenticationMechanism <authMechanism>

默认值：SCRAM-SHA-1

2.3版本新增。

Specifies the authentication mechanism to use for schema discovery. Only available if --auth is enabled. Use in conjunction with credential options --mongo-username and --mongo-password.

值	说明
SCRAM-SHA-1	5802使用 SHA1 哈希函数的 RFC 标准 Salted 挑战响应身份验证机制。
SCRAM-SHA-256	版本 2.6 中的新增内容： RFC 7677 standard Salted Challenge Response Authentication Mechanism using the SHA2 hash function.
普通版 (LDAP SASL)	使用 LDAP 进行外部身份验证。您也可使用 `PLAIN` 对数据库内用户进行身份验证。`PLAIN` 以纯文本形式传输密码。此机制仅在 MongoDB Enterprise 中可用。
GSSAPI (Kerberos)	使用 Kerberos 的外部身份验证。此机制仅在 MongoDB Enterprise 中可用。

模式选项

--schema <filename>: 指定模式文件或模式目录的路径。

--schemaDirectory <directoryname>: 自版本 2.2 起已弃用。
Use --schema instead.

--sampleNamespaces <db.collection>

2.5版本新增。

--sampleNamespaces 在创建模式的数据采样过程中，指定包含或排除的数据库和数据集。还可以指定来自单个数据库的多个集合，或来自多个数据库的多个集合。请参见下面的示例。

If you do not use the --sampleNamespaces option or the --schema option, mongosqld samples data from all available MongoDB databases and collections except the admin and local databases.

--schemaMode <[custom|auto]>

默认值：custom

2.11版本新增。

Configures the sampling mode of mongosqld. Must be used with the --schemaSource option. The following values determine the sampling behavior:

值	`--schemaMode` 行为
`custom`	`mongosqld` reads a stored schema from the MongoDB database specified by the `--schemaSource` option.
`auto`	`mongosqld` samples the schema and writes the schema data to the MongoDB database specified by the `--schemaSource` option.

有关配置采样模式的更多信息，请参阅采样模式参考表。

重要

If mongosqld has authentication enabled, the authenticated user must have the write privilege on the specified --schemaSource database. See Built-In Roles for more information about the readWrite role.

--schemaSource <db-name>

2.11版本新增。

Required whenever the --schemaMode is set. Specifies the database where the schema information is stored.

注意

If you do not specify any of the --schema, --schemaMode, and --schemaSource options, mongosqld holds its schema in memory.

要了解有关采样模式的详情，请参阅采样模式参考图表。

--schemaName <db-name>

默认值：defaultSchema

2.11版本新增。

Optional. The name of the schema to load from or write to the --schemaSource database. Specifying schema names allows you to store multiple schemas in the --schemaSource database. The behavior depends on the value of --schemaMode:

`--schemaMode` 值	`--schemaName` 行为
`custom`	The name of the schema to load from the database specified by the `--schemaSource` option.
`auto`	The name of the schema to write to the `--schemaSource` database after the BI Connector samples the schema on startup.

重要

If you upload a custom schema, you must store it with its specified name, using name-schema, and then specify this name to the mongosqld with --schemaName. If you don't store the schema's name when you upload it, the schema name defaults to defaultSchema. If the schema's name doesn't exist, this results in an error from mongosqld similar to the following: MongoDB schema not yet available. Error initializing schema: no schema found for name.

要了解有关采样模式的详情，请参阅采样模式参考图表。

--sampleSize <number>

默认值：1000

2.3版本新增。

收集架构信息时每个命名空间要采样的文档数量。

Set --sampleSize to 0 to include all documents in the specified namespace when building the schema. If you do not specify a namespace, setting --sampleSize to 0 causes mongosqld to consider all documents in all databases (excluding local, admin, and system) when building the schema. See an example below.

--schemaRefreshIntervalSecs <number>

默认值：0

在版本 2.11 中进行了更改：

已将 --sampleRefreshIntervalSecs 重命名为 --schemaRefreshIntervalSecs

The interval in seconds at which mongosqld re-samples data to create its schema. The default value is 0, which means that after the initial sampling no automatic re-sampling occurs. The specified value must be a positive integer.

要强制对模式进行一次性更新，请在 SQL 客户端中使用 FLUSH SAMPLE 命令。

--uuidSubtype3Encoding <old|csharp|java>, -b <old|csharp|java>

指定用于生成 UUID 二进制子类型 3 的编码。选择下列值之一：

old：旧的 BSON 二进制子类型表示形式
csharp: C#/.NET 传统 UUID 表示形式
java：Java 传统 UUID 表示形式

--prejoin

2.6版本新增。

用于将数组和非数组数据合并到单个表中的模式选项。

包含数组的 MongoDB 文档通常会转换为表格格式，其中数组数据和非数组数据有单独的表。考虑一个名为 test 的 MongoDB 集合，其中包含以下文档：

{ "_id" : 1, "a" : 3, "b" : [ "orange", "apple", "pear" ] }

上述集合会转换为采用表格形式的以下两个表：

mysql> select * from test;
+------+------+
| _id  | a    |
+------+------+
|    1 |    3 |
+------+------+
mysql> select * from test_b;
+------+--------+-------+
| _id  | b      | b_idx |
+------+--------+-------+
|    1 | orange |     0 |
|    1 | apple  |     1 |
|    1 | pear   |     2 |
+------+--------+-------+

The --prejoin flag causes data from the a column to be included in the test_b table:

mysql> select * from test_b;
+------+------+--------+-------+
| _id  | a    | b      | b_idx |
+------+------+--------+-------+
|    1 |    3 | orange |     0 |
|    1 |    3 | apple  |     1 |
|    1 |    3 | pear   |     2 |
+------+------+--------+-------+

日志选项

--logAppend

Appends new logging output to an existing log file specified by --logPath.

Requires --logRotate.

--logPath <filename>

Default: stderr

指定用于存储日志输出的日志文件路径。

--logRotate reopen | rename

默认：重命名

指定要轮换日志以及如何轮换日志。

如果设置此选项，则在以下情况将发生日志轮换：您向 MongoDB Connector for BI 发出 FLUSH LOGS 命令，或者重启 mongosqld。

If you set --logRotate to rename:: 现有日志文件已关闭。 RFC3339 格式的时间戳将附加到已关闭的日志文件中。系统会创建一个新的日志文件。
If you set --logRotate to reopen:: 关闭并重新打开现有日志文件。

注意

在 UNIX 和 macOS 平台上，可发出 SIGUSR1 信号来重新启动 mongosqld 进程并轮换日志。

--usageLogInterval <number>

默认：60

2.14版本新增。

将使用情况统计信息写入日志的时间间隔（以秒为单位）。设为 0 可禁用使用情况日志记录。

注意

没有为 Windows 启用使用情况日志记录。

--verbose, -v

Specifies that mongosqld should provide more detailed log output.

下表描述了各日志级别提供的信息：

字母选项	日志级别	消息内容
`--quiet`	无	不记录任何内容。
No flag	默认	Log messages that notify user of basic `mongosqld` events and state changes.
`-v`	管理员	Log messages that provie information to `mongosqld` administrators.
`-vv`	开发人员	对于 MongoDB 支持和开发有用的日志消息。

--quiet: 隐藏所有日志输出。

MongoDB TLS/SSL 选项

重要

If you're using your own Certificate Authority (CA) to self-sign your server and client certificates, you must include the --mongo-sslAllowInvalidHostnames option to ensure authentication works correctly.

--mongo-ssl

默认值：False

Instructs mongosqld to use TLS/SSL when connecting to a MongoDB instance.

--mongo-sslPEMKeyFile <filename>

Specifies the .pem file containing both the TLS/SSL certificate and key for mongosqld to use when connecting to MongoDB. You can specify the file name of the .pem file using either using a relative or absolute path.

This option is required when using the --mongo-ssl option to connect to a mongod or mongos that has CAFile enabled without allowConnectionsWithoutCertificates.

--mongo-sslPEMKeyPassword <password>: 指定包含用于连接 MongoDB 的证书和私钥的文件的路径。

--mongo-sslAllowInvalidHostnames: Permits mongosqld to connect to a MongoDB server whose hostname differs from the hostname on its TLS/SSL certificate.

--mongo-sslAllowInvalidCertificates: Permits the MongoDB instance to present an invalid server SSL/TLS certificate. When using the allowInvalidCertificates setting, MongoDB logs the use of the invalid certificate as a warning.

--mongo-sslCAFile <filename>

指定 MongoDB 实例的 .pem 文件，其中包含来自证书颁发机构的根证书链。使用相对或绝对路径指定 .pem 文件的文件名称。

警告

在BI Connector 2.14.30 及更早版本上：

For SSL connections (--mongo-ssl) to mongod and mongos, if the mongosqld runs without the --mongo-sslCAFile, mongosqld will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file to validate the server certificates in cases where intrusion is a possibility.

从BI Connector版本2.14.31 --mongo-ssl开始，如果提供了标志，则还必须至少指定以下选项之一：

--mongo-sslCAFile
--mongo-sslAllowInvalidCertificates

--mongo-sslCRLFile <filename>: 指定 MongoDB 实例的 .pem 文件，其中包含证书吊销列表。

--mongo-sslFIPSMode: 在已安装的 OpenSSL 库中启用 FIPS 模式。

--mongo-minimumTLSVersion <TLS1_0|TLS1_1|TLS1_2>

默认：TLS1_1

指定与 mongod 或 mongos 的传出连接所需的最低 TLS 版本。实例。默认值 TLS1_1 对应于 TLS 版本 1.1。

客户端 TLS/SSL 选项

--sslMode <mode>

默认值：已禁用

2.3版本新增。

Enable or disable TLS/SSL for connections to mongosqld. The argument to the sslMode option can be one of the following:

值	说明
`disabled`	mongsqld 无法接受使用 TLS/SSL 进行安全保护的连接。
`allowSSL`	mongsqld 可接受使用 TLS/SSL 进行保护的连接。
`requireSSL`	mongsqld 只能接受使用 TLS/SSL 进行安全保护的连接。

--sslPEMKeyFile <filename>: 为 MySQL 客户端指定包含 TLS/SSL 证书和密钥的 .pem 文件。使用相对或绝对路径指定 .pem 文件的文件名。

--sslPEMKeyPassword <password>: Specifies the password used to decrypt the private key specified by --sslPEMKeyFile.

--sslAllowInvalidCertificates: 允许 MySQL 客户端提供无效的客户端 TLS/SSL 证书。

--sslAllowInvalidHostnames: Permits SQL clients to connect to a mongosqld whose hostname differs from the hostname on its TLS/SSL certificate.

--sslCAFile <filename>: Specifies the mongosqld .pem file containing the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

--sslCRLFile <filename>: Specifies the mongosqld .pem file containing the certificate revocation list.

--auth: 要求对传入的客户端请求进行身份验证。
重要
在版本2.4.0中进行了更改。
When authentication is enabled, admin credentials must be provided with the --mongo-username and --mongo-password options or the mongodb.net.auth.username and mongodb.net.auth.password settings in the configuration file.
mongosqld 使用管理档案收集采样命名空间上的元数据，并使用连接客户端的档案将数据限制为仅客户端有权读取的数据。有关管理员用户所需权限的更多信息，请参阅缓存采样的用户权限。

--defaultAuthSource <authSource>

默认值：admin

Specifies the default MongoDB authentication source. Set this value to specify a default source that mongosqld uses when authenticating with a MongoDB database. The authentication mechanisms GSSAPI and PLAIN use the $external source, while SCRAM-SHA-1 and SCRAM-SHA-256 use a MongoDB database as its source.

如果没有为此选项指定值，则默认为 MongoDB admin 数据库。

$external身份验证源将对系统用户的引用存储在名为$external的 MongoDB 数据库中，但档案存储在外部非 MongoDB 系统中，例如 LDAP 服务器。

任何使用默认值的连接都可以省略其 MySQL 或 Tableau 用户名中的 source 参数。

--defaultAuthMechanism <authMechanism>

默认值：SCRAM-SHA-1

Specifies the default authentication mechanism. Set this value to specify a default mechanism for connecting to mongosqld. Any connection which uses this specified default value can omit the mechanism value from its MySQL or Tableau username.

值	说明
SCRAM-SHA-1	RFC 5802 standard Salted Challenge Response Authentication Mechanism using the SHA1 hash function.
SCRAM-SHA-256	版本 2.6 中的新增内容： RFC 7677 standard Salted Challenge Response Authentication Mechanism using the SHA2 hash function.
普通版 (LDAP SASL)	使用 LDAP 进行外部身份验证。您也可使用 `PLAIN` 对数据库内用户进行身份验证。`PLAIN` 以纯文本形式传输密码。此机制仅在 MongoDB Enterprise 中可用。
GSSAPI (Kerberos)	使用 Kerberos 的外部身份验证。此机制仅在 MongoDB Enterprise 中可用。

--minimumTLSVersion <TLS1_0|TLS1_1|TLS1_2>

默认：TLS1_1

指定客户端连接到所需的最低 TLSmongosqld 版本。默认值TLS1_1 对应于 TLS 版本1 。1 。

服务选项

--serviceName <service-name>: Name of the system service which runs mongosqld.

--serviceDisplayName <service-name>: Display name of the system service which runs mongosqld.

--serviceDescription <service-name>: Description of the system service which runs mongosqld.

Kerberos Options

--gssapiHostname <hostname>

Default: First IP address for net.bindIp.

2.5版本新增。

用于配置 Kerberos 身份验证的 FQDN。Kerberos 主机名仅覆盖 Kerberos 配置的主机名。

--gssapiServiceName <service-name>

默认值：mongosql

2.5版本新增。

使用 Kerberos 的服务的注册名称。此选项支持您在每个实例的基础上覆盖 Kerberos SPN 的默认 Kerberos 服务名称组件。如未指定，则使用默认值。

--mongo-gssapiServiceName <service-name>

默认值：mongodb

2.5版本新增。

连接到 Kerberized MongoDB 实例时设置 Kerberos SPN。此值必须与 MongoDB 实例上设置的服务名称相匹配。

--gssapiConstrainedDelegation

默认值：False

2.11版本新增。

Use proxy credentials for Kerberos authorization, enabling constrained delegation. Requires mongosqld service credentials to be present in the client keytab as well as the service keytab. See Configure Kerberos for BI Connector for more information about Kerberos configuration.

套接字选项

--filePermissions <mode>

默认：0700

指定 UNIX 域套接字文件的权限。

--noUnixSocket: 禁用 Unix 域套接字上的侦听。

--unixSocketPrefix <path>

默认：/tmp

Specifies an alternative directory for the mongosqld Unix domain socket.

mongosqld will create a socket file called mysql.sock underneath this path. If you do not specify --unixSocketPrefix, the socket will exist at /tmp/mysql.sock.

设置参数选项

--setParameter <parameter>

Parameter	类型	对应
`"polymorphic_type_conversion_mode=<value>"`	字符串	Determines how `mongosqld` evaluates document fields that are specified with multiple data types. Accepted values are `off`, `fast`, and `safe`. To learn more about these values, see System Variables.
`"type_conversion_mode=<value>"`	字符串	Specifies which mode `mongosqld` uses to convert data types. BI Connector uses its own mode (`mongosql`) by default. Accepted values are `mongosql` and `mysql`. To learn more about these values, see System Variables.

The following example starts mongosqld and uses the --setParameter option to specify the type conversion mode:

mongosqld --setParameter "type_conversion_mode=mongosql"

配置文件

You may configure mongosqld using a YAML configuration file. This file may contain the settings listed in the following sections.

注意

您可以在配置文件中使用扩展指令来加载外部来源的配置值。扩展指令掩盖了安全证书和密码等机密信息。

要了解有关使用扩展指令的详细信息，请参阅 MongoDB 手册中的源自外部的配置文件值。

日志记录选项

systemLog:
  logAppend: <boolean>
  logRotate: "rename"|"reopen"
  path: <string>
  quiet: <boolean>
  verbosity: <integer>

名称	类型	对应
`systemLog.logAppend`	布尔	`--logAppend`
`systemLog.logRotate`	字符串	`--logRotate`
`systemLog.path`	字符串	`--logPath`
`systemLog.quiet`	布尔	`--quiet`
`systemLog.verbosity`	整型	`--verbose`

模式选项

schema:
  path: <string>
  maxVarcharLength: <integer>

名称	类型	对应
`schema.path`	字符串	`--schema`
`schema.maxVarcharLength`	整型	`--maxVarcharLength`

数据采样选项

schema:
  sample:
    size: <integer>
    prejoin: <boolean>
    namespaces: <array of strings>
    uuidSubtype3Encoding: <[old|csharp|java]>
  stored:
    mode: <[custom|auto]>
    source: <string>
    name: <db-name>
  refreshIntervalSecs: <integer>

名称	类型	对应
`schema.stored.mode`	字符串	`--schemaMode`
`schema.stored.source`	字符串	`--schemaSource`
`schema.stored.name`	字符串	`--schemaName`
`schema.sample.size`	整型	`--sampleSize`
`schema.sample.prejoin`	布尔	`--prejoin`
`schema.sample.namespaces`	字符串或字符串数组	`--sampleNamespaces`
`schema.refreshIntervalSecs`	整型	`--schemaRefreshIntervalSecs`
`schema.sample.uuidSubtype3Encoding`	字符串	`--uuidSubtype3Encoding`

运行时选项

runtime:
  memory:
    maxPerStage: <integer>
    maxPerServer: <integer>
    maxPerConnection: <integer>

重要

BI Connector provides the following options for controlling the amount of system memory which the mongosqld process may use for sending queries to MongoDB. These limits do not include the memory which BI Connector uses for other purposes, such as data structure overhead, so the total amount of memory BI Connector uses will be higher than the limits set with these options.

runtime.memory.maxPerStage

类型：整型

Default: unlimited

指定查询执行阶段可以使用的最大内存量（以字节为单位）。

runtime.memory.maxPerServer

类型：整型

Default: unlimited

2.5版本新增。

Specifies the maximum amount of memory in bytes that a mongosqld process may use.

runtime.memory.maxPerConnection

类型：整型

Default: unlimited

2.5版本新增。

Specifies the maximum amount of memory in bytes that a mongosqld client connection may use.

网络选项

net:
  bindIp: <string>
  port: <integer>
  unixDomainSocket:
    enabled: <boolean>
    pathPrefix: <string>
    filePermissions: <string>
  ssl:
    mode: <string>
    allowInvalidCertificates: <boolean>
    PEMKeyFile: <string>
    PEMKeyPassword: <string>
    CAFile: <string>

名称

类型

对应

net.bindIp

字符串

主机名组件 --addr

版本2.2 中的更改：要绑定到多个IP地址，请输入逗号分隔值的列表。

例如：

"72.198.41.200,72.198.41.201,72.198.41.202"

net.port

整型

端口组件 --addr

net.unixDomainSocket.enabled

布尔

反向 --noUnixSocket

net.unixDomainSocket.pathPrefix

字符串

--unixSocketPrefix

net.unixDomainSocket.filePermissions

字符串

--filePermissions

net.ssl.allowInvalidCertificates

布尔

--sslAllowInvalidCertificates

net.ssl.mode

字符串

--sslMode

net.ssl.PEMKeyFile

字符串

--sslPEMKeyFile

net.ssl.PEMKeyPassword

字符串

--sslPEMKeyPassword

net.ssl.CAFile

字符串

--sslCAFile

net.ssl.minimumTLSVersion

字符串

--minimumTLSVersion

安全选项

security:
  enabled: <boolean>
  defaultMechanism: <string>
  defaultSource: <string>
  gssapi:
    hostname: <string>
    serviceName: <string>

名称	类型	对应
`security.enabled`	布尔	`--auth`
`security.defaultMechanism`	字符串	`--defaultAuthMechanism`
`security.defaultSource`	字符串	`--defaultAuthSource`
`security.gssapi.hostname`	字符串	`--gssapiHostname`
`security.gssapi.serviceName`	字符串	`--gssapiServiceName`
`security.gssapi.constrainedDelegation`	字符串	`--gssapiConstrainedDelegation`

MongoDB 主机选项

mongodb:
  versionCompatibility: <string>
  net:
    uri: <string>
    ssl:
      enabled: <boolean>
      allowInvalidCertificates: <boolean>
      allowInvalidHostnames: <boolean>
      PEMKeyFile: <string>
      PEMKeyPassword: <string>
      CAFile: <string>
      CRLFile: <string>
      FIPSMode: <boolean>
    auth:
      username: <username>
      password: <password>
      source: <auth-db-name>
      mechanism: <auth-mechanism>
      gssapiServiceName: <service>

名称	类型	对应
`mongodb.versionCompatibility`	字符串	`--mongo-versionCompatibility`
`mongodb.net.uri`	字符串	`--mongo-uri`
`mongodb.net.ssl.enabled`	布尔	`--mongo-ssl`
`mongodb.net.ssl.allowInvalidCertificates`	布尔	`--mongo-sslAllowInvalidCertificates`
`mongodb.net.ssl.allowInvalidHostnames`	布尔	`--mongo-sslAllowInvalidHostnames`
`mongodb.net.ssl.PEMKeyFile`	字符串	`--mongo-sslPEMKeyFile`
`mongodb.net.ssl.PEMKeyPassword`	字符串	`--mongo-sslPEMKeyPassword`
`mongodb.net.ssl.CAFile`	字符串	`--mongo-sslCAFile`
`mongodb.net.ssl.CRLFile`	字符串	`--mongo-sslCRLFile`
`mongodb.net.ssl.FIPSMode`	布尔	`--mongo-sslFIPSMode`
`mongodb.net.ssl.minimumTLSVersion`	字符串	`--mongo-minimumTLSVersion`
`mongodb.net.auth.username`	字符串	`--mongo-username`
`mongodb.net.auth.password`	字符串	`--mongo-password`
`mongodb.net.auth.source`	字符串	`--mongo-authenticationSource`
`mongodb.net.auth.mechanism`	字符串	`--mongo-authenticationMechanism`
`mongodb.net.auth.gssapiServiceName`	字符串	`--mongo-gssapiServiceName`

流程管理选项

processManagement:
  service:
    name: <string>
    displayName: <string>
    description: <string>

名称	类型	对应
`processManagement.service.name`	字符串	`--serviceName`
`processManagement.service.displayName`	字符串	`--serviceDisplayName`
`processManagement.service.description`	字符串	`--serviceDescription`

设置参数选项

setParameter:
  polymorphic_type_conversion_mode: <string>
  type_conversion_mode: <string>

名称	类型	对应
`setParameter.polymorphic_type_conversion_mode`	字符串	Determines how `mongosqld` evaluates document fields that are specified with multiple data types. Accepted values are `off`, `fast`, and `safe`. To learn more about these values, see System Variables.
`setParameter.type_conversion_mode`	字符串	Specifies which mode `mongosqld` uses to convert data types. BI Connector uses its own mode (`mongosql`) by default. Accepted values are `mongosql` and `mysql`. To learn more about these values, see System Variables.

这些配置文件选项也可用作系统变量。有关更多信息，请参阅系统变量。

加载外部配置值

您可以在配置文件中使用扩展指令来加载外部来源的配置值。扩展指令掩盖了安全证书和密码等机密信息。

要了解有关使用扩展指令的详细信息，请参阅 MongoDB 手册中的源自外部的配置文件值。

示例配置文件

注意

此示例配置文件中使用的路径特定于 Linux。检查本地系统文档，确定系统的正确路径。

systemLog:
  logAppend: false
  path: "/var/log/mongosqld/mongosqld.log"
  verbosity: 2
security:
  enabled: true
mongodb:
  net:
    uri: "mongo.example.com:27017"
    auth:
      username: "root"
      password: "changeme"
net:
  bindIp: 192.0.2.14
  port: 3307
  ssl:
    mode: "allowSSL"
    PEMKeyFile: "/vagrant/certificates/mongosqld-server.pem"
    CAFile: "/vagrant/certificates/ca.crt"
schema:
  sample:
    namespaces: "inventory.*"
processManagement:
  service:
    name: mongosqld
    displayName: mongosqld
    description: "BI Connector SQL proxy server"

使用示例

`mongosqld` 带有模式文件

Use the --schema option to specify a schema file for mongosqld to use.

mongosqld --schema /path/to/schema-file.drdl

指定要采样的集合

Use the --sampleNamespaces option to specify a database and collection for mongosqld to sample data from. If you start mongosqld without the --sampleNamespaces option, it samples data from all available databases except the admin and local databases.

以下示例会对名为 contacts 的数据库中名为 addresses 的集合内的数据进行采样：

mongosqld --sampleNamespaces contacts.addresses

指定要采样的多个集合

To sample data from all the collections in a database, use the --sampleNamespaces option with a wildcard (*).

以下示例对名为 inventory 的数据库中所有集合中的数据进行采样：

mongosqld --sampleNamespaces 'inventory.*'

You can repeat the --sampleNamespaces at the command line to sample data from multiple collections within a database, or from multiple collections across several databases.

以下示例对名为 cars 和 boats 的数据库中所有集合中的数据进行采样：

mongosqld --sampleNamespaces 'cars.*' \
          --sampleNamespaces 'boats.*' \

You can mix and match wildcards and specific collections with multiple --sampleNamespaces options.

以下示例会对名为 orders 的数据库中的所有集合以及 expenses 数据库中的 FY2015 和 FY2016 集合内的数据进行采样：

mongosqld --sampleNamespaces 'orders.*' \
          --sampleNamespaces expenses.FY2015 \
          --sampleNamespaces expenses.FY2016 \

注意

使用通配符时，只需将命名空间用单引号括起。

从采样中排除数据库和集合

要从数据采样过程中排除指定的命名空间，请在命名空间前面添加 ~ （波浪号）字符。以下示例包括除fruit数据库中的apples集合之外的所有数据库和集合：

mongosqld --sampleNamespaces ~fruit.apples

使用 * 通配符字符以表示数据库中的所有集合。以下示例可从数据采样中排除整个 vehicles 数据库：

mongosqld --sampleNamespaces '~vehicles.*'

对集合中的所有文档进行采样

If you have a collection in which some documents have different fields from others and you want to ensure that the schema takes them all into consideration, set the --sampleSize option to 0. This causes mongosqld to examine all documents in the specified namespace when it builds its schema.

The following example instructs mongosqld to build the schema based on all documents in the inventory.electronics namespace.

mongosqld --sampleNamespaces inventory.electronics \
          --sampleSize 0

指定数据库以保存模式

Use the --schemaSource option to specify a database in which to store schema information. Use the --schemaMode option to specify whether mongosqld can write to the schema database or only read from it.

The following example command uses a database named sampleDb to store schema information and sets --schemaMode to auto.

mongosqld --schemaSource sampleDb --schemaMode auto

重要

指定数据重新采样间隔

Use the --schemaRefreshIntervalSecs option to specify an interval in seconds for mongosqld to resample data and regenerate the schema. The default value for this option is 0, which means that mongosqld never resamples data.

If you set a resampling interval with --schemaRefreshIntervalSecs and you specify a schema database with --schemaSource, you cannot set --schemaMode to custom.

以下示例未指定模式数据库或模式文件，因此它会将其模式保存在内存中。它使用--schemaRefreshIntervalSecs 指定3600 秒的数据重新采样间隔。

mongosqld --schemaRefreshIntervalSecs 3600

`mongosqld` （启用身份验证）

To connect mongosqld to a MongoDB instance running with authentication enabled, use the --auth option and provide MongoDB user credentials.

The following example starts mongosqld with credentials for a user named reportsUser with password reportsPass, who has access to the reports.inventory namespace.

mongosqld --auth \
          --mongo-username reportsUser \
          --mongo-password reportsPass \
          --sampleNamespaces reports.inventory

This example does not specify an authenticating database with the --mongo-authenticationSource option, so it defaults to admin. It does not specify an authentication mechanism with the --mongo-authenticationMechanism option, so it defaults to SCRAM-SHA-1.

`mongosqld` （带有配置文件）

如要指定将日志保存到 /var/log/mongosqld.log 并从 /var/schema.drdl 加载模式的配置文件，则可以将如下文件保存到 /etc/mongosqld.conf：

警告

配置文件中指定的所有路径都必须是绝对路径，例如它们必须以 / 开头。

systemLog:
  path: /var/log/mongosqld.log
schema:
  path: /var/schema.drdl

You may then start mongosqld with the --config option:

mongosqld --config /etc/mongosqld.conf

有关将 mongosqld 作为系统服务启动的更多信息，请参阅您操作系统的《安装指南》。

与 Atlas 一起使用

Atlas 是一项云服务，可用来运行、监控和维护 MongoDB 部署，包括为 MongoDB 实例预配专用服务器。

Atlas 默认使用 TLS/SSL 来加密连接并强制执行身份验证。

注意

对于 MongoDB Atlas 免费套餐，BI Connector 无法使用 allowDiskUse 选项运行聚合管道。此选项支持在聚合阶段将数据作为临时文件写入磁盘。要查看 MongoDB Atlas 免费套餐约束，请参阅 MongoDB Atlas 手册。

mongosqld 可以使用自签名证书或证书颁发机构颁发的任何有效 TLS 证书。如果使用自签名证书，尽管通信通道将被加密，但不会验证服务器身份。尽管这种情况可以防止连接被窃听，但它会让您容易受到中间人攻击。使用由受信任的证书颁发机构签名的证书将允许您的 MySQL 客户端验证服务器的身份。

出于测试目的，您可以使用 openssl 工具创建名为 test.pem 的 .pem 密钥文件：

openssl req -nodes -newkey rsa:2048 -keyout test.key -out test.crt -x509 -days 365 -subj "/C=US/ST=test/L=test/O=test Security/OU=IT Department/CN=test.com"
cat test.crt test.key > test.pem

Start mongosqld with the following options:

--mongo-ssl
--auth
--sslPEMKeyFile
--mongo-uri
--sslMode
--mongo-username
--mongo-password

如果已将密钥文件命名为 test.pem（如上一示例所示），则可运行以下命令来替换集群 URI 和登录档案：

mongosqld --mongo-ssl \
          --auth \
          --sslPEMKeyFile test.pem \
          --mongo-uri <uri> \
          --sslMode allowSSL \
          --mongo-username <username> \
          --mongo-password <password>

Pass your username, password, and authentication database to your SQL client. For example, using mysql without verifying your mongosqld server certificate:

mysql --host <mongosqld-host> --port <mongosqld-port> -u <username>?source=admin -p --ssl-mode required --enable-cleartext-plugin

有关将 mysql 客户端与 BI Connector 结合使用的更多详细信息，请参阅从 MySQL 客户端进行连接。

采样模式参考图

The chart below describes types of mongosqld startup configurations and the options used with each.

模式

mongosqld 选项

行为

独立模式

--schemaMode not used
--schemaSource not used

mongosqld在初创企业时对数据进行采样。如果--schemaRefreshIntervalSecs >0 ，按指定间隔重新采样。

例如：

mongosqld --schemaRefreshIntervalSecs 3600

有关详细信息，请参阅独立运行模式（缓存采样）。

自定义模式

--schemaMode custom
--schemaSource <dbName>
--schemaRefreshIntervalSecs not used

Read schema data from the database specified by --schemaSource.

例如：

mongosqld --schemaMode custom \
          --schemaSource schemaDb

Auto Schema

--schemaMode auto
--schemaSource <dbName>
--schemaRefreshIntervalSecs > 0

在用户指定的模式数据库中采样和保存模式数据。

例如：

mongosqld --schemaMode auto \
          --schemaSource schemaDb \
          --schemaRefreshIntervalSecs 3600

有关更多信息，请参阅 Auto Schema Mode（MongoDB 中的 Persist a Schema）。

无效配置

The following mongosqld option configurations are invalid and cause an error at startup.

模式	`mongosqld` 选项	行为
独立编写器（无效）	`--schemaMode` `auto` `--schemaSource` not used	This configuration is invalid for a standalone `mongod` instance because in `auto` mode there must be a writeable database specified.
集群采样读取器（无效）	`--schemaMode` `custom` `--schemaSource` <dbName> `--schemaRefreshIntervalSecs` > 0	When used in a MongoDB replica set or sharded cluster, this configuration is invalid. When a database is specified for storing schema data with `--schemaSource`, `--schemaMode` must be set to `auto` so that the schema may be updated from the primary to maintain cluster-wide consistency.

mongosqld

说明

使用

使用模式文件启动 mongosqld

使用模式数据库启动 mongosqld

mongosqld使用指定的命名空间启动

MongoDB 用户权限

默认最低 TLS 版本

命令行选项

核心选项

模式选项

日志选项

MongoDB TLS/SSL 选项

客户端 TLS/SSL 选项

服务选项

Kerberos Options

套接字选项

设置参数选项

配置文件

日志记录选项

模式选项

数据采样选项

运行时选项

网络选项

安全选项

MongoDB 主机选项

流程管理选项

设置参数选项

加载外部配置值

示例配置文件

使用示例

mongosqld 带有模式文件

指定要采样的集合

指定要采样的多个集合

从采样中排除数据库和集合

对集合中的所有文档进行采样

指定数据库以保存模式

指定数据重新采样间隔

mongosqld （启用身份验证）

mongosqld （带有配置文件）

与 Atlas 一起使用

采样模式参考图

无效配置

`mongosqld`

使用模式文件启动 `mongosqld`

使用模式数据库启动 `mongosqld`

`mongosqld`使用指定的命名空间启动

`mongosqld` 带有模式文件

`mongosqld` （启用身份验证）

`mongosqld` （带有配置文件）