Pular para o conteúdo principal

Criar funções do Postgres

info

Beta

A partir de 15 de junho, o Lakebase está disponível em Beta no GCP. Consulte Disponibilidade regional para regiões compatíveis.

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.

  1. Em Funções e Bancos de Dados > Adicionar função > tab OAuth , selecione o usuário, a entidade de serviço Databricks ou o 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

Adicionar função — tab OAuth

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 Databricks ) 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 que você concedeu 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 permissõ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

Criar 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.

  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.

Adicionar função — tabSenha

nota

Os recursos nativos de senha do Postgres são compatíveis com o pool de conexões integrado. Consulte Usar o agrupamento de conexões.

Como obter uma senha​

As operações de criação de função do Python SDK, da API REST e da CLI não retornam a senha gerada. Use um dos seguintes métodos para obter uma senha para uma função de senha nativa do Postgres:

  • Defina sua própria senha no momento da criação com SQL: Execute CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password'; em uma conexão SQL OAuth. Isso requer o privilégio CREATEROLE. Consulte a tab SQL em Create a native Postgres password role.
  • Reset a senha na interface do usuário: Para uma função criada com o Python SDK, REST API, CLI ou Terraform, use o fluxo Reset senha no aplicativo Lakebase para gerar uma nova senha. Consulte Reset uma senha.
nota

As funções criadas com o SDK Python, a API REST ou o Terraform são de propriedade de uma função interna do plano de controle. Os principals do cliente não podem alterar as senhas dessas funções com SQL, porque o Postgres 16 requer a opção ADMIN na função para alterar sua senha. Use o fluxo de Reset password da IU como alternativa.

Como as funções de senha nativas são armazenadas​

Independentemente de como você cria uma função de senha nativa do Postgres, sua senha nunca é armazenada em texto simples. O núcleo Postgres do nó de compute armazena um verificador SCRAM-SHA-256, calculado no lado do servidor (o default do compute é password_encryption = scram-sha-256). Quando o Lakebase gera a senha para você (caminhos da UI, Python SDK, API REST e CLI), o plano de controle também retém uma cópia da credencial criptografada por KMS, que é o que permite que a UI exiba ou faça o reset da senha posteriormente. As senhas que você define com SQL não são retidas dessa forma: apenas o verificador é armazenado.

  • UI: O Databricks gera a senha no lado do servidor, calcula o verificador e exibe a senha gerada uma única vez. Copie-a então, pois ela não será exibida novamente.
  • SDK do Python, API REST e CLI: O Databricks gera a senha no lado do servidor e calcula o verificador, mas não retorna a senha na resposta. Para obter uma senha utilizável, use SQL no momento da criação ou o fluxo de Reset password da interface de usuário. Consulte Como obter uma senha. Esses caminhos não aceitam uma senha fornecida por você.
  • **SQL:** quando você executa CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password'; (ou psql o \password de), você fornece o texto simples e o servidor gera o hash dele no verificador.

Nunca é necessário fazer o hash de uma senha por conta própria.

visualizar funções do Postgres​

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.

Lista de funções

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 .

Use a API ou a CLI para atualizar as funções ou atributos do sistema de uma função. Somente os campos especificados na máscara de atualização serão alterados.

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.

Atualize uma função usando o padrão de máscara de atualização. A máscara de atualização é o segundo argumento posicional após o nome do recurso.

Ao atualizar spec.attributes, você deve fornecer todos os três campos de atributo (createdb, createrole, bypassrls) — a API substitui o objeto de atributos inteiro:

Bash
databricks postgres update-role \
projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
"spec.attributes" \
--json '{
"spec": {
"attributes": {"createdb": true, "createrole": false, "bypassrls": false}
}
}'

Para atualizar também as funções de associação, adicione spec.membership_roles à máscara de atualização:

Bash
databricks postgres update-role \
projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
"spec.membership_roles" \
--json '{"spec": {"membership_roles": ["DATABRICKS_SUPERUSER"]}}'

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 Databricks quanto as funções de senha integradas do Postgres.

  1. Acesse a tab Funções e Bancos de Dados da sua filial no aplicativo Lakebase .

  2. Clique no menu para a função que deseja excluir e selecione Excluir .

  3. Na caixa de diálogo de confirmação, opcionalmente, habilite a opção Reatribuir objetos pertencentes a você .

    Não é possível eliminar uma função Postgres se ela possuir objetos de banco de dados, como tabelas, visualizações ou esquemas. Quando ativado, aparece um dropdown Reatribuir para . Selecione a função para receber a propriedade dos objetos antes da exclusão. Objetos que não podem ser reatribuídos, como concessões para a função que está sendo eliminada, são descartados automaticamente após a reatribuição ser concluída. Quando desabilitado, a eliminação falha se a função possuir objetos.

  4. Clique em Confirmar .

A exclusão de uma função é permanente e não pode ser desfeita.

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.

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

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:

Recursos adicionais​