Criar funções do Postgres

Quando você cria um projeto, o Lakebase cria várias funções do Postgres no projeto:

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

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

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

Várias funções gerenciadas pelo sistema também são criadas. Essas são funções internas usadas pelos serviços do Azure Databricks para gerenciamento, monitoramento e operações de dados.

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

Criar funções do Postgres

O Lakebase dá suporte a dois tipos de funções postgres para acesso ao banco de dados:

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

Para obter diretrizes 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 Azure Databricks

Para permitir que as identidades do Azure 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 databricks_auth extensão com SQL ou a API REST.

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

interface do usuário

1. Na guia Funções & Bancos de DadosAdicionar funçãoOAuth, selecione o usuário, a entidade de serviço ou o grupo ao qual conceder acesso ao banco de dados.
2. Depois de criar a função, conceda privilégios de banco de dados apropriados. Saiba como: gerenciar permissões

SQL

Pré-requisitos:

• Você deve ter CREATE e CREATE ROLE permissões no banco de dados
• Você deve ser autenticado como uma identidade do Azure Databricks com um token OAuth válido
• Sessões autenticadas do Postgres nativo 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.

   CREATE EXTENSION IF NOT EXISTS databricks_auth;
   

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

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

   Para um usuário do Azure Databricks:

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

   Para uma entidade de serviço do Azure Databricks:

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

   Para um grupo do Azure Databricks:

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

   O nome do grupo é sensível a maiúsculas e minúsculas e deve corresponder exatamente como aparece no workspace do Azure Databricks. Quando você cria uma função postgres para um grupo, qualquer membro direto ou indireto (usuário ou entidade de serviço) desse grupo do Databricks pode se autenticar no Postgres como a função de grupo usando seu token OAuth individual. Esse modelo de permissão no nível do grupo permite que você gerencie permissões 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 um papel Postgres com permissão LOGIN somente. Depois de 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. Saiba como: gerenciar permissões

SDK do Python

Definir identity_type como USER, SERVICE_PRINCIPALou GROUP. Defina postgres_role como o endereço de email da identidade, a ID do aplicativo (UUID) ou o nome de exibição do grupo, respectivamente. Esse valor se torna o nome da função do Postgres e é o que você usa em cadeias de conexão e declarações GRANT.

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

w = WorkspaceClient()

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

Depois de criar a função, conceda privilégios de banco de dados apropriados. Saiba como: gerenciar permissões

CLI

Definir identity_type como USER, SERVICE_PRINCIPALou GROUP. Defina postgres_role como o endereço de email da identidade, a ID do aplicativo (UUID) ou o nome de exibição do grupo, respectivamente. Esse valor se torna o nome da função do Postgres e é o que você usa em cadeias de conexão e declarações GRANT.

Para um usuário do Azure Databricks:

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

Para uma entidade de serviço do Azure Databricks:

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "8c01cfb1-62c9-4a09-88a8-e195f4b01b08"}}'

Para um grupo do Azure Databricks:

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-group-role \
  --json '{"spec": {"identity_type": "GROUP", "postgres_role": "My Group Name"}}'

O comando aguarda a conclusão da operação e retorna a função criada. Use --no-wait para retornar imediatamente e sondar separadamente com databricks postgres get-operation.

Depois de criar a função, conceda privilégios de banco de dados apropriados. Saiba como: gerenciar permissões

curl

Definir identity_type como USER, SERVICE_PRINCIPALou GROUP. Defina postgres_role como o endereço de email da identidade, a ID do aplicativo (UUID) ou o nome de exibição do grupo, respectivamente. Esse valor se torna o nome da função do Postgres e é o que você usa em cadeias de conexão e declarações GRANT.

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 ponto de extremidade retorna uma operação de longa execução. Aguarde até que done seja true, em seguida, use o campo name da função para chamadas subsequentes à API. Consulte operações de longa duração.

Depois de criar a função, conceda privilégios de banco de dados apropriados. Saiba como: gerenciar permissões

Autenticação baseada em grupo

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

Como funciona:

1. Crie uma função postgres para um grupo de Azure 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 de Azure Databricks pode se conectar ao Postgres usando seu token OAuth individual.
4. Ao se conectar, o membro se autentica como a função de 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 o nome de usuário e seu próprio token OAuth como a senha:

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 de grupo: A associação de grupo é validada somente no momento da autenticação. Se um membro for removido do grupo do Azure Databricks após estabelecer uma conexão, a conexão permanecerá ativa. Novas tentativas de conexão de membros removidos são rejeitadas.
• Escopo do workspace: somente os grupos atribuídos ao mesmo workspace do Azure Databricks que o projeto têm suporte para autenticação baseada em grupo. Para saber como atribuir grupos a um workspace, consulte Gerenciar grupos.
• Diferenciação de maiúsculas e minúsculas: o nome do grupo usado em databricks_create_role() deve corresponder ao nome do grupo exatamente como ele aparece no workspace do Azure Databricks, incluindo maiúsculas e minúsculas.
• Gerenciamento de permissões: Gerenciar permissões no nível do grupo no Postgres é mais eficiente do que gerenciar permissões de usuário individuais. Quando você concede permissões à função de grupo, todos os membros atuais e futuros do grupo herdam essas permissões automaticamente.
• Identity renaming: Se o email de um usuário ou o nome de exibição do grupo for alterado no Azure Databricks, a autenticação e as permissões do banco de dados existentes serão interrompidos. Solte a função antiga, crie uma nova com o nome atualizado e atualize cadeias de conexão e concessões.

Crie uma função nativa de senha Postgres

As conexões de senha podem ser desabilitadas no nível do projeto ou da computação. Consulte Bloquear conexões de senha.

interface do usuário

1. Na aba Funções & Bancos de Dados>Adicionar função>Senha, insira um nome de função e, opcionalmente, conceda databricks_superuser (CREATEDB, CREATEROLE, BYPASSRLS).
2. Copie a senha gerada e forneça-a com segurança ao usuário. Ele não é mostrado novamente.

SQL

CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password';

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

SDK do Python

Omita identity_type para criar uma função de senha. A create_role operação retorna um Role objeto sem campo de senha. O SDK não retorna a senha gerada. Para obter uma senha utilizável, veja Como obter uma senha.

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}")

CLI

Omita identity_type para criar uma função de senha. O comando retorna um Role objeto sem campo de senha. A CLI não retorna a senha gerada. Para obter uma senha utilizável, veja Como obter uma senha.

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

O comando aguarda a conclusão da operação e retorna a função criada.

curl

Omita identity_type para criar uma função de senha. O ponto de extremidade retorna uma operação de longa execução. Aguarde até que done seja true. O resultado da operação é um Role objeto sem campo de senha. A API não retorna a senha gerada. Para obter uma senha utilizável, veja Como obter uma senha.

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

Como obter uma senha

As operações create-role do SDK do Python, 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 nativa de senha 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 OAuth SQL. Isso exige o privilégio CREATEROLE. Veja a aba SQL na função Criar uma senha nativa do Postgres.
• Redefina a senha na interface: Para uma função criada com o SDK Python, API REST, CLI ou Terraform, use o fluxo Redefinir senha no aplicativo Lakebase para gerar uma nova senha. Veja Redefinir uma senha.

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

Independentemente de como você crie uma role do Postgres com senha nativa, a senha nunca é armazenada em texto simples. O núcleo Postgres do nó de computação armazena um verificador SCRAM-SHA-256, calculado no lado do servidor (o padrão de computação é password_encryption = scram-sha-256). Quando o Lakebase gera a senha para você (a interface, SDK Python, API REST e caminhos da CLI), o plano de controle também mantém uma cópia criptografada em KMS da credencial, que é o que permite à interface exibir ou redefinir a senha depois. As senhas que você define com SQL não são mantidas dessa forma: apenas o verificador é armazenado.

• UI: Azure Databricks gera a senha do lado do servidor, calcula o verificador e exibe a senha gerada uma vez. Copie-o então, porque ele não será mostrado novamente.
• Python SDK, API REST e CLI: Azure Databricks gera a senha do 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 siga o fluxo da IU Redefinir senha. Veja Como obter uma senha. Esses caminhos não aceitam uma senha que você fornece.
• SQL: quando você executa CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password'; (ou psql's \password), você fornece o texto sem formatação e o servidor o coloca no verificador.

Você nunca precisa gerar o hash de uma senha você mesmo.

Exibir funções do Postgres

interface do usuário

Para exibir todas as funções do Postgres em seu projeto, navegue até a guia Funções &Bancos de Dados do branch no Aplicativo Lakebase. Todas as funções criadas no branch, com exceção das funções do sistema, são listadas. A coluna de tipo de autenticação indica se cada função usa autenticação OAuth ou Password.

PostgreSQL

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

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

\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

SDK do Python

Listar todas as funções:

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:

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

CLI

Listar todas as funções:

databricks postgres list-roles projects/my-project/branches/production

Obtenha uma função específica:

databricks postgres get-role projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx

A saída inclui o name campo (por exemplo, rol-xxxx-xxxxxxxxxx) necessário para atualizar e excluir chamadas.

curl

Listar todas as funções:

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:

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 name campo (por exemplo, rol-xxxx-xxxxxxxxxx) necessário para atualizar e excluir chamadas.

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ção na guia 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 são alterados.

CLI

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 todo o objeto de atributos:

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 também atualizar as funções de associação, adicione spec.membership_roles à máscara de atualização:

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 uma matriz vazia: "membership_roles": [].

curl

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 uma matriz vazia: "membership_roles": [].

Descartar uma função do Postgres

Você pode excluir funções baseadas em identidade do Azure Databricks e funções de senha pré-definidas do Postgres.

interface do usuário

1. Vá para a guia Funções e Bancos de Dados da sua filial no aplicativo Lakebase.

2. Clique no menu da função que você deseja remover e selecione Soltar.

3. Na caixa de diálogo de confirmação, se desejar, ative Reatribuir objetos pertencentes.

   Uma função Postgres não poderá ser descartada se ela tiver objetos de banco de dados, como tabelas, exibições ou esquemas. Quando ativado, aparecerá um menu suspenso Reatribuir propriedade para. Selecione a função para receber a propriedade dos objetos antes do descarte. Objetos que não podem ser reatribuídos, como concessões à função que está sendo descartada, são removidos automaticamente após a conclusão da reatribuição. Se desabilitada, o descarte falhará se a função for proprietária de algum objeto.

4. Clique em Confirmar.

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

PostgreSQL

Você pode remover qualquer função postgres usando comandos postgres padrão. Para obter detalhes, consulte a documentação do PostgreSQL sobre a remoção de funções.

Excluir uma função:

DROP ROLE role_name;

Depois que uma função baseada em identidade do Azure Databricks é descartada, essa identidade não pode mais se autenticar no Postgres usando tokens OAuth até que uma nova função seja criada.

CLI

databricks postgres delete-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx

Se a função possuir objetos de banco de dados, use --reassign-owned-to para transferir a propriedade para outra função antes da exclusão:

databricks postgres delete-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  --reassign-owned-to projects/my-project/branches/production/roles/rol-yyyy-yyyyyyyyyy

SDK do 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

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

Depois que um projeto é criado, o Azure Databricks cria automaticamente funções do Postgres para administração de projeto e introdução.

Saiba mais sobre os recursos e privilégios específicos dessas funções: funcionalidades de função pré-criadas

Funções do sistema criadas pelo Azure Databricks

O Azure Databricks cria as seguintes funções de sistema necessárias para serviços internos. Você pode exibir essas funções emitindo um comando \du de psql ou do Editor de SQL do Lakebase.

Para saber como as funções, privilégios e associações de função funcionam no Postgres, use os seguintes recursos na documentação do Postgres:

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

Recursos adicionais

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