Criar funções do Postgres

info

O dimensionamento automático do Lakebase está disponível nas seguintes regiões: 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.

O Lakebase autoscale é a versão mais recente do Lakebase, com recursos como autoscale compute, escala-to-zero, branching e instant restore. Se você é usuário de provisionamento Lakebase, consulte Provisionamento Lakebase.

Ao criar um projeto, o Lakebase cria várias funções do Postgres no projeto:

• Uma função do Postgres para a identidade do proprietário do projeto Databricks (por exemplo, user@databricks.com), que possui o banco de dados default databricks_postgres
• Uma função administrativa databricks_superuser

Ambas as funções ficam visíveis na tab Funções e Bancos de Dados quando você abre o projeto pela primeira vez.

O banco de dados databricks_postgres é criado para que você possa se conectar e experimentar o Lakebase imediatamente após a criação do projeto.

Diversas funções de gerenciamento de sistema também são criadas. Estas são funções internas utilizadas pelo serviço Databricks para gerenciamento, monitoramento e operações de dados.

nota

Os papéis do Postgres controlam o acesso ao banco de dados (quem pode consultar os dados). Para obter informações sobre permissões de projeto (quem pode gerenciar a infraestrutura), consulte Permissões de projeto. Para um tutorial sobre como configurar ambos, consulte o tutorial: Conceder acesso ao projeto e ao banco de dados a um novo usuário.

Consulte Funções pré-criadas e Funções do sistema.

Criar funções do Postgres

O Lakebase suporta dois tipos de funções do Postgres para acesso ao banco de dados:

• Funções OAuth para identidades Databricks: Crie-as usando a interface do usuário do Lakebase, a extensão databricks_auth com SQL ou o SDK Python e a API REST. Permite que identidades Databricks (usuários, entidades de serviço e grupos) se conectem usando tokens OAuth .
• Funções de senha nativas do Postgres: Crie-as usando a interface do usuário do Lakebase, SQL ou o SDK Python e a API REST. Utilize qualquer nome de função válido com autenticação por senha.

Para obter orientações sobre como escolher o tipo de função a ser usada, consulte a Visão geral da autenticação. Cada um foi projetado para diferentes casos de uso.

Criar uma função OAuth para identidades do Databricks

Para permitir que identidades Databricks (usuários, entidades de serviço ou grupos) se conectem usando tokens OAuth , crie uma função OAuth usando a interface do usuário do Lakebase, a extensão databricks_auth com SQL ou a API REST .

Para obter instruções detalhadas sobre como obter tokens OAuth , consulte Obter tokens OAuth em um fluxo de usuário para máquina e Obter tokens OAuth em um fluxo de máquina para máquina.

UI

1. Em Funções e Bancos de Dados > Adicionar função > tab OAuth , selecione o usuário, entidade de serviço ou grupo ao qual deseja conceder acesso ao banco de dados.
2. Após criar a função, conceda os privilégios de banco de dados apropriados. Aprenda como: gerenciar permissões

SQL

Pré-requisitos:

• Você deve ter permissões CREATE e CREATE ROLE no banco de dados.
• Você precisa estar autenticado como uma identidade Databricks com um token OAuth válido.
• Sessões autenticadas nativas do Postgres não podem criar funções OAuth.

1. Crie a extensão databricks_auth . Cada banco de dados Postgres deve ter sua própria extensão.

   SQL

   CREATE EXTENSION IF NOT EXISTS databricks_auth;

2. Use a função databricks_create_role para criar uma função do Postgres para a identidade do Databricks:

   SQL

   SELECT databricks_create_role('identity_name', 'identity_type');

   Para um usuário do Databricks:

   SQL

   SELECT databricks_create_role('myuser@databricks.com', 'USER');

   Para uma entidade de serviço Databricks:

   SQL

   SELECT databricks_create_role('8c01cfb1-62c9-4a09-88a8-e195f4b01b08', 'SERVICE_PRINCIPAL');

   Para um grupo Databricks:

   SQL

   SELECT databricks_create_role('My Group Name', 'GROUP');

   O nome do grupo diferencia maiúsculas de minúsculas e deve corresponder exatamente como aparece no seu workspace Databricks . Ao criar uma função do Postgres para um grupo, qualquer membro direto ou indireto (usuário ou entidade de serviço) desse grupo Databricks pode se autenticar no Postgres como a função do grupo usando seus tokens OAuth individuais. Isso permite gerenciar permissões no nível do grupo no Postgres, em vez de manter permissões para usuários individuais.

3. Conceda permissões de banco de dados à função recém-criada.

A função databricks_create_role() cria uma função do Postgres com permissão LOGIN apenas. Após criar a função, você deve conceder os privilégios e permissões de banco de dados apropriados nos bancos de dados, esquemas ou tabelas específicos que o usuário precisa acessar. Aprenda como: gerenciar permissões

Python SDK

Defina identity_type como USER, SERVICE_PRINCIPAL ou GROUP. Defina postgres_role para o endereço email da identidade, ID do aplicativo (UUID) ou nome de exibição do grupo, respectivamente. Esse valor se torna o nome da função do Postgres e é o que você usa nas strings de conexão e nas instruções GRANT .

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Role, RoleRoleSpec

w = WorkspaceClient()

operation = w.postgres.create_role(
    parent="projects/my-project/branches/production",
    role=Role(
        spec=RoleRoleSpec(
            identity_type="USER",
            postgres_role="user@example.com"
        )
    )
)
role = operation.wait()
print(f"Created role: {role.name}")

Após criar a função, conceda os privilégios de banco de dados apropriados. Aprenda como: gerenciar permissões

curl

Defina identity_type como USER, SERVICE_PRINCIPAL ou GROUP. Defina postgres_role para o endereço email da identidade, ID do aplicativo (UUID) ou nome de exibição do grupo, respectivamente. Esse valor se torna o nome da função do Postgres e é o que você usa nas strings de conexão e nas instruções GRANT .

Bash

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "identity_type": "USER",
      "postgres_role": "user@example.com"
    }
  }' | jq

O endpoint retorna uma operação de longa duração. Faça polling até que done seja true, então use o campo name da função para chamadas de API subsequentes. Veja Operações de longa duração.

Após criar a função, conceda os privilégios de banco de dados apropriados. Aprenda como: gerenciar permissões

Autenticação baseada em grupo

Ao criar uma função do Postgres para um grupo do Databricks, você habilita a autenticação baseada em grupo. Isso permite que qualquer membro do grupo Databricks se autentique no Postgres usando a função do grupo, simplificando o gerenciamento de permissões.

Como funciona:

1. Crie uma função do Postgres para um grupo do Databricks.
2. Conceda permissões de banco de dados à função de grupo no Postgres. Consulte gerenciar permissões.
3. Qualquer membro direto ou indireto (usuário ou entidade de serviço) do grupo Databricks pode se conectar ao Postgres usando seus tokens OAuth individuais.
4. Ao se conectar, o membro se autentica com a função do grupo e herda todas as permissões concedidas a essa função.

Fluxo de autenticação:

Quando um membro do grupo se conecta, ele especifica o nome da função Postgres do grupo como nome de usuário e seus próprios tokens OAuth como senha:

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

Considerações importantes:

• Validação de associação a grupos: A associação a grupos é validada apenas no momento da autenticação. Se um membro for removido do grupo Databricks após o estabelecimento de uma conexão, a conexão permanecerá ativa. Novas tentativas de conexão de membros removidos serão rejeitadas.
• Delimitação do espaço de trabalho: a autenticação baseada em grupo é compatível apenas com os grupos atribuídos ao mesmo workspace Databricks que o projeto. Para aprender como atribuir grupos a um workspace, consulte Gerenciar grupos.
• Diferenciação entre maiúsculas e minúsculas: O nome do grupo usado em databricks_create_role() deve corresponder exatamente ao nome do grupo como aparece no seu workspace Databricks , incluindo maiúsculas e minúsculas.
• Gerenciamento de permissões: Gerenciar permissões no nível de grupo no Postgres é mais eficiente do que gerenciar permissões de usuários individuais. Ao conceder permissões à função de grupo, todos os membros atuais e futuros do grupo herdam essas permissões automaticamente.
• Renomeação de identidade: Se email ou o nome de exibição do grupo de um usuário for alterado no Databricks, a autenticação e as concessões de banco de dados existentes serão interrompidas. Remova a função antiga, crie uma nova com o nome atualizado e atualize as strings de conexão e as permissões.

nota

Os nomes dos cargos não podem exceder 63 caracteres, e alguns nomes não são permitidos. Saiba mais: funções gerenciais

Crie uma função de senha nativa do Postgres

As conexões com senha podem ser desativadas no nível do projeto ou compute . Consulte Bloquear conexões por senha.

UI

1. Em Funções e Bancos de Dados > Adicionar função > tab Senha , insira um nome de função e, opcionalmente, conceda databricks_superuser ou atributos de sistema (CREATEDB, CREATEROLE, BYPASSRLS).
2. Copie a senha gerada e forneça-a ao usuário em local seguro. Não é exibido novamente.

SQL

SQL

CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password';

A senha deve ter pelo menos 12 caracteres, com uma combinação de letras minúsculas, maiúsculas, números e símbolos. As senhas definidas pelo usuário são validadas no momento da criação para garantir entropia de 60 bits.

Python SDK

Omita identity_type para criar uma função de senha. A API retorna uma senha gerada na resposta.

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Role, RoleRoleSpec

w = WorkspaceClient()

operation = w.postgres.create_role(
    parent="projects/my-project/branches/production",
    role=Role(
        spec=RoleRoleSpec(
            postgres_role="my-app-role"
        )
    )
)
role = operation.wait()
print(f"Created role: {role.name}")

curl

Omita identity_type para criar uma função de senha. O endpoint retorna uma operação de longa duração. Sondar até que done seja true.

Bash

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "postgres_role": "my-app-role"
    }
  }' | jq

visualizar funções do Postgres

UI

Para view todas as funções do Postgres em seu projeto, navegue até a tab Funções e Bancos de Dados do seu branch no aplicativo Lakebase. Todas as funções criadas na ramificação, com exceção das funções do sistema, estão listadas. A coluna Tipo de autenticação indica se cada função usa autenticação OAuth ou autenticação por senha.

PostgreSQL

Veja todas as funções com o comando \du :

Você pode view todas as funções do Postgres, incluindo as funções do sistema, usando o meta-comando \du de qualquer cliente Postgres (como psql) ou do editor SQL do Lakebase:

SQL

\du
                                      List of roles
          Role name          |                         Attributes
-----------------------------+------------------------------------------------------------
 cloud_admin                 | Superuser, Create role, Create DB, Replication, Bypass RLS
 my.user@databricks.com      | Create role, Create DB, Bypass RLS
 databricks_control_plane    | Superuser
 databricks_gateway          |
 databricks_monitor          |
 databricks_reader_12345     | Create role, Create DB, Replication, Bypass RLS
 databricks_replicator       | Replication
 databricks_superuser        | Create role, Create DB, Cannot login, Bypass RLS
 databricks_writer_12345     | Create role, Create DB, Replication, Bypass RLS

Python SDK

Liste todas as funções:

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

roles = w.postgres.list_roles(parent="projects/my-project/branches/production")
for role in roles:
    print(f"{role.status.postgres_role} ({role.status.identity_type or 'PASSWORD'}): {role.name}")

Obtenha uma função específica:

Python

role = w.postgres.get_role(
    name="projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx"
)
print(role)

curl

Liste todas as funções:

Bash

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Obtenha uma função específica:

Bash

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

A resposta inclui o campo name (por exemplo, rol-xxxx-xxxxxxxxxx) necessário para chamadas de atualização e exclusão.

Atualizar uma função

Para atualizar os atributos de uma função na interface do usuário, selecione Editar função no menu de funções na tab Funções e Bancos de Dados .

Utilize a API para atualizar as funções ou atributos do sistema de uma função. Use update_mask como parâmetro de consulta para especificar quais campos devem ser alterados; somente os campos mascarados serão modificados.

nota

Para obter o nome do recurso de uma função para uso em chamadas de atualização e exclusão, use o endpoint list roles . Os nomes dos recursos de função usam um identificador gerado pelo sistema (por exemplo, rol-xxxx-xxxxxxxxxx), não o valor postgres_role fornecido na criação.

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

Para remover databricks_superuser, passe um array vazio: "membership_roles": [].

Remover uma função do Postgres

Você pode remover tanto as funções baseadas em identidade do Databricks quanto as funções nativas de senha do Postgres.

UI

Excluir uma função é uma ação permanente que não pode ser desfeita. Para excluir uma função que possui um banco de dados, você deve especificar a função à qual os objetos de propriedade serão reatribuídos. Caso contrário, o banco de dados deverá ser excluído manualmente antes de excluir a função proprietária do banco de dados.

Para excluir qualquer função do Postgres usando a interface do usuário:

1. Acesse a tab "Funções e Bancos de Dados" da sua filial no aplicativo Lakebase.
2. Selecione "Excluir função" no menu de funções e confirme a exclusão.

PostgreSQL

Você pode remover qualquer função do Postgres usando o comando padrão do Postgres. Para obter detalhes, consulte a documentação do PostgreSQL sobre como remover funções (rolling roles).

Abandone uma vaga:

SQL

DROP ROLE role_name;

Após a remoção de uma função baseada em identidade do Databricks, essa identidade não poderá mais autenticar-se no Postgres usando tokens OAuth até que uma nova função seja criada.

Python SDK

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

operation = w.postgres.delete_role(
    name="projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx"
)
operation.wait()

curl

Bash

curl -X DELETE "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Funções pré-criadas

Após a criação de um projeto, Databricks cria automaticamente funções do Postgres para administração do projeto e para iniciar o processo.

Função	Descrição	Privilégios herdados
<project_owner_role>	A identidade Databricks do criador do projeto (por exemplo, my.user@databricks.com). Esta função é proprietária do banco de dados default databricks_postgres e pode log in e administrar o projeto.	Membro de databricks_superuser
databricks_superuser	Uma função administrativa interna. Utilizado para configurar e gerenciar o acesso em todo o projeto. Este cargo confere amplos privilégios.	Herda de pg_read_all_data, pg_write_all_data e pg_monitor.

Saiba mais sobre as capacidades e privilégios específicos dessas funções: Capacidades de funções pré-criadas

Funções do sistema criadas pelo Databricks

Databricks cria as seguintes funções de sistema necessárias para o serviço interno. Você pode view essas funções emitindo um comando \du a partir de psql ou do Editor SQL do Lakebase.

Função	Propósito
cloud_admin	Função de superusuário usada para gerenciamento de infraestrutura cloud .
databricks_control_plane	Função de superusuário usada por componentes internos do Databricks para operações de gerenciamento.
databricks_monitor	Utilizado pelo serviço de coleta de medições internas
databricks_replicator	Utilizado para operações de replicação de banco de dados
databricks_writer_<dbid>	Função por banco de dados usada para criar e gerenciar tabelas sincronizadas.
databricks_reader_<dbid>	Função por banco de dados usada para ler tabelas registradas no Unity Catalog
databricks_gateway	Utilizado para conexões internas para gerenciamento de serviço de atendimento de dados

Para aprender como funcionam os papéis, privilégios e associações de papéis no Postgres, utilize o seguinte recurso na documentação do Postgres:

• Funções do banco de dados
• Privilégios

Próximos passos

• Gerenciar permissões
• Conecte-se ao seu projeto
• Saiba mais sobre autenticação