CREATE MONGODB CONNECTION¶

CREATE MONGODB CONNECTION registers a MongoDB connection with a name and connection options, enabling MatrixOne to query external MongoDB collections through external tables.

Description¶

CREATE MONGODB CONNECTION registers a MongoDB connection in MatrixOne. After registering a connection, you can create an external table with ENGINE = mongodb that maps a MongoDB collection, and query it with standard SQL.

Connections use hosts to list seed servers, or srv_host for DNS SRV discovery. Authentication defaults to the SCRAM-SHA-256 mechanism against the admin authentication source, and TLS is required by default.

Exactly one of hosts and srv_host must be specified. credential_secret_ref is required. In v4.2.0, CN services use the built-in environment resolver, so the reference must be an account-scoped secret://env/... name; MatrixOne does not accept a password directly in the DDL.

To change an existing connection, use ALTER MONGODB CONNECTION ... SET (...), ... ENABLE, or ... DISABLE. To remove one, use DROP MONGODB CONNECTION.

Prerequisites¶

Before creating a MongoDB connection:

Configure the required account-scoped environment credential described below.
Configure the hostname or CIDR allowlist for the MongoDB endpoint.
Provide exactly one of hosts or srv_host.
Ensure that the MatrixOne host can reach the MongoDB endpoint.

The v4.2.0 constructor defaults the connector to enabled, but endpoint access is fail-closed until an allowlist is configured on every CN. DNS names require allowed-host-suffixes; direct IP addresses require allowed-cidrs; loopback addresses require allow-loopback = true. For example:

[cn.frontend.mongodb]
enable = true
allowed-host-suffixes = ["example.com"]
allowed-cidrs = ["192.0.2.0/24"]

The v4.2.0 built-in EnvSecretResolver accepts only secret://env/... references. For the system account, the environment-variable name must start with MO_MONGODB_; tenant account N must use MO_MONGODB_ACCOUNT_N_. The value is strict JSON with lowercase username and password fields:

export MO_MONGODB_DOCS_CREDENTIAL='{"username":"docs_reader","password":"replace-me"}'

Use secret://env/MO_MONGODB_DOCS_CREDENTIAL for the system account. In a multi-CN deployment, define the same environment variable in every CN process that can plan or execute the external scan, distribute it through the deployment secret mechanism, and restart or roll the CNs consistently. Environment variables are intended for local or controlled deployments; a production secret-manager integration must enforce the same account namespace. Do not put credentials in hosts, srv_host, or options_json.

Syntax¶

CREATE MONGODB CONNECTION connection_name WITH ("option" = 'value' [, "option" = 'value'] ...)

Arguments¶

Option	Description
`hosts`	Conditionally required. A comma-separated list of `host:port` seed servers. Must not be specified together with `srv_host`.
`srv_host`	Conditionally required. A DNS SRV host without user information, path, or port. Must not be specified together with `hosts`.
`replica_set`	Optional. The replica set name.
`auth_source`	Optional. The authentication database. Defaults to `admin`.
`auth_mechanism`	Optional. The authentication mechanism. Defaults to `SCRAM-SHA-256`.
`credential_secret_ref`	Required. In v4.2.0, an account-scoped environment reference such as `secret://env/MO_MONGODB_DOCS_CREDENTIAL`.
`tls_mode`	Optional. The TLS mode. Defaults to `required`.
`tls_ca_secret_ref`	Optional. A reference to a stored CA certificate secret.
`read_preference`	Optional. The read preference. Defaults to `secondaryPreferred`.
`read_concern`	Optional. The read concern. Defaults to `majority`.
`max_staleness_seconds`	Optional. The maximum allowed replication lag in seconds.
`options_json`	Optional. A JSON document with additional connection options.

Examples¶

CREATE MONGODB CONNECTION docs_mongo WITH (
    "hosts" = 'mongo1.example.com:27017,mongo2.example.com:27017',
    "credential_secret_ref" = 'secret://env/MO_MONGODB_DOCS_CREDENTIAL',
    "replica_set" = 'rs0',
    "read_preference" = 'secondaryPreferred'
);

The example host names are placeholders. example.com must be included in allowed-host-suffixes on every CN before the connection can be created or used.