Role
Role represents a Postgres role within a Branch.
Role object
Role represents a Postgres role within a Branch.
- namestring
Output only. The full resource path of the role. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}
- parentstringOutput only
The Branch where this Role exists. Format: projects/{project_id}/branches/{branch_id}
- create_timestringOutput only
- update_timestringOutput only
- specobjectInput only
The spec contains the role configuration, including identity type, authentication method, and role attributes.
Show child attributesHide child attributes
- membership_rolesarray of string
An enum value for a standard role that this role is a member of.
MEMBERSHIP_ROLE_UNSPECIFIEDDATABRICKS_SUPERUSER
- identity_typestring
The type of role. When specifying a managed-identity, the chosen role_id must be a valid:
- application ID for SERVICE_PRINCIPAL
- user email for USER
- group name for GROUP
IDENTITY_TYPE_UNSPECIFIEDUSERSERVICE_PRINCIPALGROUP
- attributesobject
The desired API-exposed Postgres role attribute to associate with the role. Optional.
Show child attributesHide child attributes
- createdbboolean
- createroleboolean
- bypassrlsboolean
- auth_methodstring
Controls how the Postgres role authenticates when a client opens a database connection. Supported values:
- LAKEBASE_OAUTH_V1: the role authenticates by presenting a Databricks
OAuth access token derived from the backing managed identity (the
<Databricks> user, service principal, or group named by the role's
postgres_role). No static password exists for roles using this method. - PG_PASSWORD_SCRAM_SHA_256: the role authenticates with a Postgres password verified server-side using the SCRAM-SHA-256 mechanism. Lakebase generates a password for the role.
- NO_LOGIN: the role cannot open a Postgres session at all. Useful for roles that exist only to own objects or to aggregate privileges that are then granted to other, loginable roles.
If auth_method is left unspecified, a meaningful authentication method is derived from the identity_type:
- For the managed identities, OAUTH is used.
- For the regular postgres roles, authentication based on postgres passwords is used.
NOTE: for the <Databricks> identity type GROUP, LAKEBASE_OAUTH_V1 is the default auth method (group can login as well).
AUTH_METHOD_UNSPECIFIEDNO_LOGINPG_PASSWORD_SCRAM_SHA_256LAKEBASE_OAUTH_V1
- LAKEBASE_OAUTH_V1: the role authenticates by presenting a Databricks
OAuth access token derived from the backing managed identity (the
<Databricks> user, service principal, or group named by the role's
- postgres_rolestring
The name of the Postgres role.
This expects a valid Postgres identifier as specified in the link below. https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
Required when creating the Role.
If you wish to create a Postgres Role backed by a managed <Databricks> identity, then postgres_role must be one of the following:
1. user email for IdentityType.USER
2. app ID for IdentityType.SERVICE_PRINCIPAL
2. group name for IdentityType.GROUP
- statusobjectOutput only
Current status of the role, including its identity type, authentication method, and role attributes.
Show child attributesHide child attributes
- membership_rolesarray of string
An enum value for a standard role that this role is a member of.
MEMBERSHIP_ROLE_UNSPECIFIEDDATABRICKS_SUPERUSER
- identity_typestring
The type of the role.
IDENTITY_TYPE_UNSPECIFIEDUSERSERVICE_PRINCIPALGROUP
- attributesobject
The PG role attributes associated with the role.
Show child attributesHide child attributes
- createdbboolean
- createroleboolean
- bypassrlsboolean
- auth_methodstring
How the role is authenticated when connecting to Postgres.
AUTH_METHOD_UNSPECIFIEDNO_LOGINPG_PASSWORD_SCRAM_SHA_256LAKEBASE_OAUTH_V1
- postgres_rolestring
The name of the Postgres role.
- role_idstringOutput only
Part of the resource name.
- role_idstringOutput only
The part of the name, chosen by the user when the resource was created.
Get a Postgres Role for a Branch GA
GET
Retrieves information about the specified Postgres role, including its authentication method and permissions.
API scopes: postgres
Parameters
- namestringRequiredpath
The full resource path of the role to retrieve. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}
Response
Returns the Role object.
List Postgres Roles for a Branch GA
GET
Returns a paginated list of Postgres roles in the branch.
API scopes: postgres
Parameters
- parentstringRequiredpath
The Branch that owns this collection of roles. Format: projects/{project_id}/branches/{branch_id}
- page_tokenstringquery
Page token from a previous response. If not provided, returns the first page.
- page_sizeint32query
Upper bound for items returned. Cannot be negative.
Response
Returns a list of Role objects.
Create a Postgres Role for a Branch GA
POST
Creates a new Postgres role in the branch.
API scopes: postgres
Parameters
- parentstringRequiredpath
The Branch where this Role is created. Format: projects/{project_id}/branches/{branch_id}
- role_idstringquery
The ID to use for the Role, which will become the final component of the role's resource name. This ID becomes the role in Postgres.
This value should be 4-63 characters, and valid characters are lowercase letters, numbers, and hyphens, as defined by RFC 1123.
If role_id is not specified in the request, it is generated automatically.
- replace_existingbooleanInput onlyquery
If true, update the role if it already exists instead of returning an error.
When the role already exists, the provided
rolespec fully replaces the existing one:membership_rolesis overwritten, not merged. Leavingmembership_rolesempty clears all of the role's existing memberships, includingDATABRICKS_SUPERUSER. Always send the complete desired list of memberships when using this field.
Request body
The desired specification of a Role.
- namestring
Output only. The full resource path of the role. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}
- specobjectInput only
The spec contains the role configuration, including identity type, authentication method, and role attributes.
Show child attributesHide child attributes
- membership_rolesarray of string
An enum value for a standard role that this role is a member of.
MEMBERSHIP_ROLE_UNSPECIFIEDDATABRICKS_SUPERUSER
- identity_typestring
The type of role. When specifying a managed-identity, the chosen role_id must be a valid:
- application ID for SERVICE_PRINCIPAL
- user email for USER
- group name for GROUP
IDENTITY_TYPE_UNSPECIFIEDUSERSERVICE_PRINCIPALGROUP
- attributesobject
The desired API-exposed Postgres role attribute to associate with the role. Optional.
Show child attributesHide child attributes
- createdbboolean
- createroleboolean
- bypassrlsboolean
- auth_methodstring
Controls how the Postgres role authenticates when a client opens a database connection. Supported values:
- LAKEBASE_OAUTH_V1: the role authenticates by presenting a Databricks
OAuth access token derived from the backing managed identity (the
<Databricks> user, service principal, or group named by the role's
postgres_role). No static password exists for roles using this method. - PG_PASSWORD_SCRAM_SHA_256: the role authenticates with a Postgres password verified server-side using the SCRAM-SHA-256 mechanism. Lakebase generates a password for the role.
- NO_LOGIN: the role cannot open a Postgres session at all. Useful for roles that exist only to own objects or to aggregate privileges that are then granted to other, loginable roles.
If auth_method is left unspecified, a meaningful authentication method is derived from the identity_type:
- For the managed identities, OAUTH is used.
- For the regular postgres roles, authentication based on postgres passwords is used.
NOTE: for the <Databricks> identity type GROUP, LAKEBASE_OAUTH_V1 is the default auth method (group can login as well).
AUTH_METHOD_UNSPECIFIEDNO_LOGINPG_PASSWORD_SCRAM_SHA_256LAKEBASE_OAUTH_V1
- LAKEBASE_OAUTH_V1: the role authenticates by presenting a Databricks
OAuth access token derived from the backing managed identity (the
<Databricks> user, service principal, or group named by the role's
- postgres_rolestring
The name of the Postgres role.
This expects a valid Postgres identifier as specified in the link below. https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
Required when creating the Role.
If you wish to create a Postgres Role backed by a managed <Databricks> identity, then postgres_role must be one of the following:
1. user email for IdentityType.USER
2. app ID for IdentityType.SERVICE_PRINCIPAL
2. group name for IdentityType.GROUP
Response
- namestring
The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the
nameshould be a resource name ending withoperations/{unique_id}.
- metadataobject
Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.
- doneboolean
If the value is
false, it means the operation is still in progress. Iftrue, the operation is completed, and eithererrororresponseis available.
- errorobject
The error result of the operation in case of failure or cancellation.
Show child attributesHide child attributes
- error_codestring
Error codes returned by Databricks APIs to indicate specific failure conditions.
Show 81 possible values
UNKNOWNINTERNAL_ERRORTEMPORARILY_UNAVAILABLEIO_ERRORBAD_REQUESTSERVICE_UNDER_MAINTENANCEWORKSPACE_TEMPORARILY_UNAVAILABLEDEADLINE_EXCEEDEDCANCELLEDRESOURCE_EXHAUSTEDABORTEDNOT_FOUNDALREADY_EXISTSUNAUTHENTICATEDUNAVAILABLEINVALID_PARAMETER_VALUEENDPOINT_NOT_FOUNDMALFORMED_REQUESTINVALID_STATEPERMISSION_DENIEDFEATURE_DISABLEDCUSTOMER_UNAUTHORIZEDREQUEST_LIMIT_EXCEEDEDRESOURCE_CONFLICTUNPARSEABLE_HTTP_ERRORNOT_IMPLEMENTEDDATA_LOSSINVALID_STATE_TRANSITIONCOULD_NOT_ACQUIRE_LOCKRESOURCE_ALREADY_EXISTSRESOURCE_DOES_NOT_EXISTQUOTA_EXCEEDEDMAX_BLOCK_SIZE_EXCEEDEDMAX_READ_SIZE_EXCEEDEDPARTIAL_DELETEMAX_LIST_SIZE_EXCEEDEDDRY_RUN_FAILEDRESOURCE_LIMIT_EXCEEDEDDIRECTORY_NOT_EMPTYDIRECTORY_PROTECTEDMAX_NOTEBOOK_SIZE_EXCEEDEDMAX_CHILD_NODE_SIZE_EXCEEDEDSEARCH_QUERY_TOO_LONGSEARCH_QUERY_TOO_SHORTMANAGED_RESOURCE_GROUP_DOES_NOT_EXISTPERMISSION_NOT_PROPAGATEDDEPLOYMENT_TIMEOUTGIT_CONFLICTGIT_UNKNOWN_REFGIT_SENSITIVE_TOKEN_DETECTEDGIT_URL_NOT_ON_ALLOW_LISTGIT_REMOTE_ERRORPROJECTS_OPERATION_TIMEOUTIPYNB_FILE_IN_REPOINSECURE_PARTNER_RESPONSEMALFORMED_PARTNER_RESPONSEMETASTORE_DOES_NOT_EXISTDAC_DOES_NOT_EXISTCATALOG_DOES_NOT_EXISTSCHEMA_DOES_NOT_EXISTTABLE_DOES_NOT_EXISTSHARE_DOES_NOT_EXISTRECIPIENT_DOES_NOT_EXISTSTORAGE_CREDENTIAL_DOES_NOT_EXISTEXTERNAL_LOCATION_DOES_NOT_EXISTPRINCIPAL_DOES_NOT_EXISTPROVIDER_DOES_NOT_EXISTMETASTORE_ALREADY_EXISTSDAC_ALREADY_EXISTSCATALOG_ALREADY_EXISTSSCHEMA_ALREADY_EXISTSTABLE_ALREADY_EXISTSSHARE_ALREADY_EXISTSRECIPIENT_ALREADY_EXISTSSTORAGE_CREDENTIAL_ALREADY_EXISTSEXTERNAL_LOCATION_ALREADY_EXISTSPROVIDER_ALREADY_EXISTSCATALOG_NOT_EMPTYSCHEMA_NOT_EMPTYMETASTORE_NOT_EMPTYPROVIDER_SHARE_NOT_ACCESSIBLE
- messagestring
- stack_tracestring
- detailsarray of object
- responseobject
The normal, successful response of the operation.
Update a Postgres Role for a Branch GA
PATCH
Update a role for a branch.
API scopes: postgres
Parameters
- namestringRequiredpath
Output only. The full resource path of the role. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}
- update_maskstringRequiredquery
The list of fields to update.
Request body
The Postgres Role to update.
The role's name field is used to identify the role to update.
Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}
- specobjectInput only
The spec contains the role configuration, including identity type, authentication method, and role attributes.
Show child attributesHide child attributes
- membership_rolesarray of string
An enum value for a standard role that this role is a member of.
MEMBERSHIP_ROLE_UNSPECIFIEDDATABRICKS_SUPERUSER
- identity_typestring
The type of role. When specifying a managed-identity, the chosen role_id must be a valid:
- application ID for SERVICE_PRINCIPAL
- user email for USER
- group name for GROUP
IDENTITY_TYPE_UNSPECIFIEDUSERSERVICE_PRINCIPALGROUP
- attributesobject
The desired API-exposed Postgres role attribute to associate with the role. Optional.
Show child attributesHide child attributes
- createdbboolean
- createroleboolean
- bypassrlsboolean
- auth_methodstring
Controls how the Postgres role authenticates when a client opens a database connection. Supported values:
- LAKEBASE_OAUTH_V1: the role authenticates by presenting a Databricks
OAuth access token derived from the backing managed identity (the
<Databricks> user, service principal, or group named by the role's
postgres_role). No static password exists for roles using this method. - PG_PASSWORD_SCRAM_SHA_256: the role authenticates with a Postgres password verified server-side using the SCRAM-SHA-256 mechanism. Lakebase generates a password for the role.
- NO_LOGIN: the role cannot open a Postgres session at all. Useful for roles that exist only to own objects or to aggregate privileges that are then granted to other, loginable roles.
If auth_method is left unspecified, a meaningful authentication method is derived from the identity_type:
- For the managed identities, OAUTH is used.
- For the regular postgres roles, authentication based on postgres passwords is used.
NOTE: for the <Databricks> identity type GROUP, LAKEBASE_OAUTH_V1 is the default auth method (group can login as well).
AUTH_METHOD_UNSPECIFIEDNO_LOGINPG_PASSWORD_SCRAM_SHA_256LAKEBASE_OAUTH_V1
- LAKEBASE_OAUTH_V1: the role authenticates by presenting a Databricks
OAuth access token derived from the backing managed identity (the
<Databricks> user, service principal, or group named by the role's
- postgres_rolestring
The name of the Postgres role.
This expects a valid Postgres identifier as specified in the link below. https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
Required when creating the Role.
If you wish to create a Postgres Role backed by a managed <Databricks> identity, then postgres_role must be one of the following:
1. user email for IdentityType.USER
2. app ID for IdentityType.SERVICE_PRINCIPAL
2. group name for IdentityType.GROUP
Response
- namestring
The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the
nameshould be a resource name ending withoperations/{unique_id}.
- metadataobject
Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.
- doneboolean
If the value is
false, it means the operation is still in progress. Iftrue, the operation is completed, and eithererrororresponseis available.
- errorobject
The error result of the operation in case of failure or cancellation.
Show child attributesHide child attributes
- error_codestring
Error codes returned by Databricks APIs to indicate specific failure conditions.
Show 81 possible values
UNKNOWNINTERNAL_ERRORTEMPORARILY_UNAVAILABLEIO_ERRORBAD_REQUESTSERVICE_UNDER_MAINTENANCEWORKSPACE_TEMPORARILY_UNAVAILABLEDEADLINE_EXCEEDEDCANCELLEDRESOURCE_EXHAUSTEDABORTEDNOT_FOUNDALREADY_EXISTSUNAUTHENTICATEDUNAVAILABLEINVALID_PARAMETER_VALUEENDPOINT_NOT_FOUNDMALFORMED_REQUESTINVALID_STATEPERMISSION_DENIEDFEATURE_DISABLEDCUSTOMER_UNAUTHORIZEDREQUEST_LIMIT_EXCEEDEDRESOURCE_CONFLICTUNPARSEABLE_HTTP_ERRORNOT_IMPLEMENTEDDATA_LOSSINVALID_STATE_TRANSITIONCOULD_NOT_ACQUIRE_LOCKRESOURCE_ALREADY_EXISTSRESOURCE_DOES_NOT_EXISTQUOTA_EXCEEDEDMAX_BLOCK_SIZE_EXCEEDEDMAX_READ_SIZE_EXCEEDEDPARTIAL_DELETEMAX_LIST_SIZE_EXCEEDEDDRY_RUN_FAILEDRESOURCE_LIMIT_EXCEEDEDDIRECTORY_NOT_EMPTYDIRECTORY_PROTECTEDMAX_NOTEBOOK_SIZE_EXCEEDEDMAX_CHILD_NODE_SIZE_EXCEEDEDSEARCH_QUERY_TOO_LONGSEARCH_QUERY_TOO_SHORTMANAGED_RESOURCE_GROUP_DOES_NOT_EXISTPERMISSION_NOT_PROPAGATEDDEPLOYMENT_TIMEOUTGIT_CONFLICTGIT_UNKNOWN_REFGIT_SENSITIVE_TOKEN_DETECTEDGIT_URL_NOT_ON_ALLOW_LISTGIT_REMOTE_ERRORPROJECTS_OPERATION_TIMEOUTIPYNB_FILE_IN_REPOINSECURE_PARTNER_RESPONSEMALFORMED_PARTNER_RESPONSEMETASTORE_DOES_NOT_EXISTDAC_DOES_NOT_EXISTCATALOG_DOES_NOT_EXISTSCHEMA_DOES_NOT_EXISTTABLE_DOES_NOT_EXISTSHARE_DOES_NOT_EXISTRECIPIENT_DOES_NOT_EXISTSTORAGE_CREDENTIAL_DOES_NOT_EXISTEXTERNAL_LOCATION_DOES_NOT_EXISTPRINCIPAL_DOES_NOT_EXISTPROVIDER_DOES_NOT_EXISTMETASTORE_ALREADY_EXISTSDAC_ALREADY_EXISTSCATALOG_ALREADY_EXISTSSCHEMA_ALREADY_EXISTSTABLE_ALREADY_EXISTSSHARE_ALREADY_EXISTSRECIPIENT_ALREADY_EXISTSSTORAGE_CREDENTIAL_ALREADY_EXISTSEXTERNAL_LOCATION_ALREADY_EXISTSPROVIDER_ALREADY_EXISTSCATALOG_NOT_EMPTYSCHEMA_NOT_EMPTYMETASTORE_NOT_EMPTYPROVIDER_SHARE_NOT_ACCESSIBLE
- messagestring
- stack_tracestring
- detailsarray of object
- responseobject
The normal, successful response of the operation.
Delete a Postgres Role from a Branch GA
DELETE
Deletes the specified Postgres role.
API scopes: postgres
Parameters
- namestringRequiredpath
The full resource path of the role to delete. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}
- reassign_owned_tostringquery
Reassign objects. If this is set, all objects owned by the role are reassigned to the role specified in this parameter.
NOTE: setting this requires spinning up a compute to succeed, since it involves running SQL queries.
Response
- namestring
The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the
nameshould be a resource name ending withoperations/{unique_id}.
- metadataobject
Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.
- doneboolean
If the value is
false, it means the operation is still in progress. Iftrue, the operation is completed, and eithererrororresponseis available.
- errorobject
The error result of the operation in case of failure or cancellation.
Show child attributesHide child attributes
- error_codestring
Error codes returned by Databricks APIs to indicate specific failure conditions.
Show 81 possible values
UNKNOWNINTERNAL_ERRORTEMPORARILY_UNAVAILABLEIO_ERRORBAD_REQUESTSERVICE_UNDER_MAINTENANCEWORKSPACE_TEMPORARILY_UNAVAILABLEDEADLINE_EXCEEDEDCANCELLEDRESOURCE_EXHAUSTEDABORTEDNOT_FOUNDALREADY_EXISTSUNAUTHENTICATEDUNAVAILABLEINVALID_PARAMETER_VALUEENDPOINT_NOT_FOUNDMALFORMED_REQUESTINVALID_STATEPERMISSION_DENIEDFEATURE_DISABLEDCUSTOMER_UNAUTHORIZEDREQUEST_LIMIT_EXCEEDEDRESOURCE_CONFLICTUNPARSEABLE_HTTP_ERRORNOT_IMPLEMENTEDDATA_LOSSINVALID_STATE_TRANSITIONCOULD_NOT_ACQUIRE_LOCKRESOURCE_ALREADY_EXISTSRESOURCE_DOES_NOT_EXISTQUOTA_EXCEEDEDMAX_BLOCK_SIZE_EXCEEDEDMAX_READ_SIZE_EXCEEDEDPARTIAL_DELETEMAX_LIST_SIZE_EXCEEDEDDRY_RUN_FAILEDRESOURCE_LIMIT_EXCEEDEDDIRECTORY_NOT_EMPTYDIRECTORY_PROTECTEDMAX_NOTEBOOK_SIZE_EXCEEDEDMAX_CHILD_NODE_SIZE_EXCEEDEDSEARCH_QUERY_TOO_LONGSEARCH_QUERY_TOO_SHORTMANAGED_RESOURCE_GROUP_DOES_NOT_EXISTPERMISSION_NOT_PROPAGATEDDEPLOYMENT_TIMEOUTGIT_CONFLICTGIT_UNKNOWN_REFGIT_SENSITIVE_TOKEN_DETECTEDGIT_URL_NOT_ON_ALLOW_LISTGIT_REMOTE_ERRORPROJECTS_OPERATION_TIMEOUTIPYNB_FILE_IN_REPOINSECURE_PARTNER_RESPONSEMALFORMED_PARTNER_RESPONSEMETASTORE_DOES_NOT_EXISTDAC_DOES_NOT_EXISTCATALOG_DOES_NOT_EXISTSCHEMA_DOES_NOT_EXISTTABLE_DOES_NOT_EXISTSHARE_DOES_NOT_EXISTRECIPIENT_DOES_NOT_EXISTSTORAGE_CREDENTIAL_DOES_NOT_EXISTEXTERNAL_LOCATION_DOES_NOT_EXISTPRINCIPAL_DOES_NOT_EXISTPROVIDER_DOES_NOT_EXISTMETASTORE_ALREADY_EXISTSDAC_ALREADY_EXISTSCATALOG_ALREADY_EXISTSSCHEMA_ALREADY_EXISTSTABLE_ALREADY_EXISTSSHARE_ALREADY_EXISTSRECIPIENT_ALREADY_EXISTSSTORAGE_CREDENTIAL_ALREADY_EXISTSEXTERNAL_LOCATION_ALREADY_EXISTSPROVIDER_ALREADY_EXISTSCATALOG_NOT_EMPTYSCHEMA_NOT_EMPTYMETASTORE_NOT_EMPTYPROVIDER_SHARE_NOT_ACCESSIBLE
- messagestring
- stack_tracestring
- detailsarray of object
- responseobject
The normal, successful response of the operation.