Skip to main content
Last updated on

Create Postgres roles

info

Lakebase Autoscaling is available in the following regions: us-east-1, us-east-2, us-west-2, ca-central-1, sa-east-1, eu-central-1, eu-west-1, eu-west-2, ap-south-1, ap-southeast-1, ap-southeast-2.

Lakebase Autoscaling is the latest version of Lakebase, with autoscaling compute, scale-to-zero, branching, and instant restore. If you are a Lakebase Provisioned user, see Lakebase Provisioned.

When you create a project, Lakebase creates several Postgres roles in the project:

  • A Postgres role for the project owner's Databricks identity (for example, user@databricks.com), which owns the default databricks_postgres database
  • A databricks_superuser administrative role

Both of these roles are visible in the Roles & Databases tab when you first open your project.

The databricks_postgres database is created so you can connect and try out Lakebase immediately after project creation.

Several system-managed roles are also created. These are internal roles used by Databricks services for management, monitoring, and data operations.

note

Postgres roles control database access (who can query data). For project permissions (who can manage infrastructure), see Project permissions. For a tutorial on setting up both, see Tutorial: Grant project and database access to a new user.

See Pre-created roles and System roles.

Create Postgres roles​

Lakebase supports two types of Postgres roles for database access:

  • OAuth roles for Databricks identities: Create these using the Lakebase UI, the databricks_auth extension with SQL, or the Python SDK and REST API. Enables Databricks identities (users, service principals, and groups) to connect using OAuth tokens.
  • Native Postgres password roles: Create these using the Lakebase UI, SQL, or the Python SDK and REST API. Use any valid role name with password authentication.

For guidance on choosing the type of role to use, see Authentication overview. Each is designed for different use cases.

Create an OAuth role for Databricks identities​

To allow Databricks identities (users, service principals, or groups) to connect using OAuth tokens, create an OAuth role using the Lakebase UI, the databricks_auth extension with SQL, or the REST API.

For detailed instructions on obtaining OAuth tokens, see Obtain an OAuth token in a user-to-machine flow and Obtain an OAuth token in a machine-to-machine flow.

  1. In Roles & Databases > Add role > OAuth tab, select the user, service principal, or group to grant database access to.
  2. After creating the role, grant appropriate database privileges. Learn how: Manage permissions

Add role — OAuth tab

Group-based authentication​

When you create a Postgres role for a Databricks group, you enable group-based authentication. This allows any member of the Databricks group to authenticate to Postgres using the group's role, simplifying permission management.

How it works:

  1. Create a Postgres role for a Databricks group.
  2. Grant database permissions to the group role in Postgres. See Manage permissions.
  3. Any direct or indirect member (user or service principal) of the Databricks group can connect to Postgres using their individual OAuth token.
  4. When connecting, the member authenticates as the group role and inherits all permissions granted to that role.

Authentication flow:

When a group member connects, they specify the group's Postgres role name as the username and their own OAuth token as the password:

Bash
export PGPASSWORD='<OAuth token of a group member>'
export GROUP_ROLE_NAME='<pg-case-sensitive-group-role-name>'

psql -h $HOSTNAME -p 5432 -d databricks_postgres -U $GROUP_ROLE_NAME

Important considerations:

  • Group membership validation: Group membership is validated only at authentication time. If a member is removed from the Databricks group after establishing a connection, the connection remains active. New connection attempts from removed members are rejected.
  • Workspace scoping: Only groups assigned to the same Databricks workspace as the project are supported for group-based authentication. To learn how to assign groups to a workspace, see Manage groups.
  • Case sensitivity: The group name used in databricks_create_role() must match the group name exactly as it appears in your Databricks workspace, including case.
  • Permission management: Managing permissions at the group level in Postgres is more efficient than managing individual user permissions. When you grant permissions to the group role, all current and future group members inherit those permissions automatically.
  • Identity renaming: If a user's email or group display name changes in Databricks, authentication and existing database grants will break. Drop the old role, create a new one with the updated name, and update connection strings and grants.
note

Role names cannot exceed 63 characters, and some names are not permitted. Learn more: Manage roles

Create a native Postgres password role​

Password connections can be disabled at the project or compute level. See Block password connections.

  1. In Roles & Databases > Add role > Password tab, enter a role name and optionally grant databricks_superuser or system attributes (CREATEDB, CREATEROLE, BYPASSRLS).
  2. Copy the generated password and provide it securely to the user. It is not shown again.

Add role — Password tab

View Postgres roles​

To view all Postgres roles in your project, navigate to your branch's Roles & Databases tab in the Lakebase App. All roles created in the branch, with the exception of System roles, are listed. The Auth type column indicates whether each role uses OAuth or Password authentication.

Roles list

Update a role​

To update a role's attributes in the UI, select Edit role from the role menu in the Roles & Databases tab.

Use the API to update a role's system roles or attributes. Use update_mask as a query parameter to specify which fields to change; only the masked fields are modified.

note

To get a role's resource name for use in update and delete calls, use the list roles endpoint. Role resource names use a system-generated identifier (for example, rol-xxxx-xxxxxxxxxx), not the postgres_role value supplied at creation.

Bash
curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx?update_mask=spec.membership_roles%2Cspec.attributes.createdb" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx",
    "spec": {
      "membership_roles": ["DATABRICKS_SUPERUSER"],
      "attributes": { "createdb": true }
    }
  }' | jq

To remove databricks_superuser, pass an empty array: "membership_roles": [].

Drop a Postgres role​

You can drop both Databricks identity-based roles and native Postgres password roles.

Deleting a role is a permanent action that cannot be undone. To delete a role that owns a database you must specify the role to reassign the owned objects to. Otherwise the database must be deleted manually before deleting the role that owns the database.

To delete any Postgres role using the UI:

  1. Navigate to your branch's Roles & Databases tab in the Lakebase App.
  2. Select Delete role from the role menu and confirm the deletion.

Pre-created roles​

After a project is created, Databricks automatically creates Postgres roles for project administration and getting started.

Role

Description

Inherited privileges

<project_owner_role>

The Databricks identity of the project creator (for example, my.user@databricks.com). This role owns the default databricks_postgres database and can log in and administer the project.

Member of databricks_superuser

databricks_superuser

An internal administrative role. Used to configure and manage access across the project. This role is granted broad privileges.

Inherits from pg_read_all_data, pg_write_all_data, and pg_monitor.

Learn more about these roles' specific capabilities and privileges: Pre-created role capabilities

System roles created by Databricks​

Databricks creates the following system roles required for internal services. You can view these roles by issuing a \du command from psql or the Lakebase SQL Editor.

Role

Purpose

cloud_admin

Superuser role used for cloud infrastructure management

databricks_control_plane

Superuser role used by internal Databricks components for management operations

databricks_monitor

Used by internal metrics collection services

databricks_replicator

Used for database replication operations

databricks_writer_<dbid>

Per-database role used to create and manage synced tables

databricks_reader_<dbid>

Per-database role used to read tables registered in Unity Catalog

databricks_gateway

Used for internal connections for managed data serving services

To learn how roles, privileges, and role memberships work in Postgres, use the following resources in the Postgres documentation:

Next steps​