db.updateRole()

Definition

db.updateRole( rolename, update, writeConcern )

Updates a user-defined role. The db.updateRole() method must run on the role's database.

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the updateRole command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

An update to a field completely replaces the previous field's values. To grant or remove roles or privileges without replacing all values, use one or more of the following methods:

• db.grantRolesToRole()

• db.grantPrivilegesToRole()

• db.revokeRolesFromRole()

• db.revokePrivilegesFromRole()

Warning

An update to the privileges or roles array completely replaces the previous array's values.

The db.updateRole() method uses the following syntax:

db.updateRole(
    "<rolename>",
    {
      privileges:
          [
            { resource: { <resource> }, actions: [ "<action>", ... ] },
            ...
          ],
      roles:
          [
            { role: "<role>", db: "<database>" } | "<role>",
            ...
          ],
      authenticationRestrictions:
          [
            {
              clientSource: ["<IP>" | "<CIDR range>", ...],
              serverAddress: ["<IP>", | "<CIDR range>", ...]
            },
            ...
          ]
    },
    { <writeConcern> }
)

The db.updateRole() method accepts the following arguments:

Parameter	Type	Description
rolename	string	The name of the user-defined role to update.
update	document	A document containing the replacement data for the role. This data completely replaces the corresponding data for the role.
writeConcern	document	Optional. The level of write concern for the operation. See Write Concern Specification.

The update document specifies the fields to update and the new values. Each field in the update document is optional, but the document must include at least one field. The update document has the following fields:

Field	Type	Description
privileges	array	Optional. Required if you do not specify roles array. The privileges to grant the role. An update to the privileges array overrides the previous array's values. For the syntax for specifying a privilege, see the privileges array.
roles	array	Optional. Required if you do not specify privileges array. The roles from which this role inherits privileges. An update to the roles array overrides the previous array's values.
authenticationRestrictions	array	Optional. The authentication restrictions the server enforces on the role. Specifies a list of IP addresses and CIDR ranges users granted this role are allowed to connect to and/or which they can connect from. New in version 3.6.

The db.updateRole() method wraps the updateRole command.

Compatibility

This method is available in deployments hosted in the following environments:

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

"readWrite"

{ role: "<role>", db: "<database>" }

Behavior

Required Access

You must have the revokeRole action on all databases in order to update a role.

You must have the grantRole action on the database of each role in the roles array to update the array.

You must have the grantRole action on the database of each privilege in the privileges array to update the array. If a privilege's resource spans databases, you must have grantRole on the admin database. A privilege spans databases if the privilege is any of the following:

• a collection in all databases

• all collections and all database

• the cluster resource

You must have the setAuthenticationRestriction action on the database of the target role to update a role's authenticationRestrictions document.

Example

The following db.updateRole() method replaces the privileges and the roles for the inventoryControl role that exists in the products database. The method runs on the database that contains inventoryControl:

use products
db.updateRole(
    "inventoryControl",
    {
      privileges:
          [
            {
              resource: { db:"products", collection:"clothing" },
              actions: [ "update", "createCollection", "createIndex"]
            }
          ],
      roles:
          [
            {
              role: "read",
              db: "products"
            }
          ]
    },
    { w:"majority" }
)

To view a role's privileges, use the rolesInfo command.