- Concept
- Version · 5.2.2
- Integration guide
Best practices for configuring MongoDB user roles with Liquibase
Last updated: August 12, 2026
The Liquibase MongoDB Secure Extension and Community extension access MongoDB as a user and respect all MongoDB role-based security structures. That means that you must provide sufficient privileges to the user ID that Liquibase is using so that Liquibase can operate as you want.
This guide discusses two approaches to creating a user with sufficient privileges for Liquibase and the MongoDB extension to perform all of their functionality. The two methods include the built-in roles method and the user-defined role method. It is possible to create more restrictive setups, but depending on which restrictions are imposed, some Liquibase and MongoDB extension features may not work.
Role requirements
The two methods to create a user with privileges for Liquibase include the built-in roles method and the user-defined role method. The built-in role method allows you to provide different levels of access commonly needed in a database system. The user-defined role method allows for custom role creation when the built-in roles cannot describe the privileges necessary for the job.
Permissions: roles required to manage non-administrative database changes
The minimum required roles and permissions for Liquibase to manage changes to non-system collections and the system.js collection are:
readWritecollMod
Roles Required to Manage Administrative Tasks
readWritedbAdmin
As a MongoDB administrator, you have the ability to create a user using these standard roles or you can create your own custom roles. Liquibase supports both approaches as long as the resulting permissions meet the above requirements.
Built-in roles method
This method allows you to create a user that has readWrite and dbAdmin roles. when dbAdmin roles are enabled, this user can run the Liquibase MongoDB extension directly from the administrative perspective. As mentioned above, the built-in role method allows you to provide different levels of access commonly needed in a database system. If you need a user to have administrative access, use this guide.
Note: Without dbAdmin role permissions, you cannot run the MongoDB extension from the administrative perspective.
Create a user with the built-in readWrite and dbAdmin roles by executing the following code in one of two ways:
With your own user, password, and database content, use Mongo Shell directly in MongoDB to execute the code.
With your own user, password, and database content, add this code as part of the Docker
init-scriptif you use Docker to start your database.
db.createUser(
{
user: "lbuser",
pwd: "password",
roles: [
{
role: "readWrite",
db: "yourdb"
},
{
role: "dbAdmin",
db: "yourdb"
}
]
}
);
User-defined roles method
This method allows you to create a custom user-defined role that is inherited from the readWrite role. If a user does not need the dbAdmin role for security purposes, use this method.
Create a role with readWrite with only one additional collMod privilege by executing the two sections of code in one of two ways:
With your own user, password, and database content, use Mongo Shell directly in MongoDB to execute the code.
With your own user, password, and database content, add this code as part of the Docker
init-scriptif you use Docker to start your database.
This section allows you to create a role with a specific action:
db.createRole(
{
role: "liquibase_role",
privileges: [{resource: {db: 'yourdb', collection: ''}, actions: ['collMod']}],
roles: [
{ role: "readWrite", db: "yourdb" }
]
}
)
Assign the roles to your new created user:
db.createUser(
{
user: "lbuser",
pwd: "password",
roles: [
{
role: "liquibase_role",
db: "yourdb"
}
]
}
);