Migrating RBAC with custom roles
This guide is intended for users with the Admin role in ClickHouse Cloud.
In June 2026, ClickHouse Cloud moved to a new role-based access control (RBAC) system. If your organization has members or API keys with service-scoped permissions that can't be migrated automatically, you'll use a migration wizard to map those permissions to new roles. This guide explains how the new system works and how to complete the migration.
Organizations that haven't finished the migration by the deadline shown in the wizard and in your email notifications will be migrated automatically (see What happens if you don't migrate).
What's changing
The new RBAC system introduces custom role definitions and more granular access control. Instead of a fixed set of service-scoped permissions, you define roles that reveal every permission they grant, so it's clear exactly what access each role provides.
A role can combine organization, service, and database permissions. You can apply those permissions to all of your services and databases, or to a subset. For the full list of permissions and the standard roles that ship with ClickHouse Cloud, see Console roles and permissions. For instructions on creating and editing roles after you migrate, see Manage custom roles.
Most permissions map to the new model automatically. Service-scoped permissions that can't be mapped directly are what the migration wizard asks you to handle.
Complete the migration wizard
The wizard prompts you to create new roles that reflect the permissions your members and API keys hold today, then assign those roles to the right members and keys. Your progress is saved automatically, so you don't need to finish in a single session.
Open the migration wizard
From the Users and roles page, follow the migration prompt to open the wizard. You can also reach it from the migration banner shown in the console.
Create roles for unmapped permissions
The wizard lists members and API keys whose service-scoped permissions couldn't be migrated automatically. Create new roles that match the access these members and keys need. See Manage custom roles for details on how permissions are scoped.
Assign roles to every member and API key
Assign at least one new role to each member, each pending invitation, and each API key. Any member, invitation, or key left with a blank New role column will block submission.
Keep at least one Administrator
Assign an Admin role to at least one existing member. The wizard won't let you submit without one, because your organization would otherwise lose administrative access after the migration.
Submit the migration
Once every member, invitation, and API key has a role, submit the migration. You'll be redirected to the Roles tab on success.
If you try to submit before these conditions are met, the wizard shows a message identifying what's missing — members without roles, API keys without roles, or a missing Administrator — so you can jump straight to the affected entries.
What happens if you don't migrate
Complete the migration yourself whenever possible so your roles reflect your intended access model. If your organization doesn't finish the migration in time, ClickHouse runs an automated migration in the following weeks.
The automated migration creates one custom role per user and one custom role per API key, each mirroring that user's or key's existing permissions. This preserves everyone's current access level, so no member or key loses access. You can review and consolidate these roles afterward on the Roles tab.
After you migrate
Review your OpenAPI and Terraform configurations to keep them compatible with the new roles system. Automation that references the old roles may need to be updated.
The Query Endpoints role transitions to the Basic service API reader role. Update any integrations that depend on the previous role name.
For guidance on managing roles going forward, see Manage custom roles and Cloud access management.
