Migrate to Starburst access control#

This page describes how to move to Starburst access control from the following setups:

Upgrade from the private preview#

If you used Control Plane catalogs in the private preview, make the following changes when you upgrade.

In the Control Plane config.properties file:

  • Remove the catalogs.enabled and control-plane.access-control.enabled properties, and set control-plane.enabled=true instead. If a removed property is still set, the Control Plane fails to start with an error such as Configuration property 'catalogs.enabled' was not used.

  • The following properties now require control-plane.enabled=true. If you set one of them without it, the Control Plane fails to start:

    • ai-models.enabled

    • background-work.enabled

    • context-studio.enabled

    • data-products.enabled

    • icehouse-tasks.enabled

    • mcp.enabled

    • resource-groups.enabled

    • starburst.users.provisioning.type

On each cluster, remove the catalog.management=LIVE property, and run the cluster in managed mode instead, with the deployment.mode=MANAGED and deployment.manager.uri properties. LIVE is no longer a valid value.

After the upgrade:

  • Catalogs that existed in the Control Plane are delegated and owned by the accountadmin role. Starburst access control doesn’t control access to them. Load built-in access control alongside Starburst access control, as described in Configuration, or switch the catalogs to governed.

  • The Control Plane has a built-in catalog named starburst, which appears in the catalog list. You can’t create, rename, alter, or drop a catalog with that name.

Move from built-in access control#

You move from built-in access control to Starburst access control one catalog at a time. Delegated catalogs keep using built-in access control while you set up Starburst access control, and you switch each catalog to governed when its Starburst access control rules are ready.

  1. Enable Starburst access control, and load built-in access control alongside it on each coordinator. For more information, see Configuration.

  2. Grant location privileges in Starburst access control to the roles that create schemas or tables with an explicit location. Starburst access control checks storage locations in every catalog, including delegated catalogs, and built-in access control location grants stop applying. If the starburst.access-control.location.enabled property is set, the cluster ignores it and logs a warning. For more information, see Privileges.

  3. Make sure that your catalogs are delegated, so that their built-in access control grants keep working. New catalogs are governed by default, and SQL CREATE CATALOG statements always create governed catalogs. Switch these catalogs to delegated.

  4. Update the role settings of your clients, as described in Role settings.

  5. Recreate the roles, privileges, column masks, and row filters of each catalog in Starburst access control. No tool copies them for you, and the two systems use different privilege names.

  6. Switch the catalogs to governed one at a time.

  7. Assign a Starburst access control owner to the objects that were created while each catalog was delegated, as described in When you switch a catalog.

Role settings#

With Starburst access control enabled, the system role of a session is a Starburst access control role. Clients that select a built-in access control role as a system role stop working:

Client setting

Result with Starburst access control

Use instead

SET ROLE with a built-in access control role

Fails with Role '...' does not exist

The $biac-role extra credential

SET ROLE ... IN "$biac"

Fails with Catalog '$biac' not found

The $biac-role extra credential

X-Trino-Role: system=ROLE{name} with a built-in access control role

Fails with HTTP 403

The $biac-role extra credential

X-Trino-Role: system=ALL or system=NONE

Fails with HTTP 400

One Starburst access control role

By default, users have the privileges of all their built-in access control roles in delegated catalogs. For more information about the $biac-role extra credential, see Compare with built-in access control.

When you switch a catalog#

  • The change applies to the next statement, including on open connections.

  • No grants are deleted. Built-in access control keeps its grants, and they apply again if you switch the catalog back to delegated.

  • Schemas, tables, and views created while the catalog was delegated have no Starburst access control owner. Starburst access control treats the owner of the schema, or else the owner of the catalog, as their owner. To give one of these objects a Starburst access control owner, run ALTER ... SET AUTHORIZATION ROLE.

  • SECURITY DEFINER views created while the catalog was delegated fail until you give them a Starburst access control owner. For more information, see View privileges.

Built-in access control stores grants and ownership by catalog name:

  • If you drop a delegated catalog and create a catalog with the same name, the new catalog gets the built-in access control grants of the old one.

  • If you rename a delegated catalog, its built-in access control grants stay with the old name and don’t apply to the renamed catalog.

Roll back#

To roll back a catalog, switch it back to delegated. Its built-in access control grants apply again from the next statement.