Azure Cosmos DB for PostgreSQL 함수

아티클
10/27/2023

적용 대상: PostgreSQL용 Azure Cosmos DB(Citus 데이터베이스 확장에서 PostgreSQL로 구동 )

이 섹션에는 Azure Cosmos DB for PostgreSQL에서 제공하는 사용자 정의 함수에 대한 참조 정보가 포함되어 있습니다. 이 함수는 Azure Cosmos DB for PostgreSQL에 분산 기능을 제공하는 데 도움이 됩니다.

참고 항목

이전 버전의 Citus 엔진을 실행하는 클러스터는 이 페이지에 나열된 모든 함수를 제공하지 않을 수 있습니다.

테이블 및 분할된 데이터베이스 DDL

citus_schema_distribute

기존 일반 스키마를 분산 스키마로 변환합니다. 분산 스키마는 개별 공동 배치 그룹과 자동 연결됩니다. 이러한 스키마에서 만든 테이블은 분할 키 없이 공동 배치된 분산 테이블로 변환됩니다. 스키마를 배포하는 프로세스는 자동으로 할당하고 클러스터의 기존 노드로 이동합니다.

인수

schemaname: 배포해야 하는 스키마의 이름입니다.

반환 값

해당 없음

예시

SELECT citus_schema_distribute('tenant_a');
SELECT citus_schema_distribute('tenant_b');
SELECT citus_schema_distribute('tenant_c');

자세한 예제는 마이크로 서비스에 대한 디자인 방법을 참조하세요.

citus_schema_undistribute

기존 분산 스키마를 다시 일반 스키마로 변환합니다. 이 프로세스로 인해 테이블과 데이터가 현재 노드에서 클러스터의 코디네이터 노드로 다시 이동됩니다.

인수

schemaname: 배포해야 하는 스키마의 이름입니다.

반환 값

해당 없음

예시

SELECT citus_schema_undistribute('tenant_a');
SELECT citus_schema_undistribute('tenant_b');
SELECT citus_schema_undistribute('tenant_c');

자세한 예제는 마이크로 서비스에 대한 디자인 방법을 참조하세요.

create_distributed_table

create_distributed_table() 함수는 분산 테이블을 정의하고, 해시 분산 테이블인 경우 분할된 데이터베이스를 만드는 데 사용됩니다. 이 함수는 테이블 이름, 배포 열 및 선택적 배포 메서드를 사용하고 적절한 메타데이터를 삽입하여 테이블을 분산된 것으로 표시합니다. 분포 메서드가 지정되지 않은 경우 함수는 기본적으로 '해시' 분포로 설정됩니다. 테이블이 해시 분산된 경우 이 함수는 분할된 데이터베이스 수 및 분할된 데이터베이스 복제본(replica)tion 요소 구성 값에 따라 작업자 분할된 데이터베이스도 만듭니다. 테이블에 행이 포함된 경우 작업자 노드에 자동으로 분산됩니다.

이 함수는 master_create_distributed_table() 다음에 master_create_worker_shards() 사용을 대체합니다.

인수

table_name: 배포해야 하는 테이블의 이름입니다.

distribution_column: 테이블이 배포될 열입니다.

distribution_type: (선택 사항) 테이블이 배포되는 방법입니다. 허용되는 값은 추가 또는 해시이며 기본값은 '해시'입니다.

colocate_with: (선택 사항) 다른 테이블의 공동 배치 그룹에 현재 테이블을 포함합니다. 기본적으로 테이블은 동일한 유형의 열로 분산되고 분할된 데이터베이스 수와 복제 계수가 동일한 경우에 공동 배치됩니다. 가능한 값 colocate_with 은 defaultnone 새 공동 배치 그룹을 시작하거나 해당 테이블과 공동 배치할 다른 테이블의 이름입니다. (테이블 공동 배치를 참조하세요.)

기본값 colocate_with 은 암시적 공동 배치를 수행합니다. 공동 배치는 테이블이 관련되거나 조인될 때 매우 유용할 수 있습니다. 그러나 두 테이블이 관련이 없지만 배포 열에 동일한 데이터 형식을 사용하는 경우 실수로 공동 배치하면 분할된 데이터베이스 리밸런싱 중에 성능이 저하될 수 있습니다. 테이블 분할된 데이터베이스가 불필요하게 “계단식”으로 함께 이동됩니다.

새 분산 테이블이 다른 테이블과 관련이 없는 경우 colocate_with => 'none'을 지정하는 것이 가장 좋습니다.

shard_count: (선택 사항) 새 분산 테이블에 대해 만들 분할된 데이터베이스 수입니다. 지정할 shard_count 때는 none 이외의 값을 colocate_with 지정할 수 없습니다. 기존 테이블 또는 공동 배치 그룹의 분할된 데이터베이스 수를 변경하려면 alter_distributed_table 함수를 사용합니다.

shard_count의 가능한 값은 1~64000 사이입니다. 최적 값 선택에 관한 참고 자료는 분할된 데이터베이스 수를 참조하세요.

반환 값

해당 없음

예시

이 예제에서는 github_events 테이블이 repo_id 열의 해시로 배포되어야 함을 데이터베이스에 알립니다.

SELECT create_distributed_table('github_events', 'repo_id');

-- alternatively, to be more explicit:
SELECT create_distributed_table('github_events', 'repo_id',
                                colocate_with => 'github_repo');

create_distributed_table_concurrently

이 함수는 create_distributed_function 과 인터페이스와 용도가 동일하지만 테이블 배포 중에 쓰기를 차단하지 않습니다.

그러나 create_distributed_table_concurrently에는 다음과 같은 몇 가지 제한 사항이 있습니다.

트랜잭션 블록에는 함수를 사용할 수 없습니다. 즉, 한 번에 하나의 테이블만 배포할 수 있습니다. (하지만 시간 분할 테이블에서 함수를 사용할 수 있습니다.)
테이블이 외래 키에서 참조되거나 또 다른 로컬 테이블을 참조하는 경우 create_distributed_table_concurrently를 사용할 수 없습니다. 그러나 테이블을 참조하는 외래 키가 작동하며 테이블 배포가 완료된 후 다른 분산 테이블에 대한 외래 키를 만들 수 있습니다.
테이블에 기본 키 또는 복제본 ID가 없는 경우 업데이트 및 삭제 명령은 논리 복제에 대한 제한으로 인해 테이블 배포 중에 실패합니다.

truncate_local_data_after_distributing_table

테이블을 배포한 후 모든 로컬 행을 잘라내고, 오래된 로컬 레코드로 인해 제약 조건이 실패하지 않도록 방지합니다. 잘림은 지정된 테이블에 대한 외래 키가 있는 테이블까지 연속됩니다. 참조 테이블 자체가 배포되지 않은 경우에는 참조 무결성을 보호하기 위해 참조 테이블이 배포될 때까지 잘림이 금지됩니다.

ERROR:  cannot truncate a table referenced in a foreign key constraint by a local table

분산 테이블의 경우 행(있는 경우)이 배포 중에 작업자 노드에 복사되기 때문에 로컬 코디네이터 노드 테이블 데이터를 잘라내도 안전합니다.

인수

table_name: 코디네이터 노드에서 해당 로컬 항목을 잘라내야 하는 분산 테이블의 이름입니다.

반환 값

해당 없음

예시

-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');

create_reference_table

create_reference_table() 함수는 작은 참조 테이블 또는 차원 테이블을 정의하는 데 사용됩니다. 이 함수는 테이블 이름을 사용하고 모든 작업자 노드에 복제본(replica) 분할된 데이터베이스가 하나만 있는 분산 테이블을 만듭니다.

인수

table_name: 배포해야 하는 작은 차원 테이블 또는 참조 테이블의 이름입니다.

반환 값

해당 없음

예시

이 예제에서는 국가 테이블을 참조 테이블로 정의해야 하며 데이터베이스에 알릴 수 있습니다.

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Citus 메타데이터에 로컬 Postgres 테이블을 추가합니다. 이 함수의 주요 사용 사례는 클러스터의 모든 노드에서 코디네이터의 로컬 테이블에 액세스할 수 있도록 하는 것입니다. 로컬 테이블과 연결된 데이터는 코디네이터에 유지되며 해당 스키마 및 메타데이터만 작업자에게 전송됩니다.

메타데이터에 로컬 테이블을 추가하면 약간의 비용이 발생합니다. 테이블을 추가할 때 Citus는 파티션 테이블에서 추적해야 합니다. 메타데이터에 추가된 로컬 테이블은 참조 테이블과 동일한 제한 사항을 상속합니다.

테이블의 배포를 제거하면 Citus는 메타데이터에서 결과 로컬 테이블을 제거하므로 해당 테이블에 대한 이러한 제한 사항이 제거됩니다.

인수

table_name: Citus 메타데이터에 추가할 코디네이터의 테이블 이름입니다.

cascade_via_foreign_keys: (선택 사항) 이 인수가 "true"로 설정되면 citus_add_local_table_to_metadata 지정된 테이블과 외래 키 관계에 있는 다른 테이블을 메타데이터에 자동으로 추가합니다. 이 매개 변수는 많은 테이블에 영향을 줄 수 있으므로 사용 시 주의해야 합니다.

반환 값

해당 없음

예시

이 예제에서는 국가 테이블이 모든 노드에서 액세스할 수 있는 코디네이터-로컬 테이블로 정의되어야 한다고 데이터베이스에 알릴 수 있습니다.

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

alter_distributed_table() 함수를 사용하여 분산 테이블의 배포 열, 분할된 데이터베이스 수 또는 공동 배치 속성을 변경할 수 있습니다.

인수

table_name 변경할 테이블의 이름입니다.

distribution_column: (선택 사항) 새 배포 열의 이름입니다.

shard_count: (선택 사항) 새 분할된 데이터베이스 수입니다.

colocate_with: (선택 사항) 현재 분산 테이블과 공동 배치될 테이블입니다. 사용할 수 있는 값은 default, 새 공동 배치 그룹을 시작하기 위한 none 또는 공동 배치할 다른 테이블의 이름입니다. (테이블 공동 배치를 참조하세요.)

cascade_to_colocated: (선택 사항) 이 인수를 “true”로 설정하면 이전에 테이블과 공동 배치된 모든 테이블에 shard_count 및 colocate_with 변경 내용이 적용되고 공동 배치가 유지됩니다. “false”이면 이 테이블의 현재 공동 배치가 중단됩니다.

반환 값

해당 없음

예시

-- change distribution column
SELECT alter_distributed_table('github_events', distribution_column:='event_id');

-- change shard count of all tables in colocation group
SELECT alter_distributed_table('github_events', shard_count:=6, cascade_to_colocated:=true);

-- change colocation
SELECT alter_distributed_table('github_events', colocate_with:='another_table');

update_distributed_table_colocation

update_distributed_table_colocation() 함수는 분산 테이블의 공동 배치를 업데이트하는 데 사용됩니다. 이 함수를 사용하여 분산 테이블의 공동 배치를 중단할 수도 있습니다. 배포 열이 동일한 형식인 경우 Azure Cosmos DB for PostgreSQL은 두 테이블을 암시적으로 공동 배치합니다. 이 기능은 테이블이 관련되어 있고 일부 조인을 수행하는 경우에 유용할 수 있습니다. 테이블 A와 B가 공동 배치되고 테이블 A가 리밸런싱되는 경우 테이블 B도 리밸런싱됩니다. 테이블 B에 복제본 ID가 없으면 리밸런싱에 실패합니다. 따라서 이 함수는 해당 경우에 암시적 공동 배치를 중단하는 데 유용할 수 있습니다.

이 함수는 데이터를 물리적으로 이동하지 않습니다.

인수

table_name: 업데이트할 테이블 공동 배치의 이름입니다.

colocate_with: 테이블과 공동 배치해야 하는 테이블입니다.

테이블 공동 배치를 중단하려는 경우 colocate_with => 'none'을 지정해야 합니다.

반환 값

해당 없음

예시

이 예제에서는 테이블 A의 공동 배치가 테이블 B의 공동 배치로 업데이트되는 것을 보여 줍니다.

SELECT update_distributed_table_colocation('A', colocate_with => 'B');

공동 배치를 중단하려는 경우 테이블 A와 테이블 B가 공동 배치되었다고(암시적으로) 가정합니다.

SELECT update_distributed_table_colocation('A', colocate_with => 'none');

이제 테이블 A, 테이블 B, 테이블 C, 테이블 D가 공동 배치되었으며 테이블 A와 테이블 B, 테이블 C와 테이블 D를 함께 배치하려 한다고 가정합니다.

SELECT update_distributed_table_colocation('C', colocate_with => 'none');
SELECT update_distributed_table_colocation('D', colocate_with => 'C');

none이라는 해시 분산 테이블이 있고 공동 배치를 업데이트하려는 경우 다음을 수행할 수 있습니다.

SELECT update_distributed_table_colocation('"none"', colocate_with => 'some_other_hash_distributed_table');

undistribute_table

undistribute_table() 함수는 create_distributed_table 또는 create_reference_table 작업을 실행 취소합니다. 배포를 해제하면 분할된 데이터베이스의 모든 데이터가 코디네이터 노드의 로컬 테이블로 다시 이동한 다음(데이터가 수용될 수 있다고 가정), 분할된 데이터베이스가 삭제됩니다.

Azure Cosmos DB for PostgreSQL은 cascade_via_foreign_keys 인수가 true로 설정되지 않은 경우 외래 키가 있거나 외래 키로 참조된 테이블의 배포를 해제하지 않습니다. 이 인수가 false이거나 생략된 경우 배포 해제 전에 위반하는 외래 키 제약 조건을 수동으로 삭제해야 합니다.

인수

table_name: 배포 해제할 분산 테이블 또는 참조 테이블의 이름입니다.

cascade_via_foreign_keys: (선택 사항) 이 인수가 “true”로 설정된 경우 undistribute_table은 외래 키를 통해 table_name과 관련된 모든 테이블의 배포도 해제합니다. 이 매개 변수는 많은 테이블에 영향을 줄 수 있으므로 사용 시 주의해야 합니다.

반환 값

해당 없음

예시

이 예제에서는 github_events 테이블을 배포했다가 배포 해제합니다.

-- first distribute the table
SELECT create_distributed_table('github_events', 'repo_id');

-- undo that and make it local again
SELECT undistribute_table('github_events');

create_distributed_function

코디네이터 노드에서 작업자로 함수를 전파하고 분산 실행을 위해 표시합니다. 분산 함수가 코디네이터에서 호출되면 Azure Cosmos DB for PostgreSQL은 “배포 인수”의 값을 사용하여 함수를 실행할 작업자 노드를 선택합니다. 작업자에서 함수를 실행하면 병렬 처리가 증가하며, 대기 시간을 낮추기 위해 분할된 데이터베이스의 데이터에 코드를 더 가깝게 만들 수 있습니다.

Postgres 검색 경로는 분산 함수 실행 중에 코디네이터에서 작업자로 전파되지 않으므로 분산 함수 코드에서 데이터베이스 개체 이름을 정규화해야 합니다. 또한 함수에서 내보낸 알림은 사용자에게 표시되지 않습니다.

인수

function_name: 배포할 함수의 이름입니다. 여러 함수가 PostgreSQL에서 동일한 이름을 가질 수 있으므로 이름에는 함수의 매개 변수 형식이 괄호 안에 포함되어야 합니다. 예를 들어, 'foo(int)'는 'foo(int, text)'와 다릅니다.

distribution_arg_name:(선택 사항) 배포 시 사용할 인수 이름입니다. 편의를 위해(또는 함수 인수에 이름이 없는 경우) '$1'과 같은 위치 자리 표시자가 허용됩니다. 이 매개 변수를 지정하지 않으면 function_name이라는 함수만 작업자에 생성됩니다. 나중에 작업자 노드가 추가되면 함수도 자동으로 만들어집니다.

colocate_with: (선택 사항) 분산 함수가 분산 테이블(또는 보다 일반적으로 공동 배치 그룹)을 읽거나 쓰는 경우 colocate_with 매개 변수를 사용하여 해당 테이블의 이름을 지정해야 합니다. 그런 다음 함수의 각 호출은 관련 분할된 데이터베이스를 포함하는 작업자 노드에서 실행됩니다.

반환 값

해당 없음

예시

-- an example function which updates a hypothetical
-- event_responses table which itself is distributed by event_id
CREATE OR REPLACE FUNCTION
  register_for_event(p_event_id int, p_user_id int)
RETURNS void LANGUAGE plpgsql AS $fn$
BEGIN
  INSERT INTO event_responses VALUES ($1, $2, 'yes')
  ON CONFLICT (event_id, user_id)
  DO UPDATE SET response = EXCLUDED.response;
END;
$fn$;

-- distribute the function to workers, using the p_event_id argument
-- to determine which shard each invocation affects, and explicitly
-- colocating with event_responses which the function updates
SELECT create_distributed_function(
  'register_for_event(int, int)', 'p_event_id',
  colocate_with := 'event_responses'
);

alter_columnar_table_set

alter_columnar_table_set() 함수는 열 형식 테이블의 설정을 변경합니다. 열이 아닌 테이블에서 이 함수를 호출하면 오류가 발생합니다. 테이블 이름을 제외한 모든 인수는 선택 사항입니다.

모든 열 형식 테이블에 대한 현재 옵션을 보려면 다음 표를 참조하세요.

SELECT * FROM columnar.options;

새로 만든 테이블의 열 형식 설정 기본값은 다음 GUC로 재정의할 수 있습니다.

columnar.compression
columnar.compression_level
columnar.stripe_row_count
columnar.chunk_row_count

인수

table_name: 열 형식 테이블의 이름입니다.

chunk_row_count: (선택 사항) 새로 삽입된 데이터의 청크당 최대 행 수입니다. 기존 데이터 청크는 변경되지 않으며 이 최대값보다 많은 행이 있을 수 있습니다. 기본값은 10000입니다.

stripe_row_count: (선택 사항) 새로 삽입된 데이터의 스트라이프당 최대 행 수입니다. 기존 데이터 줄무늬는 변경되지 않으며 이 최대값보다 많은 행이 있을 수 있습니다. 기본값은 150000입니다.

압축: (선택 사항) [none|pglz|zstd|lz4|lz4hc] 새로 삽입된 데이터의 압축 유형입니다. 기존 데이터는 다시 압축되거나 압축 해제되지 않습니다. 기본 및 제안된 값은 zstd입니다(지원이 컴파일된 경우).

compression_level: (선택 사항) 유효한 설정은 1에서 19까지입니다. 압축 방법이 선택한 수준을 지원하지 않는 경우 가장 가까운 수준이 선택됩니다.

반환 값

해당 없음

예시

SELECT alter_columnar_table_set(
  'my_columnar_table',
  compression => 'none',
  stripe_row_count => 10000);

alter_table_set_access_method

alter_table_set_access_method() 함수는 테이블의 액세스 메서드(예: 힙 또는 열 형식)를 변경합니다.

인수

table_name: 액세스 메서드를 변경할 테이블의 이름입니다.

access_method: 새 액세스 메서드의 이름입니다.

반환 값

해당 없음

예시

SELECT alter_table_set_access_method('github_events', 'columnar');

create_time_partitions

create_time_partitions() 함수는 지정된 시간 범위를 포함하도록 지정된 간격의 파티션을 만듭니다.

인수

table_name: (regclass) 새 파티션을 만들 테이블입니다. 테이블은 날짜, 타임스탬프 또는 timestamptz 형식의 한 열에서 분할되어야 합니다.

partition_interval: 새 파티션에서 범위를 설정할 때 사용할 시간 간격(예: '2 hours' 또는 '1 month')입니다.

end_at: (timestamptz) 이 시간까지 파티션을 만듭니다. 마지막 파티션에는 end_at 시점이 포함되며, 이후 파티션은 생성되지 않습니다.

start_from: (timestamptz, 선택 사항) start_from 시점이 포함되도록 첫 번째 파티션을 선택합니다. 기본값은 now()입니다.

반환 값

새 파티션을 만들어야 한 경우 true이고, 모든 파티션이 이미 있었던 경우 false입니다.

예시

-- create a year's worth of monthly partitions
-- in table foo, starting from the current time

SELECT create_time_partitions(
  table_name         := 'foo',
  partition_interval := '1 month',
  end_at             := now() + '12 months'
);

drop_old_time_partitions

drop_old_time_partitions() 함수는 간격이 지정된 타임스탬프보다 이전인 모든 파티션을 제거합니다. 이 함수를 사용하는 것 외에도 alter_old_partitions_set_access_method를 사용하여 열 형식 스토리지로 이전 파티션을 압축하는 것이 좋습니다.

인수

table_name: (regclass) 파티션을 제거할 테이블입니다. 테이블은 날짜, 타임스탬프 또는 timestamptz 형식의 한 열에서 분할되어야 합니다.

older_than: (timestamptz) 상한 범위가 older_than보다 이전이거나 같은 파티션을 삭제합니다.

반환 값

해당 없음

예시

-- drop partitions that are over a year old

CALL drop_old_time_partitions('foo', now() - interval '12 months');

alter_old_partitions_set_access_method

시계열 사용 사례에서 테이블은 시간별로 분할되는 경우가 많으며, 이전 파티션은 읽기 전용 열 형식 스토리지로 압축됩니다.

인수

parent_table_name: (regclass) 파티션을 변경할 테이블입니다. 테이블은 날짜, 타임스탬프 또는 timestamptz 형식의 한 열에서 분할되어야 합니다.

older_than: (timestamptz) 상한 범위가 older_than보다 이전이거나 같은 파티션을 변경합니다.

new_access_method: (이름) 행 기반 스토리지의 경우 '힙' 또는 열 형식 스토리지의 경우 'columnar'입니다.

반환 값

해당 없음

예시

CALL alter_old_partitions_set_access_method(
  'foo', now() - interval '6 months',
  'columnar'
);

메타데이터 / 구성 정보

get_shard_id_for_distribution_column

Azure Cosmos DB for PostgreSQL은 행의 배포 열 값과 테이블의 배포 방법을 기반으로 분산 테이블의 모든 행을 분할된 데이터베이스에 할당합니다. 대부분의 경우, 정확한 매핑은 데이터베이스 관리자가 무시할 수 있는 낮은 수준의 세부 정보입니다. 그러나 수동 데이터베이스 기본 테넌스 작업 또는 호기심을 만족시키기 위해 행의 분할된 데이터베이스를 결정하는 것이 유용할 수 있습니다. 이 함수는 get_shard_id_for_distribution_column 해시 분산, 범위 분산 및 참조 테이블에 대해 이 정보를 제공합니다. 추가 배포에서는 작동하지 않습니다.

인수

table_name: 분산 테이블입니다.

distribution_value: 배포 열의 값입니다.

반환 값

Azure Cosmos DB for PostgreSQL의 분할된 데이터베이스 ID는 지정된 테이블의 배포 열 값과 연결됩니다.

예시

SELECT get_shard_id_for_distribution_column('my_table', 4);

 get_shard_id_for_distribution_column
--------------------------------------
                               540007
(1 row)

column_to_column_name

pg_dist_partition의 partkey 열을 텍스트 열 이름으로 변환합니다. 변환은 배포 테이블의 배포 열을 결정하는 데 유용합니다.

자세한 내용은 배포 열 선택을 참조하세요.

인수

table_name: 분산 테이블입니다.

column_var_text:pg_dist_partition 테이블의 partkey 값입니다.

반환 값

'의 table_name배포 열 이름입니다.

예

-- get distribution column name for products table

SELECT column_to_column_name(logicalrelid, partkey) AS dist_col_name
  FROM pg_dist_partition
 WHERE logicalrelid='products'::regclass;

출력:

┌───────────────┐
│ dist_col_name │
├───────────────┤
│ company_id    │
└───────────────┘

citus_relation_size

지정된 분산 테이블의 모든 분할된 데이터베이스에서 사용하는 디스크 공간을 가져옵니다. 디스크 공간에 “기본 포크”의 크기는 포함되지만, 분할된 데이터베이스의 가시성 맵과 사용 가능한 공간 맵은 제외됩니다.

인수

logicalrelid: 분산 테이블의 이름입니다.

반환 값

bigint로 크기(바이트)입니다.

예시

SELECT pg_size_pretty(citus_relation_size('github_events'));

pg_size_pretty
--------------
23 MB

citus_table_size

인덱스를 제외한 지정된 분산 테이블의 모든 분할된 데이터베이스에서 사용하는 디스크 공간을 가져옵니다(TOAST, 사용 가능한 공간 맵 및 표시 유형 맵 포함).

인수

logicalrelid: 분산 테이블의 이름입니다.

반환 값

bigint로 크기(바이트)입니다.

예시

SELECT pg_size_pretty(citus_table_size('github_events'));

pg_size_pretty
--------------
37 MB

citus_total_relation_size

모든 인덱스 및 TOAST 데이터를 포함하여 지정된 분산 테이블의 모든 분할된 데이터베이스에서 사용하는 총 디스크 공간을 가져옵니다.

인수

logicalrelid: 분산 테이블의 이름입니다.

반환 값

bigint로 크기(바이트)입니다.

예시

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

pg_size_pretty
--------------
73 MB

citus_stat_statements_reset

citus_stat_statements 모든 행을 제거합니다. 이 함수는 .에서 pg_stat_statements_reset()독립적으로 작동합니다. 모든 통계를 다시 설정하려면 두 함수 모두 호출합니다.

인수

해당 없음

반환 값

없음

citus_get_active_worker_nodes

citus_get_active_worker_nodes() 함수는 활성 작업자 호스트 이름과 포트 번호의 목록을 반환합니다.

인수

해당 없음

반환 값

각 튜플에 다음 정보가 포함된 튜플 목록입니다.

node_name: 작업자 노드의 DNS 이름입니다.

node_port: 데이터베이스 서버가 수신 대기 중인 작업자 노드의 포트입니다.

예시

SELECT * from citus_get_active_worker_nodes();
 node_name | node_port
-----------+-----------
 localhost |      9700
 localhost |      9702
 localhost |      9701

(3 rows)

클러스터 관리 및 복구

master_copy_shard_placement

수정 명령 또는 DDL 작업 중에 분할 배치가 업데이트되지 않으면 비활성으로 표시됩니다. 그런 다음 master_copy_shard_placement 함수를 호출하여 정상적인 배치의 데이터를 사용하여 비활성 분할 배치를 복구할 수 있습니다.

분할을 복구하기 위해 이 함수는 먼저 비정상 분할 배치를 삭제하고 코디네이터의 스키마를 사용하여 다시 만듭니다. 분할 배치가 만들어지면 함수는 정상 배치의 데이터를 복사하고 메타데이터를 업데이트하여 새 분할 배치를 정상으로 표시합니다. 이 함수는 복구하는 동안 분할된 데이터베이스가 동시 수정으로부터 보호되도록 합니다.

인수

shard_id: 복구할 분할된 데이터베이스의 ID입니다.

source_node_name: 정상적인 분할된 데이터베이스 배치가 있는 노드(“원본” 노드)의 DNS 이름입니다.

source_node_port: 데이터베이스 서버가 수신 대기 중인 원본 작업자 노드의 포트입니다.

target_node_name: 잘못된 분할된 데이터베이스 배치가 있는 노드(“대상” 노드)의 DNS 이름입니다.

target_node_port: 데이터베이스 서버가 수신 대기 중인 대상 작업자 노드의 포트입니다.

반환 값

해당 없음

예시

아래 예제에서는 포트 5432의 ‘bad_host’에서 실행 중인 데이터베이스 서버에 있는 분할된 데이터베이스 12345의 비활성 분할된 데이터베이스 배치를 복구합니다. 복구하기 위해 포트 5432의 ‘good_host’에서 실행 중인 서버에 있는 정상적인 분할된 데이터베이스 배치의 데이터를 사용합니다.

SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);

master_move_shard_placement

이 함수는 지정된 분할된 데이터베이스(및 분할된 데이터베이스)를 한 노드에서 다른 노드로 이동합니다. 일반적으로 데이터베이스 관리자가 직접 호출하지 않고 분할된 데이터베이스 리밸런싱 중에 간접적으로 사용됩니다.

데이터를 이동하는 방법에는 차단 또는 차단 해제의 두 가지가 있습니다. 차단 방법은 이동하는 동안 분할된 데이터베이스에 대한 모든 수정이 일시 중지됨을 의미합니다. 분할 쓰기 차단을 방지하는 두 번째 방법은 Postgres 10 논리적 복제를 사용하는 것입니다.

이동 작업이 성공하면 원본 노드의 분할된 데이터베이스가 삭제됩니다. 이동이 어느 시점에서든 실패하면 이 함수는 오류를 throw하고 원본 및 대상 노드를 변경되지 않은 상태로 둡니다.

인수

shard_id: 이동할 분할된 데이터베이스의 ID입니다.

source_node_name: 정상적인 분할된 데이터베이스 배치가 있는 노드(“원본” 노드)의 DNS 이름입니다.

source_node_port: 데이터베이스 서버가 수신 대기 중인 원본 작업자 노드의 포트입니다.

target_node_name: 잘못된 분할된 데이터베이스 배치가 있는 노드(“대상” 노드)의 DNS 이름입니다.

target_node_port: 데이터베이스 서버가 수신 대기 중인 대상 작업자 노드의 포트입니다.

shard_transfer_mode: (선택 사항) PostgreSQL 논리적 복제를 사용하든 또는 작업자 간 COPY 명령을 사용하든 관계없이 복제 방법을 지정합니다. 가능한 값은 다음과 같습니다.

auto: 논리적 복제본(replica) 가능한 경우 복제본(replica) ID를 요구합니다. 그렇지 않으면 레거시 동작(예: 분할 복구의 경우 PostgreSQL 9.6)을 사용합니다. 기본값입니다.

force_logical: 테이블에 복제본(replica) ID가 없더라도 논리 복제본(replica)tion을 사용합니다. 테이블에 대한 동시 업데이트/삭제 문은 복제본(replica) 중에 실패합니다.

block_writes: 기본 키 또는 복제본 ID가 없는 테이블에는 COPY(쓰기 차단)를 사용합니다.

반환 값

해당 없음

예시

SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);

rebalance_table_shards

rebalance_table_shards() 함수는 지정된 테이블의 분할된 데이터베이스를 이동하여 작업자 간에 균등하게 배포합니다. 함수는 먼저 클러스터가 지정된 임계 값 내에서 균형을 이루도록 하기 위해 필요한 이동 목록을 계산합니다. 그런 다음 원본 노드에서 대상 노드로 분할된 데이터베이스 배치를 하나씩 이동하고 해당 분할된 데이터베이스 메타데이터를 업데이트하여 이동을 반영합니다.

분할된 데이터베이스가 “균등하게 배포”되었는지 여부를 판단할 때 모든 분할된 데이터베이스에 비용이 할당됩니다. 기본적으로 각 분할된 데이터베이스의 비용은 동일하므로(값 1), 작업자 간에 비용이 균일하도록 배포하는 것은 각 작업자의 분할된 데이터베이스 수를 균일화하는 것과 같습니다. 고정 비용 전략은 “by_shard_count”라고 하며, 기본 리밸런싱 전략입니다.

"by_shard_count" 전략은 다음과 같은 경우에 적합합니다.

분할된 데이터베이스의 크기는 거의 동일합니다.
분할된 데이터베이스는 거의 동일한 양의 트래픽을 받습니다.
작업자 노드의 크기/형식이 모두 동일한 경우
분할된 데이터베이스가 특정 작업자에게 고정되지 않았습니다.

이러한 가정 중 어느 것이라도 유지되지 않으면 "by_shard_count"의 균형을 재조정하면 잘못된 계획이 발생할 수 있습니다.

기본 리밸런싱 전략은 "by_disk_size"입니다. 항상 매개 변수를 사용하여 rebalance_strategy 전략을 사용자 지정할 수 있습니다.

rebalance_table_shards를 실행하기 전에 get_rebalance_table_shards_plan을 호출하여 수행할 작업을 살펴보고 확인하는 것이 좋습니다.

인수

table_name: (선택 사항) 분할된 데이터베이스를 리밸런싱해야 하는 테이블의 이름입니다. NULL이면 기존의 모든 공동 배치 그룹의 균형을 다시 조정합니다.

임계값: (선택 사항) 평균 사용률에서 노드 사용률의 최대 차이 비율을 나타내는 0.0에서 1.0 사이의 부동 소수점 숫자입니다. 예를 들어 0.1을 지정하면 분할된 데이터베이스 리밸런스가 모든 노드의 분산을 시도하여 동일한 수의 분할된 데이터베이스를 ±10%로 유지합니다. 특히, 분할 리밸런서는 모든 작업자 노드의 사용률을 (1-임계값) * average_utilization ... (1

임계값) * average_utilization 범위로 수렴하려고 합니다.

max_shard_moves:(선택 사항) 이동할 최대 분할된 데이터베이스 수입니다.

excluded_shard_list:(선택 사항) 리밸런싱 작업 중에 이동해서는 안 되는 분할된 데이터베이스의 식별자입니다.

auto: 논리적 복제본(replica) 가능한 경우 복제본(replica) ID를 요구합니다. 그렇지 않으면 레거시 동작(예: 분할 복구의 경우 PostgreSQL 9.6)을 사용합니다. 기본값입니다.

force_logical: 테이블에 복제본(replica) ID가 없더라도 논리 복제본(replica)tion을 사용합니다. 테이블에 대한 동시 업데이트/삭제 문은 복제본(replica) 중에 실패합니다.

block_writes: 기본 키 또는 복제본 ID가 없는 테이블에는 COPY(쓰기 차단)를 사용합니다.

drain_only: (선택 사항) true이면 pg_dist_node에서 shouldhaveshards가 false로 설정된 작업자 노드의 분할된 데이터베이스를 다른 곳으로 이동합니다. 다른 분할된 데이터베이스는 이동하지 않습니다.

rebalance_strategy: (선택 사항) pg_dist_rebalance_strategy의 전략 이름입니다. 이 인수를 생략하면 함수는 표에 표시된 대로 기본 전략을 선택합니다.

반환 값

해당 없음

예시

아래 예제는 기본 임계값 내에서 github_events 테이블의 분할된 데이터베이스를 리밸런싱하려고 시도합니다.

SELECT rebalance_table_shards('github_events');

이 예제 사용법에서는 ID가 1과 2인 분할된 데이터베이스를 이동하지 않고 github_events 테이블의 리밸런싱을 시도합니다.

SELECT rebalance_table_shards('github_events', excluded_shard_list:='{1,2}');

get_rebalance_table_shards_plan

rebalance_table_shards 계획된 분할된 데이터베이스 이동을 수행하지 않고 출력합니다. 가능성은 낮지만 get_rebalance_table_shards_plan은 동일한 인수로 rebalance_table_shards가 호출하는 것과는 약간 다른 계획을 출력할 수 있습니다. 동시에 실행되지 않으므로 클러스터에 대한 팩트(예: 디스크 공간)가 호출할 때마다 다를 수 있습니다.

인수

인수는 rebalance_table_shards와 동일합니다(relation, threshold, max_shard_moves, excluded_shard_list, drain_only). 인수의 의미는 해당 함수의 설명서를 참조하세요.

반환 값

튜플은 다음 열을 포함합니다.

table_name: 분할된 데이터베이스를 이동할 테이블
shardid: 의심스러운 분할
shard_size: 크기(바이트)
sourcename: 원본 노드의 호스트 이름
sourceport: 원본 노드의 포트
targetname: 대상 노드의 호스트 이름
targetport: 대상 노드의 포트

get_rebalance_progress

분할된 데이터베이스 리밸런스가 시작되면 함수는 get_rebalance_progress() 관련된 모든 분할된 데이터베이스의 진행률을 나열합니다. 에서 계획하고 실행한 rebalance_table_shards()이동을 모니터링합니다.

인수

해당 없음

반환 값

튜플은 다음 열을 포함합니다.

sessionid: 재조정 모니터의 Postgres PID
table_name: 분할된 데이터베이스를 이동할 테이블
shardid: 의심스러운 분할
shard_size: 크기(바이트)
sourcename: 원본 노드의 호스트 이름
sourceport: 원본 노드의 포트
targetname: 대상 노드의 호스트 이름
targetport: 대상 노드의 포트
진행률: 0 = 이동 대기 중, 1 = 이동, 2 = 완료

예시

SELECT * FROM get_rebalance_progress();

┌───────────┬────────────┬─────────┬────────────┬───────────────┬────────────┬───────────────┬────────────┬──────────┐
│ sessionid │ table_name │ shardid │ shard_size │  sourcename   │ sourceport │  targetname   │ targetport │ progress │
├───────────┼────────────┼─────────┼────────────┼───────────────┼────────────┼───────────────┼────────────┼──────────┤
│      7083 │ foo        │  102008 │    1204224 │ n1.foobar.com │       5432 │ n4.foobar.com │       5432 │        0 │
│      7083 │ foo        │  102009 │    1802240 │ n1.foobar.com │       5432 │ n4.foobar.com │       5432 │        0 │
│      7083 │ foo        │  102018 │     614400 │ n2.foobar.com │       5432 │ n4.foobar.com │       5432 │        1 │
│      7083 │ foo        │  102019 │       8192 │ n3.foobar.com │       5432 │ n4.foobar.com │       5432 │        2 │
└───────────┴────────────┴─────────┴────────────┴───────────────┴────────────┴───────────────┴────────────┴──────────┘

citus_add_rebalance_strategy

행 을 추가하여 pg_dist_rebalance_strategy .

인수

이러한 인수에 대한 자세한 내용은 pg_dist_rebalance_strategy의 해당 열 값을 참조하세요.

name: 새 전략의 식별자

shard_cost_function: 각 분할된 데이터베이스의 “비용”을 결정하는 데 사용되는 함수를 식별합니다.

node_capacity_function: 노드 용량을 측정하는 함수를 식별합니다.

shard_allowed_on_node_function: 각 노드에 배치할 수 있는 분할된 데이터베이스를 결정하는 함수를 식별합니다.

default_threshold: 분할된 데이터베이스 누적 비용이 노드 간에 얼마나 정확하게 균형을 이루어야 하는지를 튜닝하는 부동 소수점 임계값입니다.

minimum_threshold:(선택 사항) rebalance_table_shards()의 임계값 인수에 허용되는 최솟값이 포함되는 보호 열입니다. 기본값은 0입니다.

반환 값

해당 없음

citus_set_default_rebalance_strategy

pg_dist_rebalance_strategy 테이블을 업데이트하고 인수로 명명된 전략을 분할된 데이터베이스의 균형을 조정할 때 기본값으로 변경합니다.

인수

name: pg_dist_rebalance_strategy의 전략 이름입니다.

반환 값

해당 없음

예시

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

citus_remote_connection_stats() 함수는 각 원격 노드에 대한 활성 연결 수를 보여 줍니다.

인수

해당 없음

예시

SELECT * from citus_remote_connection_stats();

    hostname    | port | database_name | connection_count_to_node
----------------+------+---------------+--------------------------
 citus_worker_1 | 5432 | postgres      |                        3
(1 row)

isolate_tenant_to_new_shard

이 함수는 배포 열에 특정 단일 값이 있는 행을 저장할 새 분할된 데이터베이스를 만듭니다. 특히 대규모 테넌트를 자체 분할된 데이터베이스 및 궁극적으로 자체 물리적 노드에 단독으로 배치할 수 있는 다중 테넌트 사용 사례에 특히 편리합니다.

인수

table_name: 새 분할된 데이터베이스를 가져올 테이블의 이름입니다.

tenant_id: 새 분할된 데이터베이스에 할당할 배포 열의 값입니다.

cascade_option: (선택 사항) “CASCADE”로 설정하면 현재 테이블의 공동 배치 그룹에 있는 모든 테이블에서도 분할된 데이터베이스가 격리됩니다.

반환 값

shard_id: 이 함수는 새로 만든 분할된 데이터베이스에 할당된 고유 ID를 반환합니다.

예제

테넌트 135의 라인 항목을 보관할 새 분할을 만듭니다.

SELECT isolate_tenant_to_new_shard('lineitem', 135);

┌─────────────────────────────┐
│ isolate_tenant_to_new_shard │
├─────────────────────────────┤
│                      102240 │
└─────────────────────────────┘

다음 단계

이 문서의 많은 함수는 시스템 메타데이터 테이블을 수정합니다.
서버 매개 변수 는 일부 함수의 동작을 사용자 지정합니다.