> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciar contas de serviço de banco de dados

> Esta página descreve como os administradores podem adicionar contas de serviço de banco de dados

As contas de serviço de banco de dados podem ser tão simples quanto um usuário com uma senha ou certificado separado para autenticação. Usuários mais avançados podem querer configurar contas nas quais o escopo das permissões possa ser alterado dinamicamente com SET ROLE, para permitir a alternância rápida entre perfis sem sair da sessão nem recarregar o conteúdo.

<div id="overview">
  ## Visão geral
</div>

[SET ROLE](/docs/pt-BR/reference/statements/set-role) pode ser usado para definir dinamicamente o escopo das permissões de uma conta de serviço durante uma sessão. Isso funciona limitando as permissões efetivas de um usuário apenas àquelas concedidas pelo(s) role(s) ativado(s). Essa abordagem tem várias vantagens:

* Contas de serviço podem receber vários roles, mas ativar apenas o necessário para uma consulta específica.
* Invasores só podem usar as permissões do role ativo se a conta de serviço for comprometida.
* Uma única conta pode executar tarefas diversas alternando entre roles, em vez de exigir credenciais separadas para cada tarefa.
* As permissões podem ser atualizadas para toda uma classe de contas de serviço modificando um role, em vez de atualizar usuários individuais.
* Os logs podem rastrear qual role específico estava ativo durante uma consulta, fornecendo um contexto mais claro para auditorias de segurança.

Na prática, você:

1. Projeta roles que definem os limites permitidos (read\_only, maintenance etc.)
2. Concede esses roles à conta de serviço
3. No momento da conexão, escolhe o(s) role(s) ativo(s) por meio de `SET ROLE` (ou do parâmetro de role), restringindo assim o que essa sessão pode fazer

<div id="setup-service-roles">
  ## Configure uma role de serviço
</div>

<Steps>
  <Step title="Conceda roles à conta de serviço" id="grant-roles-to-service-account">
    Primeiro, crie roles com os privilégios/configurações desejados e, em seguida, conceda-as à conta de serviço.

    ```sql theme={null}
    CREATE ROLE read_only_role;
    GRANT SELECT ON db1.* TO read_only_role;

    CREATE ROLE maint_role;
    GRANT SELECT, INSERT, ALTER on db1.* TO maint_role;

    GRANT read_only_role, maint_role TO service_user;
    ```
  </Step>

  <Step title="Use SET ROLE para definir limites da sessão" id="define-permission-boundaries">
    No início de uma sessão, a conta de serviço escolhe quais roles ficam ativas:

    ```sql theme={null}
    -- Comportamento somente leitura para esta sessão
    SET ROLE read_only_role;
    ```

    ou:

    ```sql theme={null}
    -- Usa todas as roles concedidas (acesso total)
    SET ROLE ALL;
    ```

    `SET ROLE` ativa roles para o usuário atual; os privilégios efetivos são a união de todas as roles ativas, além daqueles concedidos diretamente ao usuário.

    Você também pode desativar todas as roles:

    ```sql theme={null}
    SET ROLE NONE;
    ```

    ou ativar várias roles:

    ```sql theme={null}
    SET ROLE read_only_role, maint_role;
    ```

    As roles ativas no momento podem ser consultadas em `system.current_roles`.
  </Step>

  <Step title="Defina roles padrão para a conta de serviço" id="set-default-role">
    Para garantir que a conta de serviço sempre inicie em modo restrito, configure as roles padrão:

    ```sql theme={null}
    SET DEFAULT ROLE read_only_role TO service_user;
    ```

    ou

    ```sql theme={null}
    SET DEFAULT ROLE ALL EXCEPT maint_role TO service_user;
    ```
  </Step>

  <Step title="Uso de SET ROLE via HTTP / programaticamente" id="use-set-role-programmatically">
    Se a conta de serviço se conectar via HTTP, você não poderá enviar SET ROLE; SELECT ... como múltiplas instruções. Em vez disso, passe a role como um parâmetro de consulta:

    ```shell theme={null}
    curl "https://host:8123?user=service_user&password=...&role=read_only_role" \
     --data-binary "SELECT * FROM db1.table1"
    ```

    `?role=`... equivale a executar `SET ROLE read_only_role` antes da instrução. Vários parâmetros `role` se comportam como `SET ROLE role 1, role 2`.

    Alguns drivers (por exemplo, ClickHouse Connect para Python) também expõem uma configuração de role que é enviada com cada requisição e que o servidor usa como role da sessão.
  </Step>
</Steps>