# Create

Launch stage: GA

`POST /api/2.0/postgres/{parent=projects/*/branches/*}/roles`

Creates a new Postgres role in the branch.

API scopes: postgres

## Path parameters

- `parent` (string, optional)
  The Branch where this Role is created.
   Format: projects/{project_id}/branches/{branch_id}

## Query parameters

- `role_id` (string, optional)
  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_existing` (boolean, optional)
  If true, update the role if it already exists instead of returning an
   error.
  
   When the role already exists, the provided `role` spec fully replaces the
   existing one: `membership_roles` is overwritten, not merged. Leaving
   `membership_roles` empty clears all of the role's existing memberships,
   including `DATABRICKS_SUPERUSER`. Always send the complete desired list of
   memberships when using this field.

## Request body

- `role` (object, optional)
  The desired specification of a Role.
  - `name` (string, optional)
    Output only. The full resource path of the role.
     Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}
  - `parent` (string, optional)
    The Branch where this Role exists.
     Format: projects/{project_id}/branches/{branch_id}
  - `create_time` (string, optional)
  - `update_time` (string, optional)
  - `spec` (object, optional)
    The spec contains the role configuration, including identity type, authentication method, and role attributes.
    - `membership_roles` (array of string, optional)
      An enum value for a standard role that this role is a member of.
      Possible values: `MEMBERSHIP_ROLE_UNSPECIFIED`, `DATABRICKS_SUPERUSER`
    - `identity_type` (string, optional)
      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
      Possible values: `IDENTITY_TYPE_UNSPECIFIED`, `USER`, `SERVICE_PRINCIPAL`, `GROUP`
    - `attributes` (object, optional)
      The desired API-exposed Postgres role attribute to associate with the role. Optional.
      - `createdb` (boolean, optional)
      - `createrole` (boolean, optional)
      - `bypassrls` (boolean, optional)
    - `auth_method` (string, optional)
      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).
      Possible values: `AUTH_METHOD_UNSPECIFIED`, `NO_LOGIN`, `PG_PASSWORD_SCRAM_SHA_256`, `LAKEBASE_OAUTH_V1`
    - `postgres_role` (string, optional)
      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
  - `status` (object, optional)
    Current status of the role, including its identity type, authentication method, and role attributes.
    - `membership_roles` (array of string, optional)
      An enum value for a standard role that this role is a member of.
      Possible values: `MEMBERSHIP_ROLE_UNSPECIFIED`, `DATABRICKS_SUPERUSER`
    - `identity_type` (string, optional)
      The type of the role.
      Possible values: `IDENTITY_TYPE_UNSPECIFIED`, `USER`, `SERVICE_PRINCIPAL`, `GROUP`
    - `attributes` (object, optional)
      The PG role attributes associated with the role.
      - `createdb` (boolean, optional)
      - `createrole` (boolean, optional)
      - `bypassrls` (boolean, optional)
    - `auth_method` (string, optional)
      Possible values: `AUTH_METHOD_UNSPECIFIED`, `NO_LOGIN`, `PG_PASSWORD_SCRAM_SHA_256`, `LAKEBASE_OAUTH_V1`
    - `postgres_role` (string, optional)
      The name of the Postgres role.
    - `role_id` (string, optional)
      Part of the resource name.
  - `role_id` (string, optional)
    The part of the name, chosen by the user when the resource was created.

## Returns

- `name` (string, optional)
  The server-assigned name, which is only unique within the same service that
   originally returns it. If you use the default HTTP mapping, the
   `name` should be a resource name ending with `operations/{unique_id}`.
- `metadata` (object, optional)
  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.
- `done` (boolean, optional)
  If the value is `false`, it means the operation is still in progress.
   If `true`, the operation is completed, and either `error` or `response` is
   available.
- `error` (object, required)
  The error result of the operation in case of failure or cancellation.
  - `error_code` (string, optional)
    Possible values: `UNKNOWN`, `INTERNAL_ERROR`, `TEMPORARILY_UNAVAILABLE`, `IO_ERROR`, `BAD_REQUEST`, `SERVICE_UNDER_MAINTENANCE`, `WORKSPACE_TEMPORARILY_UNAVAILABLE`, `DEADLINE_EXCEEDED`, `CANCELLED`, `RESOURCE_EXHAUSTED`, `ABORTED`, `NOT_FOUND`, `ALREADY_EXISTS`, `UNAUTHENTICATED`, `UNAVAILABLE`, `INVALID_PARAMETER_VALUE`, `ENDPOINT_NOT_FOUND`, `MALFORMED_REQUEST`, `INVALID_STATE`, `PERMISSION_DENIED`, `FEATURE_DISABLED`, `CUSTOMER_UNAUTHORIZED`, `REQUEST_LIMIT_EXCEEDED`, `RESOURCE_CONFLICT`, `UNPARSEABLE_HTTP_ERROR`, `NOT_IMPLEMENTED`, `DATA_LOSS`, `INVALID_STATE_TRANSITION`, `COULD_NOT_ACQUIRE_LOCK`, `RESOURCE_ALREADY_EXISTS`, `RESOURCE_DOES_NOT_EXIST`, `QUOTA_EXCEEDED`, `MAX_BLOCK_SIZE_EXCEEDED`, `MAX_READ_SIZE_EXCEEDED`, `PARTIAL_DELETE`, `MAX_LIST_SIZE_EXCEEDED`, `DRY_RUN_FAILED`, `RESOURCE_LIMIT_EXCEEDED`, `DIRECTORY_NOT_EMPTY`, `DIRECTORY_PROTECTED`, `MAX_NOTEBOOK_SIZE_EXCEEDED`, `MAX_CHILD_NODE_SIZE_EXCEEDED`, `SEARCH_QUERY_TOO_LONG`, `SEARCH_QUERY_TOO_SHORT`, `MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST`, `PERMISSION_NOT_PROPAGATED`, `DEPLOYMENT_TIMEOUT`, `GIT_CONFLICT`, `GIT_UNKNOWN_REF`, `GIT_SENSITIVE_TOKEN_DETECTED`, `GIT_URL_NOT_ON_ALLOW_LIST`, `GIT_REMOTE_ERROR`, `PROJECTS_OPERATION_TIMEOUT`, `IPYNB_FILE_IN_REPO`, `INSECURE_PARTNER_RESPONSE`, `MALFORMED_PARTNER_RESPONSE`, `METASTORE_DOES_NOT_EXIST`, `DAC_DOES_NOT_EXIST`, `CATALOG_DOES_NOT_EXIST`, `SCHEMA_DOES_NOT_EXIST`, `TABLE_DOES_NOT_EXIST`, `SHARE_DOES_NOT_EXIST`, `RECIPIENT_DOES_NOT_EXIST`, `STORAGE_CREDENTIAL_DOES_NOT_EXIST`, `EXTERNAL_LOCATION_DOES_NOT_EXIST`, `PRINCIPAL_DOES_NOT_EXIST`, `PROVIDER_DOES_NOT_EXIST`, `METASTORE_ALREADY_EXISTS`, `DAC_ALREADY_EXISTS`, `CATALOG_ALREADY_EXISTS`, `SCHEMA_ALREADY_EXISTS`, `TABLE_ALREADY_EXISTS`, `SHARE_ALREADY_EXISTS`, `RECIPIENT_ALREADY_EXISTS`, `STORAGE_CREDENTIAL_ALREADY_EXISTS`, `EXTERNAL_LOCATION_ALREADY_EXISTS`, `PROVIDER_ALREADY_EXISTS`, `CATALOG_NOT_EMPTY`, `SCHEMA_NOT_EMPTY`, `METASTORE_NOT_EMPTY`, `PROVIDER_SHARE_NOT_ACCESSIBLE`
  - `message` (string, optional)
  - `stack_trace` (string, optional)
  - `details` (array of object, optional)
- `response` (object, required)
  The normal, successful response of the operation.

## Response

```json
{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "string",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}
```