db.createRole()¶

Definition¶

db.createRole(role, writeConcern)¶

Creates a role and specifies its privileges. The role applies to the database on which you run the method. The db.createRole() method returns a duplicate role error if the role already exists in the database.

The db.createRole() method takes the following arguments:

Parameter	Type	Description
`role`	document	A document containing the name of the role and the role definition.
`writeConcern`	document	Optional. The level of write concern to apply to this operation. The `writeConcern` document uses the same fields as the `getLastError` command.

The role document has the following form:

{ role: "<name>",
  privileges: [
     { resource: { <resource> }, actions: [ "<action>", ... ] },
     ...
  ],
  roles: [
     { role: "<role>", db: "<database>" } | "<role>",
      ...
  ]
}

The role document has the following fields:

Field	Type	Description
`role`	string	The name of the new role.
`privileges`	array	The privileges to grant the role. A privilege consists of a resource and permitted actions. You must specify the `privileges` field. Use an empty array to specify no privileges. For the syntax of a privilege, see the `privileges` array.
`roles`	array	An array of roles from which this role inherits privileges. You must specify the `roles` field. Use an empty array to specify no roles.

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.createRole() runs, you can either specify the role with the name of the role:

"readWrite"

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

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

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

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

Behavior¶

A role’s privileges apply to the database where the role is created. The role can inherit privileges from other roles in its database. A role created on the admin database can include privileges that apply to all databases or to the cluster and can inherit privileges from roles in other databases.

Required Access¶

To create a role in a database, the user must have:

the createRole action on that database resource.
the grantRole action on that database to specify privileges for the new role as well as to specify roles to inherit from.

Built-in roles userAdmin and userAdminAnyDatabase provide createRole and grantRole actions on their respective resources.

Example¶

The following db.createRole() method creates the myClusterwideAdmin role on the admin database:

use admin
db.createRole({ role: "myClusterwideAdmin",
  privileges: [
    { resource: { cluster: true }, actions: [ "addShard" ] },
    { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
    { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
    { resource: { db: "", collection: "" }, actions: [ "find" ] }
  ],
  roles: [
    { role: "read", db: "admin" }
  ],
  writeConcern: { w: "majority" , wtimeout: 5000 }
})

← Role Management Methods db.dropAllRoles() →