community.mongodb.mongodb_shell module – Run commands via the MongoDB shell.
Note
This module is part of the community.mongodb collection (version 1.7.8).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.mongodb.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.mongodb.mongodb_shell.
New in community.mongodb 1.1.0
Synopsis
Run commands via the MongoDB shell.
Commands provided with the eval parameter or included in a Javascript file.
Attempts to parse returned data into a format that Ansible can use.
Module uses the mongosh shell by default.
Support for mongo is depreciated.
Requirements
The below requirements are needed on the host that executes this module.
mongosh
Parameters
Parameter |
Comments |
|---|---|
Additional arguments to supply to the mongo command. Supply as key-value pairs. If the parameter is a valueless flag supply an empty string as the value. |
|
Authentication path intended for MongoDB Atlas Instances Choices:
|
|
Authentication type. Choices:
|
|
Additional connection options. Supply as a list of dicts or strings containing key value pairs seperated with ‘=’. |
|
The database to run commands against Default: |
|
show additional debug info. Choices:
|
|
A MongoDB command to run. |
|
Path to a file containing MongoDB commands. |
|
Provides a form of pseudo-idempotency to the module. We perform a hash calculation on the contents of the eval key or the file name provided in the file key. When the command is first execute a filed called <hash>.success will be created. The module will not rerun the command if this file exists and idempotent is set to true. Choices:
|
|
The database where login credentials are stored. Default: |
|
The host running MongoDB instance to login to. Default: |
|
The password used to authenticate with. Required when login_user is specified. |
|
The MongoDB server port to login to. Default: |
|
The MongoDB user to login with. Required when login_password is specified. |
|
The MongoDB shell command. auto - Automatically detect which MongoDB shell command used. Use “mongosh” if available, else use “mongo” command. mongo - This should still work for most cases but you might have problems with json parsinf. Use transform_type of ‘raw’ is you encounter problems. Default: |
|
Specify a non-default encoding for output. Choices:
|
|
Prevents the shell from sourcing and evaluating ~/.mongorc.js on start up. Choices:
|
|
Parameter to omit from the command line. This should match the parameter name that the MongoDB shell accepts not the module name. Default: |
|
Silences output from the shell during the connection process.. Choices:
|
|
Used by the split action in the transform stage. Default: |
|
Whether to use an SSL connection when connecting to the database. Choices:
|
|
The ssl_ca_certs option takes a path to a CA file. |
|
Specifies whether a certificate is required from the other side of the connection, and whether it will be validated if provided. Choices:
|
|
Present a client certificate using the ssl_certfile option. |
|
The ssl_crlfile option takes a path to a CRL file. |
|
Private key for the client certificate. |
|
Passphrase to decrypt encrypted private keys. |
|
Enforce strict requirements for pymongo and MongoDB software versions Choices:
|
|
Wraps the command in eval in JSON.stringify(<js cmd>) (mongo) or EJSON.stringify(<js cmd>) (mongosh). Useful for escaping documents that are returned in Extended JSON format. Automatically set to false when using mongo. Automatically set to true when using mongosh. Set explicitly to override automatic selection. Choices:
|
|
Transform the output returned to the user. auto - Attempt to automatically decide the best tranformation. split - Split output on a character. json - parse as json. raw - Return the raw output. Choices:
|
Examples
- name: Run the listDatabases command
community.mongodb.mongodb_shell:
login_user: user
login_password: secret
eval: "db.adminCommand('listDatabases')"
- name: List collections and stringify the output
community.mongodb.mongodb_shell:
login_user: user
login_password: secret
eval: "db.adminCommand('listCollections')"
stringify: yes
- name: Run the showBuiltinRoles command
community.mongodb.mongodb_shell:
login_user: user
login_password: secret
eval: "db.getRoles({showBuiltinRoles: true})"
- name: Run a js file containing MongoDB commands with pseudo-idempotency
community.mongodb.mongodb_shell:
login_user: user
login_password: secret
file: "/path/to/mongo/file.js"
idempotent: yes
- name: Provide a couple of additional cmd args
community.mongodb.mongodb_shell:
login_user: user
login_password: secret
eval: "db.adminCommand('listDatabases')"
additional_args:
verbose: True
networkMessageCompressors: "snappy"
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Change status. Returned: always |
|
Raw stderr from mongo. Returned: when debug is set to true |
|
Something went wrong. Returned: on failure |
|
JS file that was executed successfully. Returned: When a js file is used. |
|
A message indicating what has happened. Returned: always |
|
Raw stdout from mongo. Returned: when debug is set to true |
|
Return code from mongo. Returned: when debug is set to true |
|
Output from the mongo command. We attempt to parse this into a list or json where possible. Returned: on success |