CREATE ROLE

CREATE ROLE
Anterior	Acima	Comandos SQL	Principal	Próxima

CREATE ROLE — define uma nova função de banco de dados (role)

Sinopse

CREATE ROLE nome [ [ WITH ] opção [ ... ] ]

onde opção pode ser:

      SUPERUSER | NOSUPERUSER
    | CREATEDB | NOCREATEDB
    | CREATEROLE | NOCREATEROLE
    | INHERIT | NOINHERIT
    | LOGIN | NOLOGIN
    | REPLICATION | NOREPLICATION
    | BYPASSRLS | NOBYPASSRLS
    | CONNECTION LIMIT limite_de_conexões
    | [ ENCRYPTED ] PASSWORD 'senha' | PASSWORD NULL
    | VALID UNTIL 'carimbo_de_tempo'
    | IN ROLE nome_da_role [, ...]
    | ROLE nome_da_role [, ...]
    | ADMIN nome_da_role [, ...]
    | SYSID uid

Descrição

O comando CREATE ROLE adiciona uma nova função de banco de dados (role) a uma instância de banco de dados do PostgreSQL ^[134] ^[135] ^[136]. Uma função de banco de dados é uma entidade que pode ser dona de objetos de banco de dados, e ter privilégios de banco de dados; uma função de banco de dados pode ser considerada um “usuário”, um “grupo”, ou os dois, dependendo de como é usada. Veja Capítulo 21 e o Autenticação do cliente para obter informações sobre como gerenciar funções de banco de dados e autenticação. É necessário possuir o privilégio CREATEROLE, ou ser um superusuário do banco de dados, para usar este comando.

Note que as funções de banco de dados são definidas no nível da instância de bancos de dados, portanto, são válidas em todos os bancos de dados da instância.

Durante a criação das funções de banco de dados é possível definir imediatamente para a função de banco de dados recém-criada ser ela um membro de uma função de banco de dados existente e, também, definir funções de banco de dados existentes como membros da função de banco de dados recém-criada. As regras que definem quais opções de associação inicial são ativadas para as funções de banco de dados estão descritas abaixo nas cláusulas IN ROLE, ROLE e ADMIN . O comando GRANT oferece controle preciso das opções durante a criação da associação, além da possibilidade de modificar estas opções após a criação da nova função de banco de dados.

Parâmetros

nome

O nome da nova função de banco de dados (role).

SUPERUSER NOSUPERUSER

Estas cláusulas determinam se a nova função de banco de dados é um “superusuário”, que pode desconsiderar todas as restrições de acesso no banco de dados. O status de superusuário é perigoso, devendo ser usado apenas quando realmente necessário. É necessário ser um superusuário para criar um novo superusuário. O padrão é NOSUPERUSER.

CREATEDB NOCREATEDB

Estas cláusulas definem a capacidade de uma função de banco de dados criar bancos de dados. Se for especificado CREATEDB, a função de banco de dados que está sendo definida poderá criar novos bancos de dados. Especificar NOCREATEDB nega a função de banco de dados a capacidade de criar bancos de dados. O padrão é NOCREATEDB. Somente funções de banco de dados de superusuário ou funções de banco de dados com CREATEDB podem especificar CREATEDB.

CREATEROLE NOCREATEROLE

Estas cláusulas determinam se uma função de banco de dados terá permissão para criar, alterar, excluir, comentar e modificar o rótulo de segurança de outras funções. Veja role creation para obter mais detalhes sobre as capacidades conferidas por este privilégio. O padrão é NOCREATEROLE.

INHERIT NOINHERIT

Isto afeta o status de herança de associação quando esta função de banco de dados é adicionada como membro de outra função de banco de dados, tanto neste comando quanto em comandos futuros. Especificamente, controla o status de herança das associações adicionadas com este comando usando a cláusula IN ROLE e, em comandos posteriores, usando a cláusula ROLE. Também é usado como o status de herança padrão ao adicionar esta função de banco de dados como membro usando o comando GRANT. O padrão é INHERIT.

Nas versões do PostgreSQL anteriores à 16, a herança era um atributo no nível de função de banco de dados que controlava todas as verificações de associação em tempo de execução para esta função de banco de dados.

LOGIN NOLOGIN

Estas cláusulas determinam se a função de banco de dados tem permissão para se conectar; ou seja, se a função de banco de dados pode ser usada como o nome de autorização da sessão inicial durante a conexão do cliente. Uma função de banco de dados com o atributo LOGIN pode ser considerada sendo um usuário. Funções de banco de dados sem este atributo são úteis para gerenciar privilégios de banco de dados, mas não são usuários no sentido habitual da palavra. Se não especificado, o padrão é NOLOGIN, exceto quando o comando CREATE ROLE é chamado por meio de sua grafia alternativa CREATE USER.

REPLICATION NOREPLICATION

Estas cláusulas determinam se a função de banco de dados é uma função de replicação. A função de banco de dados deve ter este atributo (ou ser um superusuário) para poder se conectar ao servidor no modo de replicação (replicação física ou lógica), e para poder criar ou remover encaixes (slots) de replicação. Uma função de banco de dados com o atributo REPLICATION é uma função altamente privilegiada, só devendo ser usada em funções realmente usadas para replicação. O padrão é NOREPLICATION. Somente superusuários e funções de banco de dados com o privilégio REPLICATION podem especificar REPLICATION.

BYPASSRLS NOBYPASSRLS

Estas cláusulas determinam se a função de banco de dados ignora todas as políticas de RLS (segurança no nível de linha). O padrão é NOBYPASSRLS. Somente superusuários e funções de banco de dados com o privilégio BYPASSRLS podem especificar BYPASSRLS.

Note que o pg_dump irá definir row_security como OFF por padrão, para garantir que todo o conteúdo de uma tabela seja exportado. Se o usuário que executa o pg_dump não tiver as permissões apropriadas, será retornado um erro. Entretanto, os superusuários e o dono da tabela que está sendo exportada sempre ignoram a segurança no nível de linha (RLS).

CONNECTION LIMIT limite_de_conexões

Se a função de banco de dados puder se conectar, esta cláusula especifica quantas conexões simultâneas a função pode fazer. -1 (o padrão) significa sem limite. Note que apenas as conexões normais são contadas para este limite. Nem as transações preparadas, nem as conexões de trabalho em segundo plano, são contabilizadas para este limite.

[ ENCRYPTED ] PASSWORD 'senha' PASSWORD NULL

Define a senha da função de banco de dados. (A senha só é usada para funções com o atributo LOGIN, mas pode-se definir uma senha para funções de banco de dados sem este atributo.) Se não se planeja usar autenticação por senha, esta opção pode ser omitida. Se nenhuma senha for especificada, a senha será definida como nula, e a autenticação por senha sempre irá falhar para este usuário. A senha nula pode ser opcionalmente escrita explicitamente como PASSWORD NULL.

Nota

Especificar uma cadeia de caracteres vazia também define a senha como nula, mas este não era o caso antes da versão 10 do PostgreSQL. Nas versões anteriores, uma cadeia de caracteres vazia poderia ser usada, ou não, dependendo do método de autenticação e da versão exata, e a libpq se recusaria a usá-la em qualquer caso. Para evitar ambiguidade, deve-se evitar especificar uma cadeia de caracteres vazia.

A senha é sempre armazenada encriptada nos catálogos do sistema. A palavra-chave ENCRYPTED não tem efeito, mas é aceita para manter a compatibilidade com as versões anteriores. O método de encriptação é determinado pelo parâmetro de configuração password_encryption. Se a cadeia de caracteres de senha apresentada já estiver no formato encriptado em MD5, ou encriptado em SCRAM, ela será armazenada como está, independentemente do parâmetro password_encryption (porque o sistema não pode desencriptar a cadeia de caracteres da senha encriptada fornecida, e a encriptá-la em um formato diferente). Isto permite o recarregamento de senhas encriptadas durante o salvamento/recuperação (dump/restore).

Atenção

O suporte para senhas criptografadas com MD5 está obsoleto e será removido em uma versão futura do PostgreSQL. Veja Autenticação por senha para obter detalhes sobre como migrar para outro tipo de senha.

VALID UNTIL 'carimbo_de_tempo'

A cláusula VALID UNTIL define uma data e hora após a qual a senha da função de banco de dados não é mais válida. Se esta cláusula for omitida, a senha será válida para sempre.

IN ROLE nome_da_role

A cláusula IN ROLE faz com que a nova função seja adicionada automaticamente como membro das funções existentes especificadas. A nova adição terá a opção SET ativada e a opção ADMIN desativada. A opção INHERIT será ativada a menos que a opção NOINHERIT seja especificada.

ROLE nome_da_role

A cláusula ROLE faz com que uma ou mais funções de banco de dados existentes especificadas sejam adicionadas automaticamente como membros da nova função de banco de dados, com a opção SET ativada. Isto, na prática, transforma a nova função de banco de dados em um “grupo”. As funções de banco de dados indicadas nesta cláusula com o atributo no nível de função de banco de dados INHERIT terão a opção INHERIT ativada na nova inclusão. Para as novas adições, a opção ADMIN estará desativada.

ADMIN nome_da_role

A cláusula ADMIN tem o mesmo efeito que ROLE, mas as funções indicadas são adicionadas como membros da nova função com ADMIN ativado, dando-lhes o direito de conceder a outros a participação na nova função de banco de dados.

SYSID uid

A cláusula SYSID é ignorada, mas é aceita para fins de compatibilidade com versões anteriores.

Notas

Deve ser usado o comando ALTER ROLE para alterar os atributos de uma função de banco de dados, e DROP ROLE para remover uma função de banco de dados. Todos os atributos especificados por CREATE ROLE podem ser modificados por comandos ALTER ROLE posteriores.

A maneira preferida para adicionar e remover membros de funções de banco de dados que estão sendo usadas como grupos, é usar os comandos GRANT e REVOKE.

A cláusula VALID UNTIL define o momento de expiração da senha apenas, e não da função de banco de dados em si. Em particular, o momento de expiração não é aplicado ao se conectar usando um método de autenticação não baseado em senha.

Os atributos de função de banco de dados definidos aqui não são herdáveis, ou seja, ser membro de uma função de banco de dados com, por exemplo, CREATEDB, não permitirá que o membro crie novos bancos de dados, mesmo que a concessão de associação tenha a opção INHERIT. É claro que, se a concessão de associação tiver a opção SET a função de banco de dados de membro permitiria o udo de SET ROLE para a função de banco de dados createdb e, em seguida, criar um novo banco de dados.

As concessões de ser membro criadas pelas cláusulas IN ROLE, ROLE e ADMIN têm como concedente a função de banco de dados que executa este comando..

O atributo INHERIT é o padrão por motivos de compatibilidade com versões anteriores: em versões anteriores do PostgreSQL, os usuários sempre tinham acesso a todos os privilégios dos grupos dos quais eram membros. Entretanto, NOINHERIT oferece uma correspondência mais próxima com a semântica especificada no padrão SQL.

O PostgreSQL inclui o programa createuser que tem a mesma funcionalidade do comando CREATE ROLE (na verdade, ele chama este comando), mas pode ser executado a partir do terminal.

A opção CONNECTION LIMIT é aplicada apenas de forma aproximada; se duas novas sessões forem iniciadas quase ao mesmo tempo, quando restar apenas um “slot” de conexão para a função de banco de dados, é possível que ambas falhem. Além disso, o limite nunca é aplicado a superusuários.

É preciso ter cautela ao especificar uma senha não encriptada com este comando. A senha será transmitida ao servidor em texto não encriptado e também poderá ser registrada no histórico de comandos do cliente ou no registro de transações do servidor. Entretanto, o comando createuser Transmite a senha encriptada. Além disso, o psql contém o comando \password que pode ser usado para alterar a senha com segurança posteriormente.

Exemplos

Criar uma função de banco de dados que possa se conectar, mas não fornecendo uma senha:

CREATE ROLE jonathan LOGIN;

Criar uma função de banco de dados com senha:

CREATE USER davide WITH PASSWORD 'jw8s0F4';

(O comando CREATE USER é o mesmo que CREATE ROLE, exceto por implicar em LOGIN.)

Criar uma função de banco de dados com uma senha válida até o final de 2029. Após iniciar 2030, a senha não será mais válida.

CREATE ROLE miriam WITH LOGIN PASSWORD 'jw8s0F4' VALID UNTIL '2030-01-01';

Criar uma função de banco de dados que possa criar bancos de dados e gerenciar funções de banco de dados:

CREATE ROLE admin WITH CREATEDB CREATEROLE;

Conformidade

O comando CREATE ROLE existe no padrão SQL, mas o padrão requer apenas a sintaxe

CREATE ROLE nome [ WITH ADMIN nome_da_role ]

Diversos administradores iniciais, e todas as outras opções do comando CREATE ROLE, são extensões do PostgreSQL.

O padrão SQL define os conceitos de usuários e funções de banco de dados, mas os considera como conceitos distintos e deixa todos os comandos que definem usuários para serem especificados por cada implementação de banco de dados. No PostgreSQL se optou por unificar usuários e funções de banco de dados em um único tipo de entidade. As funções de banco de dados, portanto, têm muito mais atributos opcionais do que no padrão SQL.

O comportamento especificado pelo padrão SQL é mais bem aproximado pela criação de usuários padrão-SQL como funções de banco de dados do PostgreSQL com a opção NOINHERIT e funções de banco de dados padrão-SQL como funções de banco de dados do PostgreSQL com a opção INHERIT.

A cláusula USER tem o mesmo comportamento que ROLE, mas foi descontinuada:

USER nome_da_role [, ...]

A cláusula IN GROUP tem o mesmo comportamento que IN ROLE, mas foi descontinuada:

IN GROUP nome_da_role [, ...]

Veja também

SET ROLE, ALTER ROLE, DROP ROLE, GRANT, REVOKE, createuser, createrole_self_grant, pg_roles

^[134] Use o comando CREATE ROLE para criar uma função de banco de dados (role), que é um conjunto de privilégios que podem ser concedidos a usuários, ou a outras funções de banco de dados. Você pode usar funções de banco de dados para administrar os privilégios do banco de dados. Você pode adicionar privilégios a uma função de banco de dados e conceder a função de banco de dados a um usuário. O usuário poderá ativar a função de banco de dados e exercer os privilégios concedidos pela função. Oracle 21 – CREATE ROLE (N. T.)

^[135] O comando CREATE ROLE define uma função de banco de dados (role) no servidor corrente. IBM DB2 12.1.x – CREATE ROLE statement (N. T.)

^[136] As funções de banco de dados (roles) simplificam a administração e o gerenciamento de privilégios, oferecendo uma capacidade equivalente a grupos, mas sem as mesmas restrições. IBM DB2 12.1.x – Roles (N. T.)