ALTER FOREIGN TABLE — 외부 테이블 정의 변경하기

ALTER FOREIGN TABLE은 이미 존재하는 외부 테이블(foreign table)의 정의를 바꾸는 명령이에요. 외부 테이블은 PostgreSQL 안에 정의되어 있지만 실제 데이터는 외부 데이터 소스에 있는 테이블이죠. 컬럼·제약·옵션을 추가/제거/변경하거나 소유자·스키마를 바꿀 때 씁니다.

출처: PostgreSQL 문서

본문

시놉시스 (Synopsis)

ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] name [ * ]
    action [, ... ]
ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] name [ * ]
    RENAME [ COLUMN ] column_name TO new_column_name
ALTER FOREIGN TABLE [ IF EXISTS ] name
    RENAME TO new_name
ALTER FOREIGN TABLE [ IF EXISTS ] name
    SET SCHEMA new_schema

where action is one of:

    ADD [ COLUMN ] [ IF NOT EXISTS ] column_name data_type [ COLLATE collation ] [ column_constraint [ ... ] ]
    DROP [ COLUMN ] [ IF EXISTS ] column_name [ RESTRICT | CASCADE ]
    ALTER [ COLUMN ] column_name [ SET DATA ] TYPE data_type [ COLLATE collation ]
    ALTER [ COLUMN ] column_name SET DEFAULT expression
    ALTER [ COLUMN ] column_name DROP DEFAULT
    ALTER [ COLUMN ] column_name { SET | DROP } NOT NULL
    ALTER [ COLUMN ] column_name SET STATISTICS integer
    ALTER [ COLUMN ] column_name SET ( attribute_option = value [, ... ] )
    ALTER [ COLUMN ] column_name RESET ( attribute_option [, ... ] )
    ALTER [ COLUMN ] column_name SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT }
    ALTER [ COLUMN ] column_name OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ])
    ADD table_constraint [ NOT VALID ]
    VALIDATE CONSTRAINT constraint_name
    DROP CONSTRAINT [ IF EXISTS ]  constraint_name [ RESTRICT | CASCADE ]
    DISABLE TRIGGER [ trigger_name | ALL | USER ]
    ENABLE TRIGGER [ trigger_name | ALL | USER ]
    ENABLE REPLICA TRIGGER trigger_name
    ENABLE ALWAYS TRIGGER trigger_name
    SET WITHOUT OIDS
    INHERIT parent_table
    NO INHERIT parent_table
    OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
    OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ])

설명 (Description)

ALTER FOREIGN TABLE은 기존 외부 테이블의 정의를 변경해요. 여러 하위 형식이 있어요.

ADD [ COLUMN ] [ IF NOT EXISTS ] — 이 형식은 CREATE FOREIGN TABLE과 같은 문법으로 외부 테이블에 새 컬럼을 추가해요. IF NOT EXISTS를 지정하고 같은 이름의 컬럼이 이미 있으면 오류가 발생하지 않아요. 일반 테이블에 컬럼을 추가하는 경우와 달리 기본 저장소에는 아무것도 일어나지 않아요. 이 동작은 단지 새 컬럼이 이제 외부 테이블을 통해 접근 가능하다고 선언할 뿐이에요.
DROP [ COLUMN ] [ IF EXISTS ] — 이 형식은 외부 테이블에서 컬럼을 제거해요. 테이블 밖에서 그 컬럼에 의존하는 것(예: 뷰)이 있으면 CASCADE를 말해야 해요. IF EXISTS를 지정하고 컬럼이 없으면 오류가 발생하지 않아요. 이 경우 대신 notice가 발행돼요.
SET DATA TYPE — 이 형식은 외부 테이블 컬럼의 타입을 변경해요. 마찬가지로 어떤 기본 저장소에도 영향을 주지 않아요. 이 동작은 PostgreSQL이 그 컬럼이 갖고 있다고 믿는 타입만 바꿔요.
SET/DROP DEFAULT — 이 형식은 컬럼의 기본값을 설정하거나 제거해요. 기본값은 이후의 INSERT나 UPDATE 명령에서만 적용되며 이미 테이블에 있는 행을 바꾸지는 않아요.
SET/DROP NOT NULL — 컬럼이 null 값을 허용하거나 허용하지 않도록 표시해요.
SET STATISTICS — 이 형식은 이후 ANALYZE 작업에 대한 컬럼별 통계 수집 목표를 설정해요. 자세한 내용은 ALTER TABLE의 비슷한 형식을 보세요.
SET ( attribute_option = value [, ... ] ), RESET ( attribute_option [, ... ] ) — 이 형식은 속성별 옵션을 설정하거나 재설정해요. 자세한 내용은 ALTER TABLE의 비슷한 형식을 보세요.
SET STORAGE — 이 형식은 컬럼의 저장 모드를 설정해요. 자세한 내용은 ALTER TABLE의 비슷한 형식을 보세요. 단, 테이블의 외부 데이터 래퍼가 저장 모드에 주의를 기울이기로 선택하지 않는 한 저장 모드는 효과가 없어요.
ADD table_constraint [ NOT VALID ] — 이 형식은 CREATE FOREIGN TABLE과 같은 문법으로 외부 테이블에 새 제약 조건을 추가해요. 현재 CHECK와 NOT NULL 제약 조건만 지원돼요. 일반 테이블에 제약 조건을 추가할 때와 달리 제약 조건이 올바른지 검증하는 일은 아무것도 하지 않아요. 대신 이 동작은 외부 테이블의 모든 행에 어떤 새 조건이 성립한다고 가정되어야 한다고 선언할 뿐이에요. (CREATE FOREIGN TABLE의 논의를 보세요.) 제약 조건이 NOT VALID로 표시되면(CHECK 경우에만 허용), 성립한다고 가정되지 않고 가능한 미래 사용을 위해 기록만 돼요.
VALIDATE CONSTRAINT — 이 형식은 이전에 NOT VALID로 표시된 제약 조건을 유효한 것으로 표시해요. 제약 조건을 검증하는 동작은 없지만, 이후 쿼리는 그것이 성립한다고 가정해요.
DROP CONSTRAINT [ IF EXISTS ] — 이 형식은 외부 테이블의 지정된 제약 조건을 제거해요. IF EXISTS를 지정하고 제약 조건이 없으면 오류가 발생하지 않아요. 이 경우 대신 notice가 발행돼요.
DISABLE/ENABLE [ REPLICA | ALWAYS ] TRIGGER — 이 형식은 외부 테이블에 속한 트리거의 발동을 구성해요. 자세한 내용은 ALTER TABLE의 비슷한 형식을 보세요.
SET WITHOUT OIDS — oid 시스템 컬럼을 제거하기 위한 하위 호환성 문법이에요. oid 시스템 컬럼은 더 이상 추가할 수 없으므로 이 형식은 아무 효과가 없어요.
INHERIT parent_table — 이 형식은 대상 외부 테이블을 지정된 부모 테이블의 새 자식으로 추가해요. 자세한 내용은 ALTER TABLE의 비슷한 형식을 보세요.
NO INHERIT parent_table — 이 형식은 지정된 부모 테이블의 자식 목록에서 대상 외부 테이블을 제거해요.
OWNER — 이 형식은 외부 테이블의 소유자를 지정된 사용자로 바꿔요.
OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] ) — 외부 테이블이나 그 컬럼 중 하나의 옵션을 변경해요. ADD, SET, DROP이 수행할 동작을 지정해요. 동작을 명시하지 않으면 ADD로 간주돼요. 중복 옵션 이름은 허용되지 않아요(테이블 옵션과 컬럼 옵션이 같은 이름을 갖는 건 괜찮아요). 옵션 이름과 값은 외부 데이터 래퍼 라이브러리로도 검사돼요.
RENAME — RENAME 형식은 외부 테이블의 이름이나 외부 테이블의 개별 컬럼 이름을 바꿔요.
SET SCHEMA — 이 형식은 외부 테이블을 다른 스키마로 옮겨요.

RENAME과 SET SCHEMA를 제외한 모든 동작은 병렬로 적용할 여러 변경 목록으로 결합할 수 있어요. 예를 들어 단일 명령으로 여러 컬럼을 추가하거나 여러 컬럼의 타입을 변경할 수 있어요.

명령을 ALTER FOREIGN TABLE IF EXISTS ...로 쓰고 외부 테이블이 존재하지 않으면 오류가 발생하지 않아요. 이 경우 notice가 발행돼요.

ALTER FOREIGN TABLE을 쓰려면 테이블의 소유자여야 해요. 외부 테이블의 스키마를 바꾸려면 새 스키마에 대한 CREATE 권한도 있어야 하고, 소유자를 바꾸려면 새 소유 역할로 SET ROLE할 수 있어야 하며 그 역할이 테이블의 스키마에 CREATE 권한을 가져야 해요. (이런 제약은 소유자를 바꾸는 게 테이블을 드롭하고 다시 만드는 것 이상의 일을 하지 못하게 막아 주는 거예요. 다만 슈퍼유저는 어떤 테이블이든 소유권을 바꿀 수 있어요.) 컬럼을 추가하거나 컬럼 타입을 바꾸려면 데이터 타입에 대한 USAGE 권한도 있어야 해요.

매개변수 (Parameters)

name — 변경할 기존 외부 테이블의 이름(가능하면 스키마 한정)이에요. 테이블 이름 앞에 ONLY를 지정하면 그 테이블만 변경돼요. ONLY를 지정하지 않으면 테이블과 그 모든 하위 테이블(있으면)이 변경돼요. 선택적으로 테이블 이름 뒤에 *를 지정해 하위 테이블이 포함됨을 명시적으로 나타낼 수 있어요.
column_name — 새 컬럼 또는 기존 컬럼의 이름이에요.
new_column_name — 기존 컬럼의 새 이름이에요.
new_name — 테이블의 새 이름이에요.
data_type — 새 컬럼의 데이터 타입, 또는 기존 컬럼의 새 데이터 타입이에요.
table_constraint — 외부 테이블의 새 테이블 제약 조건이에요.
constraint_name — 제거할 기존 제약 조건의 이름이에요.
CASCADE — 제거된 컬럼이나 제약 조건에 의존하는 객체(예: 그 컬럼을 참조하는 뷰)를, 그리고 다시 그 객체들에 의존하는 모든 객체를 자동으로 제거해요(5.15절 참고).
RESTRICT — 의존하는 객체가 있으면 컬럼이나 제약 조건 제거를 거부해요. 기본 동작이에요.
trigger_name — 비활성화하거나 활성화할 단일 트리거의 이름이에요.
ALL — 외부 테이블에 속한 모든 트리거를 비활성화하거나 활성화해요. (트리거 중 내부적으로 생성된 트리거가 있으면 슈퍼유저 권한이 필요해요. 핵심 시스템은 외부 테이블에 그런 트리거를 추가하지 않지만, 추가 확장 코드는 할 수 있어요.)
USER — 내부적으로 생성된 트리거를 제외한 외부 테이블의 모든 트리거를 비활성화하거나 활성화해요.
parent_table — 이 외부 테이블과 연관시키거나 연관을 끊을 부모 테이블이에요.
new_owner — 테이블의 새 소유자 사용자 이름이에요.
new_schema — 테이블이 옮겨질 스키마의 이름이에요.

참고 (Notes)

키워드 COLUMN은 노이즈라 생략할 수 있어요.

ADD COLUMN이나 DROP COLUMN으로 컬럼을 추가·제거하거나, NOT NULL/CHECK 제약 조건을 추가하거나, SET DATA TYPE으로 컬럼 타입을 바꿀 때 외부 서버와의 일관성은 확인되지 않아요. 테이블 정의가 원격 측과 일치하는지 확인하는 건 사용자의 책임이에요.

유효한 매개변수에 대한 더 자세한 설명은 CREATE FOREIGN TABLE을 참고하세요.

예제 (Examples)

컬럼을 not-null로 표시하려면:

ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;

외부 테이블의 옵션을 바꾸려면:

ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'value2', DROP opt3);

호환성 (Compatibility)

ADD, DROP, SET DATA TYPE 형식은 SQL 표준을 따르며, 나머지 형식은 SQL 표준의 PostgreSQL 확장이에요. 또한 단일 ALTER FOREIGN TABLE 명령에서 둘 이상의 조작을 지정할 수 있는 능력도 확장이에요.

ALTER FOREIGN TABLE DROP COLUMN은 외부 테이블의 유일한 컬럼을 버려 0-컬럼 테이블을 만들 수 있어요. 이것은 0-컬럼 외부 테이블을 허용하지 않는 SQL의 확장이에요.

더 알아보기 (Learn more)

CREATE FOREIGN TABLE — 새 외부 테이블을 만드는 명령이에요.
DROP FOREIGN TABLE — 외부 테이블을 삭제하는 명령이에요.
ALTER TABLE — 일반 테이블의 정의를 바꾸는 명령이에요.