W3cubDocs

/Ansible

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