Noções Básicas de Roles

8 exemplos para roles do PostgreSQL - 6 básicos e 2 intermediários. No PostgreSQL, roles são o principal universal: usuários de login e pacotes de permissão semelhantes a grupos são o mesmo tipo de objeto.

Pré-requisitos

-- Conecte-se como uma role que pode CRIAR ROLE (tipicamente superusuário ou CREATEROLE)
\du

• Prefira uma role por serviço de aplicação, não senhas humanas compartilhadas.
• Use roles de grupo (NOLOGIN) para modelar níveis de permissão.

Exemplos Básicos

1. Criar Role de Login

CREATE ROLE app_api LOGIN PASSWORD 'from-vault-rotate-quarterly';
ALTER ROLE app_api CONNECTION LIMIT 50;

• LOGIN permite autenticação por senha ou certificado.
• CONNECTION LIMIT limita a má configuração de pool descontrolada por role.
• Armazene senhas em um gerenciador de segredos; rotacione no desligamento.

2. Criar Role de Grupo (NOLOGIN)

CREATE ROLE app_readers NOLOGIN;
CREATE ROLE app_writers NOLOGIN;
 
GRANT app_readers TO app_api;
GRANT app_writers TO app_migrator;

• Roles de grupo detêm privilégios; roles de login herdam via GRANT group TO user.
• SET ROLE permite que um login assuma um grupo temporariamente.
• Modelo: app_api herda app_readers apenas em perfis de implantação somente leitura, se necessário.

Relacionado: Padrões GRANT/REVOKE - privilégios de objeto

3. Herança de Role

CREATE ROLE tenant_admin NOLOGIN;
CREATE ROLE support_agent LOGIN INHERIT PASSWORD 'vault';
 
GRANT tenant_admin TO support_agent;
 
-- support_agent automaticamente tem privilégios de tenant_admin quando INHERIT é true (padrão)

• INHERIT (padrão): os privilégios das roles concedidas se aplicam automaticamente.
• NOINHERIT: deve-se usar SET ROLE tenant_admin para ativar os privilégios.
• Use NOINHERIT para roles de "break-glass" auditadas na ativação.

4. Listar Roles e Membros

\du+
SELECT r.rolname, m.rolname AS member_of
FROM pg_roles r
LEFT JOIN pg_auth_members am ON am.member = r.oid
LEFT JOIN pg_roles m ON m.oid = am.roleid
WHERE r.rolname = 'app_api';

• \du+ mostra atributos: Superuser, Create role, Create DB, Replication.
• O gráfico de membros fica complexo - crie um diagrama na documentação de onboarding.
• pg_roles inclui roles que você não pode usar para LOGIN.

5. Alterar Atributos de Role

ALTER ROLE app_api SET statement_timeout = '30s';
ALTER ROLE app_api SET search_path = app, public;
ALTER ROLE app_migrator CREATEDB;  -- raramente - prefira concessões explícitas de banco de dados

• Padrões GUC por role se aplicam no login.
• search_path em roles de aplicação evita surpresas de sequestro de schema.
• Evite CREATEDB/CREATEROLE amplos em roles de login de aplicação.

6. Remover Role com Segurança

-- Reatribua objetos de propriedade primeiro
REASSIGN OWNED BY old_app TO app_owner;
DROP OWNED BY old_app;
DROP ROLE old_app;

• Não é possível remover uma role que possui objetos ou tem sessões ativas.
• DROP OWNED remove privilégios; revise antes de executar em produção.
• Checklist de desligamento: reatribuir, remover membros, revogar login.

Exemplos Intermediários

7. Hierarquia de Roles para Ambientes

CREATE ROLE app_owner NOLOGIN;
CREATE ROLE app_staging LOGIN PASSWORD 'vault';
CREATE ROLE app_prod LOGIN PASSWORD 'vault';
 
GRANT app_owner TO app_staging, app_migrator;
-- app_prod herda concessões mais restritas aplicadas separadamente

• Mesmo código de schema, roles de login diferentes por ambiente.
• CI usa app_migrator; tempo de execução usa app_api sem direitos DDL.
• Nunca copie o hash de senha de produção para staging.

Relacionado: Privilégios Padrão - migrações criam objetos como proprietário

8. SET ROLE para Elevação Auditada

CREATE ROLE ddl_runner NOLOGIN;
GRANT ddl_runner TO deploy_user WITH ADMIN OPTION FALSE;
 
-- Apenas em sessão de migração
SET ROLE ddl_runner;
CREATE TABLE audit.sample (id int);
RESET ROLE;

• SET ROLE é registrado em logs quando log_line_prefix inclui usuário e usuário da sessão.
• A role de migração não deve ser a proprietária do objeto em tempo de execução, se evitável.
• Emparelhe com NOINHERIT em deploy_user para elevação estrita.

Versões do Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.