mongodrdl

Core Options

--help

Returns information on the options and use of mongodrdl.

--version

Returns the mongodrdl release number.

--verbose <level>, -v <level>

Specifies that mongodrdl should provide more detailed log output. Include multiple times for more verbosity (e.g. -vvvvv), or specify a numeric value (e.g. --verbose=5).

--quiet

Hides all log output.

--uri <mongodb-uri>

New in version 2.12.

MongoDB URI connection string.

Important

The following command-line options cannot be used in conjunction with --uri option:

• --host

• --port

• --db

• --username

• --password (if the URI connection string also includes the password)

• --authenticationDatabase

• --authenticationMechanism

Instead, specify these options as part of your --uri connection string.

--host <hostname><:port>, -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongodrdl attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replSetName and a seed list of set members, as in the following:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--db <database>, -d <database>

Specifies a database from which to generate a .drdl schema file.

--collection <collection>, -c <collection>

Specifies a collection from which to generate a .drdl schema file. If you do not specify a collection, this option will use all collections in the specified database or instance.

--customFilterField <name>, -f <name>

Specifies the field name to add for a custom MongoDB filter. See Custom Filters for more details.

--out <path>, -o <path>

Default: Standard out.

Specifies the path where mongodrdl will write the schema file. To send the schema to standard output, specify "-" instead of a path.

--sampleSize <size>, -s <size>

Default: 1000

Specifies the number of documents to sample when generating the collection's schema.

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

Specify the encoding used to generate UUID binary subtype 3. Choose one of the following values:

• old: Old BSON binary subtype representation

• csharp: The C#/.NET legacy UUID representation

• java: The Java legacy UUID representation

--preJoined

Generate unwound tables including parent columns, resulting in a "pre-joined" table.

--schema <db-id>

New in version 2.11.

Required. Specifies the string representation of the ObjectId of the schema.

--name <db-name>

New in version 2.11.

Specifies the schema name.

Important

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.

--schemaSource <db-name>

New in version 2.11.

Specifies the database where the schema information is stored. This option is not used by the sample command.

TLS/SSL Options

--ssl

Default: False

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

--sslCAFile <filename>

Specifies the MongoDB instance's .pem file containing the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

Warning

For SSL connections (--ssl) to mongod and mongos, if the mongodrdl runs without the --sslCAFile, mongodrdl 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.

--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 --ssl option to connect to a mongod or mongos that has CAFile enabled without net.ssl.allowConnectionsWithoutCertificates.

--sslPEMKeyPassword <password>

Specifies the path to a file containing the certificate and private key for connecting to MongoDB.

--sslCRLFile <filename>

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

--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.

--sslAllowInvalidHostnames

Disables the validation of the hostnames in TLS/SSL certificates. Allows mongodrdl to connect to MongoDB instances if the hostname their certificates do not match the specified hostname.

--sslFIPSMode

Directs the mongodrdl to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

--minimumTLSVersion <TLS1_0|TLS1_1|TLS1_2>

Default: TLS1_1

Specifies the minimum required TLS version for mongodrdl to connect to a mongod or mongos instance. The default value TLS1_1 corresponds to TLS version 1.1.

Authentication Options

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

--authenticationDatabase <dbname>

Specifies the database in which the user is created. See Authentication Database.

--authenticationMechanism <name>

Default: SCRAM-SHA-1

Specifies the authentication mechanism the mongodrdl instance uses to authenticate to the mongod or mongos.

Value	Description
SCRAM-SHA-1	RFC 5802 standard Salted Challenge Response Authentication Mechanism using the SHA1 hash function.
SCRAM-SHA-256	New in version 2.6: RFC 7677 standard Salted Challenge Response Authentication Mechanism using the SHA2 hash function.
PLAIN (LDAP SASL)	External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise.
GSSAPI (Kerberos)	External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise.

--gssapiServiceName <service-name>

Default: mongodb

Service name to use when authenticating using GSSAPI/Kerberos.

--gssapiHostName <hostname>

Default: remote server's address

Hostname to use when authenticating using GSSAPI/Kerberos.

Custom Filters

BI Connector uses a MongoDB aggregation pipeline to perform queries against a MongoDB database. You can add a special field to your schema to pass a custom MongoDB $match query string to your MongoDB instance.

Use the --customFilterField option with mongodrdl to name a custom filter field. This field passes a native MongoDB $match stage to use as the first stage of the aggregation pipeline, which filters any results returned from MongoDB. The BI Connector applies this stage before any additional stages pushed down from SQL.

The query can refer to any field in the collection, even if the fields are not exposed in the relational schema.

For an example of custom filter usage, see Custom Filter Example.

Schema Generation Example

Given documents of the following shape in the collection abc in the database test:

{
    "_id": ObjectId(),
    "close": 7.45,
    "detail": { "a": 2, "b": 3 }
}

Run mongodrdl to generate a schema based on this collection:

mongodrdl -d test -c abc -o schema.drdl

The generated schema file (schema.drdl) looks similar to the following:

schema:
- db: test
  tables:
  - table: abc
    collection: abc
    pipeline: []
    columns:
    - Name: _id
      MongoType: bson.ObjectId
      SqlName: _id
      SqlType: varchar
    - Name: close
      MongoType: float64
      SqlName: close
      SqlType: numeric
    - Name: detail.a
      MongoType: float64
      SqlName: detail.a
      SqlType: numeric
    - Name: detail.b
      MongoType: float64
      SqlName: detail.b
      SqlType: numeric

Custom Filter Example

To use this field, specify the --customFilterField flag with the name you want this field to have:

mongodrdl [ other options ] --customFilterField _MONGOFILTER -o schema.drdl

Your DRDL file schema.drdl will include the following field in every generated table:

- Name: _MONGOFILTER
  MongoType: mongo.Filter
  SqlName: _MONGOFILTER
  SqlType: varchar

To add the special MongoDB query stage to your standard SQL, use the following SQL syntax:

SELECT <normal>
  FROM <tablename>
  WHERE <normal conditions> AND
      _MONGOFILTER='{ <json string that represents query to use> }'
SELECT name,age
  FROM users
  WHERE active='t' AND
      _MONGOFILTER='{"addr":{"$elemMatch":{"city":"Springfield","state":"CA"}}}'

The BI Connector will translate the above SQL into the following MongoDB aggregation expression:

db.users.aggregate([
   {$match:{"addr":{"$elemMatch":{"city":"Springfield","state":"CA"}}},
   {$match:{"active":true}},
   {$project:{"name":1, "age":1}}
]);

You can use this custom filter in any business intelligence tool by filtering on your special field and providing the value to match as a single quoted string representing valid JSON. All quotes inside the JSON must be double quotes.

Authentication Example

If your MongoDB server is running with authentication enabled, you must specify a username, password, and authentication database as options to your mongodrdl command.

To create a .drdl file from a mongod instance with authentication enabled, use the following command format:

mongodrdl --host myhost.example.net:27017 \
          --username dbUser \
          --password myPassword \
          --db reports \
          --collection FY2017 \
          --authenticationDatabase admin \
          --out schema.drdl