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

Note

This module is part of the community.mongodb collection (version 1.4.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

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

The database to run commands against

Default: “test”

debug

boolean

show additional debug info.

Choices:

  • no ← (default)

  • yes

eval

string

A MongoDB command to run.

file

string

Path to a file containing MongoDB commands.

idempotent

boolean

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:

  • no ← (default)

  • yes

login_database

string

The database where login credentials are stored.

Default: “admin”

login_host

string

The host running MongoDB instance to login to.

Default: “localhost”

login_password

string

The password used to authenticate with.

Required when login_user is specified.

login_port

integer

The MongoDB server port to login to.

Default: 27017

login_user

string

The MongoDB user to login with.

Required when login_password is specified.

mongo_cmd

string

The MongoDB shell command.

Default: “mongo”

nodb

boolean

Specify a non-default encoding for output.

Choices:

  • no ← (default)

  • yes

norc

boolean

Prevents the shell from sourcing and evaluating ~/.mongorc.js on start up.

Choices:

  • no ← (default)

  • yes

omit

list / elements=string

Parameter to omit from the command line.

This should match the parameter name that the MongoDB shell accepts not the module name.

Default: []

quiet

boolean

Silences output from the shell during the connection process..

Choices:

  • no

  • yes ← (default)

split_char

string

Used by the split action in the transform stage.

Default: ” “

strict_compatibility

boolean

Enforce strict requirements for pymongo and MongoDB software versions

Choices:

  • no

  • yes ← (default)

stringify

boolean

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:

  • no

  • yes

transform

string

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:

  • auto ← (default)

  • split

  • json

  • raw

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

changed

boolean

Change status.

Returned: always

err

string

Raw stderr from mongo.

Returned: when debug is set to true

failed

boolean

Something went wrong.

Returned: on failure

file

string

JS file that was executed successfully.

Returned: When a js file is used.

msg

string

A message indicating what has happened.

Returned: always

out

string

Raw stdout from mongo.

Returned: when debug is set to true

rc

integer

Return code from mongo.

Returned: when debug is set to true

transformed_output

list / elements=string

Output from the mongo command. We attempt to parse this into a list or json where possible.

Returned: on success

Authors

  • Rhys Campbell (@rhysmeister)