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

Note

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

To install it use: ansible-galaxy collection install community.mongodb.

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

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.

Requirements

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

  • mongo

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>).
Useful for escaping documents that are returned in Extended JSON format.
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)