CREATE ROLE

새 데이터베이스 역할(role)을 PostgreSQL 데이터베이스 클러스터에 추가하는 명령이에요. 데이터베이스 객체를 소유하고 권한을 가지는 주체(엔티티)를 정의합니다.

출처: PostgreSQL 문서

본문

문법 (Synopsis)

CREATE ROLE name [ [ WITH ] option [ ... ] ]

where option can be:

      SUPERUSER | NOSUPERUSER
    | CREATEDB | NOCREATEDB
    | CREATEROLE | NOCREATEROLE
    | INHERIT | NOINHERIT
    | LOGIN | NOLOGIN
    | REPLICATION | NOREPLICATION
    | BYPASSRLS | NOBYPASSRLS
    | CONNECTION LIMIT connlimit
    | [ ENCRYPTED ] PASSWORD 'password' | PASSWORD NULL
    | VALID UNTIL 'timestamp'
    | IN ROLE role_name [, ...]
    | ROLE role_name [, ...]
    | ADMIN role_name [, ...]
    | SYSID uid

설명 (Description)

CREATE ROLE은 새 역할을 PostgreSQL 데이터베이스 클러스터에 추가해요. 역할은 데이터베이스 객체를 소유하고 데이터베이스 권한을 가질 수 있는 주체이며, 어떻게 쓰느냐에 따라 '사용자', '그룹', 또는 둘 다로 볼 수 있어요. 사용자 관리와 인증에 대한 정보는 21장과 20장을 참고하세요. 이 명령을 쓰려면 CREATEROLE 권한이 있거나 데이터베이스 슈퍼유저여야 합니다.

역할은 데이터베이스 클러스터 수준에서 정의되므로 클러스터의 모든 데이터베이스에서 유효하다는 점을 기억하세요.

역할을 만들 때 새로 만든 역할을 기존 역할의 구성원으로 즉시 지정하거나, 기존 역할을 새로 만든 역할의 구성원으로 지정할 수도 있어요. 어떤 초기 역할 구성원 옵션이 켜지는지에 대한 규칙은 아래 IN ROLE, ROLE, ADMIN 절에서 설명합니다. GRANT 명령은 구성원 생성 중 세밀한 옵션 제어와, 새 역할이 만들어진 뒤 그 옵션을 수정하는 기능을 제공합니다.

파라미터 (Parameters)

name — 새 역할의 이름.
SUPERUSER / NOSUPERUSER — 새 역할이 데이터베이스 안의 모든 접근 제한을 무시할 수 있는 '슈퍼유저'인지 결정해요. 슈퍼유저 상태는 위험하므로 정말 필요할 때만 써야 합니다. 새 슈퍼유저를 만들려면 자신이 슈퍼유저여야 해요. 지정하지 않으면 NOSUPERUSER가 기본입니다.
CREATEDB / NOCREATEDB — 역할의 데이터베이스 생성 능력을 정의해요. CREATEDB를 지정하면 정의되는 역할이 새 데이터베이스를 만들 수 있게 됩니다. NOCREATEDB를 지정하면 데이터베이스 생성 능력을 거부해요. 지정하지 않으면 NOCREATEDB가 기본입니다. 슈퍼유저 역할이나 CREATEDB가 있는 역할만 CREATEDB를 지정할 수 있어요.
CREATEROLE / NOCREATEROLE — 역할이 다른 역할을 만들고, 변경하고, 삭제하고, 주석을 달고, 보안 라벨을 바꿀 수 있는지 결정해요. 이 권한이 어떤 능력을 주는지에 대한 자세한 내용은 역할 생성 문서를 참고하세요. 지정하지 않으면 NOCREATEROLE이 기본입니다.
INHERIT / NOINHERIT — 이 역할이 다른 역할의 구성원으로 추가될 때의 구성원 상속 상태에 영향을 줍니다(이 명령과 이후 명령 모두에서). 구체적으로, 이 명령에서 IN ROLE 절로, 그리고 이후 명령에서 ROLE 절로 추가되는 구성원의 상속 상태를 제어해요. GRANT 명령으로 이 역할을 구성원으로 추가할 때의 기본 상속 상태로도 쓰입니다. 지정하지 않으면 INHERIT가 기본입니다. PostgreSQL 16 이전 버전에서는 상속이 그 역할의 모든 런타임 구성원 검사를 제어하는 역할 수준 속성이었습니다.
LOGIN / NOLOGIN — 역할이 로그인을 허용하는지, 즉 클라이언트 연결 중 초기 세션 인증 이름으로 주어질 수 있는지 결정해요. LOGIN 속성이 있는 역할은 사용자로 생각할 수 있습니다. 이 속성이 없는 역할은 데이터베이스 권한 관리에 유용하지만 일반적 의미의 사용자는 아니에요. 지정하지 않으면 NOLOGIN이 기본인데, CREATE ROLE이 그 대체 철자인 CREATE USER로 호출된 경우는 예외입니다.
REPLICATION / NOREPLICATION — 역할이 복제 역할인지 결정해요. 복제 모드(물리적 또는 논리적 복제)로 서버에 연결하거나 복제 슬롯을 만들·삭제하려면 역할이 이 속성(또는 슈퍼유저)을 가져야 합니다. REPLICATION 속성이 있는 역할은 매우 높은 권한을 가진 역할이므로, 실제로 복제에 쓰이는 역할에만 사용해야 해요. 지정하지 않으면 NOREPLICATION이 기본입니다. 슈퍼유저 역할이나 REPLICATION이 있는 역할만 REPLICATION을 지정할 수 있습니다.
BYPASSRLS / NOBYPASSRLS — 역할이 모든 행 수준 보안(RLS) 정책을 우회하는지 결정해요. NOBYPASSRLS가 기본입니다. 슈퍼유저 역할이나 BYPASSRLS가 있는 역할만 BYPASSRLS를 지정할 수 있어요. 참고로 pg_dump는 테이블의 모든 내용을 덤프하도록 기본적으로 row_security를 OFF로 설정합니다. pg_dump를 실행하는 사용자에게 적절한 권한이 없으면 오류가 반환됩니다. 하지만 슈퍼유저와 덤프되는 테이블의 소유자는 항상 RLS를 우회해요.
CONNECTION LIMIT connlimit — 역할이 로그인할 수 있으면 만들어낼 수 있는 동시 연결 수를 지정해요. -1(기본)은 제한 없음을 의미합니다. 참고로 이 한도에는 일반 연결만 집계되고, 준비된 트랜잭션(prepared transaction)이나 백그라운드 워커 연결은 집계되지 않아요.
[ ENCRYPTED ] PASSWORD 'password' / PASSWORD NULL — 역할의 비밀번호를 설정해요. (비밀번호는 LOGIN 속성이 있는 역할에만 유용하지만, 없어도 정의할 수 있습니다.) 비밀번호 인증을 쓸 계획이 없으면 이 옵션을 생략할 수 있어요. 비밀번호를 지정하지 않으면 null로 설정되고 그 사용자에 대한 비밀번호 인증은 항상 실패합니다. null 비밀번호는 PASSWORD NULL로 명시적으로 쓸 수도 있어요. 참고로 빈 문자열을 지정해도 비밀번호가 null로 설정되지만, PostgreSQL 버전 10 이전에는 그렇지 않았습니다. 초기 버전에서는 빈 문자열이 인증 방법과 정확한 버전에 따라 쓰일 수도 있고 아닐 수도 있었으며 libpq는 어쨌든 그것을 거부했어요. 이런 모호함을 피하려면 빈 문자열 지정을 피해야 합니다. 비밀번호는 시스템 카탈로그에 항상 암호화되어 저장됩니다. ENCRYPTED 키워드는 효과가 없지만 역호환성을 위해 받아들여져요. 암호화 방법은 구성 파라미터 password_encryption으로 결정됩니다. 제시된 비밀번호 문자열이 이미 MD5-암호화 또는 SCRAM-암호화 형식이면 password_encryption과 무관하게 그대로 저장됩니다(시스템이 지정된 암호화된 비밀번호 문자열을 다른 형식으로 암호화하기 위해 복호화할 수 없기 때문). 이는 덤프/복원 중 암호화된 비밀번호를 다시 로드할 수 있게 합니다. 경고: MD5-암호화 비밀번호 지원은 폐기 예정이며 향후 PostgreSQL 릴리스에서 제거될 예정입니다. 다른 비밀번호 유형으로 마이그레이션하는 방법은 20.5절을 참고하세요.
VALID UNTIL 'timestamp' — 역할의 비밀번호가 더 이상 유효하지 않은 날짜와 시간을 설정해요. 이 절을 생략하면 비밀번호는 항상 유효합니다.
IN ROLE role_name — 새 역할을 지정한 기존 역할들의 구성원으로 자동 추가하게 해요. 새 구성원은 SET 옵션이 켜지고 ADMIN 옵션이 꺼집니다. NOINHERIT를 지정하지 않으면 INHERIT 옵션이 켜져요.
ROLE role_name — 지정한 기존 역할(들)을 새 역할의 구성원으로 SET 옵션을 켠 채 자동 추가하게 해요. 이는 사실상 새 역할을 '그룹'으로 만듭니다. 이 절에서 역할 수준 INHERIT 속성을 가진 역할은 새 구성원에서 INHERIT 옵션이 켜집니다. 새 구성원은 ADMIN 옵션이 꺼져 있어요.
ADMIN role_name — ROLE과 같은 효과지만, 명명된 역할이 ADMIN이 켜진 채 새 역할의 구성원으로 추가되어 새 역할의 구성원 자격을 다른 사람에게 부여할 권리를 줍니다.
SYSID uid — 무시되지만 역호환성을 위해 받아들여집니다.

주의 사항 (Notes)

ALTER ROLE로 역할의 속성을 바꾸고 DROP ROLE로 역할을 제거하세요. CREATE ROLE이 지정한 모든 속성은 이후 ALTER ROLE 명령으로 수정할 수 있습니다.

그룹으로 쓰이는 역할의 구성원을 추가·제거하는 좋은 방법은 GRANT와 REVOKE를 쓰는 것입니다.

VALID UNTIL 절은 비밀번호에 대한 만료 시간만 정의하지, 역할 자체에 대한 것은 아니에요. 특히 만료 시간은 비밀번호 기반이 아닌 인증 방법으로 로그인할 때는 적용되지 않습니다.

여기 정의된 역할 속성은 상속 불가(inheritable)가 아니에요. 즉, 예를 들어 CREATEDB가 있는 역할의 구성원이어도, 구성원 부여가 INHERIT 옵션을 가졌더라도 구성원이 새 데이터베이스를 만들 수는 없습니다. 물론 구성원 부여가 SET 옵션을 가지면 구성원 역할은 SET ROLE로 createdb 역할이 된 뒤 새 데이터베이스를 만들 수 있어요.

IN ROLE, ROLE, ADMIN 절이 만든 구성원 부여는 이 명령을 실행하는 역할을 부여자(grantor)로 가집니다.

INHERIT 속성은 역호환성 때문에 기본입니다. 이전 PostgreSQL 릴리스에서 사용자는 항상 자신이 구성원인 그룹의 모든 권한에 접근할 수 있었기 때문이에요. 하지만 NOINHERIT는 SQL 표준이 규정한 의미에 더 가깝습니다.

PostgreSQL에는 CREATE ROLE과 같은 기능(실제로는 이 명령을 호출함)을 갖지만 명령 셸에서 실행할 수 있는 createuser 프로그램이 포함되어 있어요.

CONNECTION LIMIT 옵션은 대략적으로만 적용됩니다. 역할에 단 하나의 연결 '슬롯'만 남아 있을 때 두 개의 새 세션이 거의 동시에 시작하면 둘 다 실패할 수 있습니다. 또한 슈퍼유저에게는 이 한도가 절대 적용되지 않아요.

이 명령으로 암호화되지 않은 비밀번호를 지정할 때는 주의해야 합니다. 비밀번호가 평문으로 서버에 전송되고, 클라이언트의 명령 기록이나 서버 로그에 기록될 수도 있어요. 하지만 createuser 명령은 비밀번호를 암호화해 전송합니다. 또한 psql에는 나중에 안전하게 비밀번호를 바꾸는 데 쓸 수 있는 \password 명령이 있습니다.

예제 (Examples)

로그인할 수 있지만 비밀번호는 없는 역할 만들기:

CREATE ROLE jonathan LOGIN;

비밀번호가 있는 역할 만들기:

CREATE USER davide WITH PASSWORD 'jw8s0F4';

(CREATE USER는 LOGIN을 암시한다는 점만 빼고 CREATE ROLE과 같습니다.)

2004년 말까지 유효한 비밀번호를 가진 역할 만들기. 2005년이 한 초 지나면 비밀번호는 더 이상 유효하지 않아요.

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

데이터베이스를 만들고 역할을 관리할 수 있는 역할 만들기:

CREATE ROLE admin WITH CREATEDB CREATEROLE;

호환성 (Compatibility)

CREATE ROLE 문은 SQL 표준에 있지만, 표준은 다음 문법만 요구합니다:

CREATE ROLE name [ WITH ADMIN role_name ]

여러 초기 관리자와 CREATE ROLE의 다른 모든 옵션은 PostgreSQL 확장이에요.

SQL 표준은 사용자와 역할의 개념을 정의하지만 둘을 별개의 개념으로 보고, 사용자를 정의하는 모든 명령은 각 데이터베이스 구현이 지정하도록 남겨둡니다. PostgreSQL에서는 사용자와 역할을 한 종류의 주체로 통합하기로 했어요. 그래서 역할은 표준보다 훨씬 많은 선택 속성을 가집니다.

SQL 표준이 규정한 동작은, SQL 표준 사용자를 NOINHERIT 옵션의 PostgreSQL 역할로 만들고 SQL 표준 역할을 INHERIT 옵션의 PostgreSQL 역할로 만들어 가장 가깝게 근사할 수 있어요.

USER 절은 ROLE과 같은 동작이지만 폐기되었습니다:

USER role_name [, ...]

IN GROUP 절은 IN ROLE과 같은 동작이지만 폐기되었습니다:

IN GROUP role_name [, ...]

함께 보기 (See Also)

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

더 알아보기 (Learn more)

ALTER ROLE: 역할의 속성을 변경하는 명령.
DROP ROLE: 역할을 제거하는 명령.
GRANT: 역할 구성원 자격과 권한을 부여하는 명령.