community.mongodb.mongodb_shell – Run commands via the MongoDB shell.

Note

This plugin is part of the community.mongodb collection (version 1.3.1).

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.

To use it in a playbook, specify: community.mongodb.mongodb_shell.

New in version 1.1.0: of community.mongodb

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 currently uses the mongo shell by default. This will change to mongosh in an upcoming version and support for mongo will be dropped

Requirements

The below requirements are needed on the host that executes this module.

mongo or mongosh

Parameters

Parameter	Choices/Defaults	Comments
additional_args raw		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.
db string	Default: "test"	The database to run commands against
debug boolean	Choices: no ← yes	show additional debug info.
eval string		A MongoDB command to run.
file string		Path to a file containing MongoDB commands.
idempotent boolean	Choices: no ← yes	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.
login_database string	Default: "admin"	The database where login credentials are stored.
login_host string	Default: "localhost"	The host running MongoDB instance to login to.
login_password string		The password used to authenticate with. Required when login_user is specified.
login_port integer	Default: 27017	The MongoDB server port to login to.
login_user string		The MongoDB user to login with. Required when login_password is specified.
mongo_cmd string	Default: "mongo"	The MongoDB shell command.
nodb boolean	Choices: no ← yes	Specify a non-default encoding for output.
norc boolean	Choices: no ← yes	Prevents the shell from sourcing and evaluating ~/.mongorc.js on start up.
quiet boolean	Choices: no yes ←	Silences output from the shell during the connection process..
split_char string	Default: " "	Used by the split action in the transform stage.
stringify boolean	Choices: no yes	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.
transform string	Choices: auto ← split json raw	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.

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	Returned	Description
changed boolean	always	Change status.
err string	when debug is set to true	Raw stderr from mongo.
failed boolean	on failure	Something went wrong.
file string	When a js file is used.	JS file that was executed successfully.
msg string	always	A message indicating what has happened.
out string	when debug is set to true	Raw stdout from mongo.
rc integer	when debug is set to true	Return code from mongo.
transformed_output list / elements=string	on success	Output from the mongo command. We attempt to parse this into a list or json where possible.

Authors

Rhys Campbell (@rhysmeister)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/mongodb/mongodb_shell_module.html

Docs

Docs4dev

Title here