db.updateRole()¶

On this page

Definition
Behavior
Required Access
Example

Definition¶

db.updateRole(rolename, update, writeConcern)¶

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

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:

Warning

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

The updateRole() method uses the following syntax:

copy

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

The db.updateRole() method takes 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 update operation. The `writeConcern` document takes the same fields as the `getLastError` command.

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.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.updateRole() runs, you can either specify the role with the name of the role:

copy

"readWrite"

Or you can specify the role with a document, as in:

copy

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

To specify a role that exists in a different database, specify the role with a document.

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

Behavior¶

Replica set¶

If run on a replica set, db.updateRole() is executed using majority write concern by default.

Scope¶

Except for roles created in the admin database, a role can only include privileges that apply to its database and can only inherit from other roles in its database.

A role created in the admin database can include privileges that apply to the admin database, other databases or to the cluster resource, and can inherit from roles in other databases as well as the admin database.

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

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:

copy

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.

← db.revokeRolesFromRole() Replication Methods →