pg_azure_storage 확장
적용 대상: Azure Cosmos DB for PostgreSQL(PostgreSQL에 대한 Citus 데이터베이스 확장 기반)
pg_azure_storage 확장을 사용하면 Azure Blob Storage에서 Azure Cosmos DB for PostgreSQL 클러스터로 직접 데이터를 여러 파일 형식으로 로드할 수 있습니다. 또한 이 확장을 사용하도록 설정하면 COPY 명령의 새 기능이 잠금 해제됩니다. 액세스 수준이 "Private" 또는 "Blob"인 컨테이너에는 프라이빗 액세스 키를 추가해야 합니다.
다음을 실행하여 확장을 만들 수 있습니다.
SELECT create_extension('azure_storage');
azure_storage.account_add
이 함수를 사용하여 스토리지 계정에 대한 액세스를 추가할 수 있습니다.
azure_storage.account_add
(account_name_p text
,account_key_p text);
인수
account_name_p
ABS(Azure Blob Storage) 계정에는 모든 ABS 개체(BLOB, 파일, 큐, 테이블)가 포함됩니다. 스토리지 계정은 전 세계 어디에서나 HTTPS를 통해 액세스할 수 있는 ABS의 고유한 네임스페이스를 제공합니다.
account_key_p
ABS(Azure Blob Storage) 계정 키는 스토리지 계정의 루트 암호와 비슷합니다. 항상 액세스 키를 보호해야 합니다. Azure Key Vault를 사용하여 키를 안전하게 관리하고 회전합니다. 계정 키는 postgres 슈퍼 사용자, azure_storage_admin 및 해당 관리자 권한이 부여된 모든 역할이 액세스할 수 있는 테이블에 저장됩니다. 어떤 스토리지 계정이 있는지 확인하려면 account_list 함수를 사용합니다.
azure_storage.account_remove
이 함수를 사용하여 스토리지 계정에 대한 계정의 액세스 권한을 해지할 수 있습니다.
azure_storage.account_remove
(account_name_p text);
인수
account_name_p
ABS(Azure Blob Storage) 계정에는 모든 ABS 개체(BLOB, 파일, 큐, 테이블)가 포함됩니다. 스토리지 계정은 전 세계 어디에서나 HTTPS를 통해 액세스할 수 있는 ABS의 고유한 네임스페이스를 제공합니다.
azure_storage.account_user_add
이 함수를 사용하여 역할의 스토리지 계정 액세스 권한을 추가할 수 있습니다.
azure_storage.account_user_add
( account_name_p text
, user_p regrole);
인수
account_name_p
ABS(Azure Blob Storage) 계정에는 모든 ABS 개체(BLOB, 파일, 큐, 테이블)가 포함됩니다. 스토리지 계정은 전 세계 어디에서나 HTTPS를 통해 액세스할 수 있는 ABS의 고유한 네임스페이스를 제공합니다.
user_p
사용자가 만든 역할이며 클러스터에 표시됩니다.
참고 항목
account_user_add
, account_add
, account_remove
및 account_user_remove
함수는 클러스터의 각 개별 노드에 대한 설정 권한이 필요합니다.
azure_storage.account_user_remove
이 함수를 사용하여 역할의 스토리지 계정 액세스 권한을 제거할 수 있습니다.
azure_storage.account_user_remove
(account_name_p text
,user_p regrole);
인수
account_name_p
ABS(Azure Blob Storage) 계정에는 모든 ABS 개체(BLOB, 파일, 큐, 테이블)가 포함됩니다. 스토리지 계정은 전 세계 어디에서나 HTTPS를 통해 액세스할 수 있는 ABS의 고유한 네임스페이스를 제공합니다.
user_p
사용자가 만든 역할이며 클러스터에 표시됩니다.
azure_storage.account_list
이 함수는 Azure Blob Storage에 대한 액세스 권한이 있는 계정 및 역할을 나열합니다.
azure_storage.account_list
(OUT account_name text
,OUT allowed_users regrole[]
)
Returns TABLE;
인수
account_name
ABS(Azure Blob Storage) 계정에는 모든 ABS 개체(BLOB, 파일, 큐, 테이블)가 포함됩니다. 스토리지 계정은 전 세계 어디에서나 HTTPS를 통해 액세스할 수 있는 ABS의 고유한 네임스페이스를 제공합니다.
allowed_users
Azure Blob Storage에 대한 액세스 권한이 있는 사용자를 나열합니다.
반환 형식
TABLE
azure_storage.blob_list
이 함수는 사용자 컨테이너 내부의 속성이 있는 사용 가능 BLOB 파일을 나열합니다.
azure_storage.blob_list
(account_name text
,container_name text
,prefix text DEFAULT ''::text
,OUT path text
,OUT bytes bigint
,OUT last_modified timestamp with time zone
,OUT etag text
,OUT content_type text
,OUT content_encoding text
,OUT content_hash text
)
Returns SETOF record;
인수
account_name
storage account name
은 전 세계 어디에서나 HTTPS를 통해 액세스할 수 있는 Azure 스토리지 데이터의 고유한 네임스페이스를 제공합니다.
container_name
컨테이너는 파일 시스템의 디렉터리와 비슷한 BLOB 세트를 구성합니다. 한 스토리지 계정에 포함될 수 있는 컨테이너 수에 제한이 없으며, 컨테이너에 저장될 수 있는 Blob 수에도 제한이 없습니다. 컨테이너 이름은 컨테이너 또는 해당 Blob의 주소를 지정하는 데 사용되는 고유한 URI의 일부를 구성하기 때문에 유효한 DNS 이름이어야 합니다. 컨테이너의 이름을 지정할 때 다음 규칙을 따릅니다.
- 컨테이너 이름은 3 ~ 63자까지 가능합니다.
- 컨테이너 이름은 문자 또는 숫자로 시작해야 하며 소문자, 숫자 및 대시(-) 문자를 포함할 수 있습니다.
- 컨테이너 이름에는 두 개 이상의 연속 대시 문자가 허용되지 않습니다.
컨테이너의 URI는 https://myaccount.blob.core.windows.net/mycontainer
형식입니다.
prefix
문자열 이니셜이 일치하는 BLOB 컨테이너의 파일을 반환합니다.
경로
Azure BLOB 디렉터리의 정규화된 경로입니다.
bytes
파일 개체의 크기(바이트)입니다.
last_modified
파일 콘텐츠가 마지막으로 수정된 시간입니다.
etag
ETag 속성은 업데이트하는 동안 낙관적 동시성에 사용됩니다. 레코드가 마지막으로 업데이트된 시간을 저장하는 Timestamp라는 다른 속성이 있으므로 이 속성은 타임스탬프가 아닙니다. 예를 들어 엔터티를 로드하고 업데이트하려면 ETag가 현재 저장된 항목과 일치해야 합니다. 여러 사용자가 동일한 항목을 편집할 때 서로 변경 내용을 덮어쓰는 일이 없어야 하므로 적절한 ETag를 설정하는 것이 중요합니다.
content_type
Blob 개체는 변경할 수 없는 원시 데이터의 파일과 유사한 개체인 BLOB을 나타냅니다. 텍스트 또는 이진 데이터로 읽을 수도 있고, 해당 메서드를 데이터 처리에 사용할 수 있도록 ReadableStream으로 변환할 수도 있습니다. Blob은 JavaScript 네이티브 형식이 아니어도 되는 데이터를 나타낼 수 있습니다.
content_encoding
Azure Storage를 사용하면 BLOB의 Content-Encoding 속성을 정의할 수 있습니다. 압축된 콘텐츠의 경우 속성을 GZIP으로 설정할 수 있습니다. 브라우저는 콘텐츠에 액세스하면 자동으로 콘텐츠의 압축을 풉니다.
content_hash
이 해시는 전송 중에 Blob의 무결성을 확인하는 데 사용됩니다. 이 헤더를 지정하면 스토리지 서비스는 전송된 해시와 함께 도착한 해시를 확인합니다. 두 해시가 일치하지 않으면 작업이 실패하고 오류 코드 400(잘못된 요청)이 표시됩니다.
반환 형식
SETOF 레코드
참고 항목
권한 이제 해당 스토리지에 대한 프라이빗 및 Blob 액세스 수준으로 설정된 컨테이너를 azure_storage_admin
역할이 부여된 citus user
로만 나열할 수 있습니다. support
라는 새 사용자를 만드는 경우 기본적으로 컨테이너 콘텐츠에 액세스할 수 없습니다.
azure_storage.blob_get
이 함수를 사용하면 가져오기 전에 컨테이너 내에서 파일의 콘텐츠를 로드할 수 있으며, 데이터 필터링 또는 조작에 대한 지원이 추가됩니다.
azure_storage.blob_get
(account_name text
,container_name text
,path text
,decoder text DEFAULT 'auto'::text
,compression text DEFAULT 'auto'::text
,options jsonb DEFAULT NULL::jsonb
)
RETURNS SETOF record;
출력 형식 레코드를 간편하게 정의할 수 있는 rec 매개 변수를 포함하고 있는 오버로드된 버전의 함수가 있습니다.
azure_storage.blob_get
(account_name text
,container_name text
,path text
,rec anyelement
,decoder text DEFAULT 'auto'::text
,compression text DEFAULT 'auto'::text
,options jsonb DEFAULT NULL::jsonb
)
RETURNS SETOF anyelement;
인수
거래처
스토리지 계정은 전 세계 어디에서나 HTTPS를 통해 액세스할 수 있는 Azure Storage 데이터의 고유한 네임스페이스를 제공합니다.
container
컨테이너는 파일 시스템의 디렉터리와 비슷한 BLOB 세트를 구성합니다. 한 스토리지 계정에 포함될 수 있는 컨테이너 수에 제한이 없으며, 컨테이너에 저장될 수 있는 Blob 수에도 제한이 없습니다. 컨테이너 이름은 컨테이너 또는 해당 Blob의 주소를 지정하는 데 사용되는 고유한 URI의 일부를 구성하기 때문에 유효한 DNS 이름이어야 합니다.
경로
컨테이너에 존재하는 BLOB 이름입니다.
rec
레코드 출력 구조를 정의합니다.
디코더
디코더를 자동(기본값) 또는 다음 값으로 설정할 수 있는 BLOB 형식을 지정합니다.
디코더 설명
형식 | 설명 |
---|---|
csv | PostgreSQL COPY에서 사용하는 쉼표로 구분된 값 형식 |
tsv | 탭으로 구분된 값, 기본 PostgreSQL COPY 형식 |
binary | 이진 PostgreSQL COPY 형식 |
text | 단일 텍스트 값이 포함된 파일(예: 큰 JSON 또는 XML) |
compression
압축 형식을 정의합니다. 사용 가능한 옵션은 auto
, gzip
및 . none
auto
옵션(기본값)을 사용하면 파일 확장명(.gz == gzip)을 기반으로 압축을 추측합니다. none
옵션은 확장을 무시하고 디코딩을 시도하지 않도록 강제합니다. 반면 gzip은 디코더를 사용하도록 강제합니다(gzip으로 압축되고 비표준 확장명을 사용하는 파일이 있는 경우). 현재는 확장에 다른 압축 형식을 지원하지 않습니다.
options
사용자 지정 헤더, 사용자 지정 구분 기호, 이스케이프 문자 등을 처리할 때 options
는 PostgreSQL의 COPY
명령과 비슷한 방식으로 작동하며, 매개 변수는 blob_get 함수를 사용합니다.
반환 형식
SETOF 레코드/anyelement
참고 항목
blob_get 내에서 매개 변수로 호출되며 값을 작성하는 데 도움이 되는 네 가지 유틸리티 함수가 있습니다. 각 유틸리티 함수는 해당 이름과 일치하는 디코더용으로 고안되었습니다.
azure_storage.options_csv_get
이 함수는 blob_get 내에서 매개 변수로 호출되며 csv 콘텐츠를 디코딩하는 데 유용한 유틸리티 함수 역할을 합니다.
azure_storage.options_csv_get
(delimiter text DEFAULT NULL::text
,null_string text DEFAULT NULL::text
,header boolean DEFAULT NULL::boolean
,quote text DEFAULT NULL::text
,escape text DEFAULT NULL::text
,force_not_null text[] DEFAULT NULL::text[]
,force_null text[] DEFAULT NULL::text[]
,content_encoding text DEFAULT NULL::text
)
Returns jsonb;
인수
delimiter
파일의 각 행(줄) 내에서 열을 구분하는 문자를 지정합니다. 기본값은 텍스트 형식의 탭 문자이며, CSV 형식의 쉼표입니다. 단일 1바이트 문자여야 합니다.
null_string
null 값을 나타내는 문자열을 지정합니다. 기본값은 텍스트 형식의 \N(백슬래시-N)이며, 따옴표로 묶이지 않은 CSV 형식의 빈 문자열입니다. null을 빈 문자열과 구분하지 않으려는 경우 텍스트 형식에서도 빈 문자열을 선호할 수 있습니다.
헤더
파일에 헤더 줄과 파일의 각 열 이름이 포함되도록 지정합니다. 출력의 첫 번째 줄에는 테이블의 열 이름이 포함됩니다.
견적
데이터 값을 따옴표로 묶을 때 사용할 따옴표 문자를 지정합니다. 기본값은 큰따옴표입니다. 단일 1바이트 문자여야 합니다.
escape
QUOTE 값과 일치하는 데이터 문자 앞에 나타날 문자를 지정합니다. 기본값은 QUOTE 값과 동일합니다(따옴표 문자가 데이터에 표시되는 경우 큰따옴표가 되도록). 단일 1바이트 문자여야 합니다.
force_not_null
지정된 열의 값을 null 문자열과 매칭하지 않습니다. null 문자열이 비어 있는 기본적인 사례에서는 빈 값을 따옴표로 묶지 않더라도 null이 아닌 길이가 0인 문자열로 읽습니다.
force_null
따옴표로 묶은 경우에도 지정된 열의 값을 null 문자열과 매칭하고, 일치하는 항목이 발견되면 값을 NULL로 설정합니다. null 문자열이 비어 있는 기본적인 사례에서는 따옴표로 묶은 빈 문자열을 NULL로 변환합니다.
content_encoding
파일이 encoding_name으로 인코딩되도록 지정합니다. 이 옵션을 생략하면 현재 클라이언트 인코딩이 사용됩니다.
반환 형식
jsonb
azure_storage.options_copy
이 함수는 blob_get 내에서 매개 변수로 호출되는 유틸리티 함수 역할을 합니다.
azure_storage.options_copy
(delimiter text DEFAULT NULL::text
,null_string text DEFAULT NULL::text
,header boolean DEFAULT NULL::boolean
,quote text DEFAULT NULL::text
,escape text DEFAULT NULL::text
,force_quote text[] DEFAULT NULL::text[]
,force_not_null text[] DEFAULT NULL::text[]
,force_null text[] DEFAULT NULL::text[]
,content_encoding text DEFAULT NULL::text
)
Returns jsonb;
인수
delimiter
파일의 각 행(줄) 내에서 열을 구분하는 문자를 지정합니다. 기본값은 텍스트 형식의 탭 문자이며, CSV 형식의 쉼표입니다. 단일 1바이트 문자여야 합니다.
null_string
null 값을 나타내는 문자열을 지정합니다. 기본값은 텍스트 형식의 \N(백슬래시-N)이며, 따옴표로 묶이지 않은 CSV 형식의 빈 문자열입니다. null을 빈 문자열과 구분하지 않으려는 경우 텍스트 형식에서도 빈 문자열을 선호할 수 있습니다.
헤더
파일에 헤더 줄과 파일의 각 열 이름이 포함되도록 지정합니다. 출력의 첫 번째 줄에는 테이블의 열 이름이 포함됩니다.
견적
데이터 값을 따옴표로 묶을 때 사용할 따옴표 문자를 지정합니다. 기본값은 큰따옴표입니다. 단일 1바이트 문자여야 합니다.
escape
QUOTE 값과 일치하는 데이터 문자 앞에 나타날 문자를 지정합니다. 기본값은 QUOTE 값과 동일합니다(따옴표 문자가 데이터에 표시되는 경우 큰따옴표가 되도록). 단일 1바이트 문자여야 합니다.
force_quote
지정된 각 열의 NULL이 아닌 모든 값에 따옴표를 사용하도록 강제합니다. NULL 출력에는 절대 따옴표가 사용되지 않습니다. *를 지정하면 모든 열에서 NULL이 아닌 값이 따옴표로 묶입니다.
force_not_null
지정된 열의 값을 null 문자열과 매칭하지 않습니다. null 문자열이 비어 있는 기본적인 사례에서는 빈 값을 따옴표로 묶지 않더라도 null이 아닌 길이가 0인 문자열로 읽습니다.
force_null
따옴표로 묶은 경우에도 지정된 열의 값을 null 문자열과 매칭하고, 일치하는 항목이 발견되면 값을 NULL로 설정합니다. null 문자열이 비어 있는 기본적인 사례에서는 따옴표로 묶은 빈 문자열을 NULL로 변환합니다.
content_encoding
파일이 encoding_name으로 인코딩되도록 지정합니다. 이 옵션을 생략하면 현재 클라이언트 인코딩이 사용됩니다.
반환 형식
jsonb
azure_storage.options_tsv
이 함수는 blob_get 내에서 매개 변수로 호출되는 유틸리티 함수 역할을 합니다. tsv 콘텐츠를 디코딩하는 데 유용합니다.
azure_storage.options_tsv
(delimiter text DEFAULT NULL::text
,null_string text DEFAULT NULL::text
,content_encoding text DEFAULT NULL::text
)
Returns jsonb;
인수
delimiter
파일의 각 행(줄) 내에서 열을 구분하는 문자를 지정합니다. 기본값은 텍스트 형식의 탭 문자이며, CSV 형식의 쉼표입니다. 단일 1바이트 문자여야 합니다.
null_string
null 값을 나타내는 문자열을 지정합니다. 기본값은 텍스트 형식의 \N(백슬래시-N)이며, 따옴표로 묶이지 않은 CSV 형식의 빈 문자열입니다. null을 빈 문자열과 구분하지 않으려는 경우 텍스트 형식에서도 빈 문자열을 선호할 수 있습니다.
content_encoding
파일이 encoding_name으로 인코딩되도록 지정합니다. 이 옵션을 생략하면 현재 클라이언트 인코딩이 사용됩니다.
반환 형식
jsonb
azure_storage.options_binary
이 함수는 blob_get 내에서 매개 변수로 호출되는 유틸리티 함수 역할을 합니다. 이진 콘텐츠를 디코딩하는 데 유용합니다.
azure_storage.options_binary
(content_encoding text DEFAULT NULL::text)
Returns jsonb;
인수
content_encoding
파일이 encoding_name으로 인코딩되도록 지정합니다. 이 옵션을 생략하면 현재 클라이언트 인코딩이 사용됩니다.
반환 형식
jsonb
참고 항목
권한 이제 해당 스토리지에 대한 프라이빗 및 Blob 액세스 수준으로 설정된 컨테이너를 azure_storage_admin
역할이 부여된 citus user
로만 나열할 수 있습니다. support라는 새 사용자를 만드는 경우 해당 사용자는 기본적으로 컨테이너 콘텐츠에 액세스할 수 없습니다.
예제
이 예제에서는 다양한 사용 사례를 지원하기 위해 업로드된 사용자 지정 파일과 함께 샘플 Azure 스토리지 계정(pgquickstart)
을 사용합니다. 가장 먼저 예제 집합에서 사용되는 테이블을 만듭니다.
CREATE TABLE IF NOT EXISTS public.events
(
event_id bigint
,event_type text
,event_public boolean
,repo_id bigint
,payload jsonb
,repo jsonb
,user_id bigint
,org jsonb
,created_at timestamp without time zone
);
스토리지 계정의 액세스 키 추가(액세스 수준에 필수 = 프라이빗)
이 예제에서는 Azure Cosmos DB for Postgres 클러스터의 세션에서 쿼리하는 데 필요한 액세스 권한을 얻기 위해 스토리지 계정에 대한 액세스 키를 추가하는 방법을 보여줍니다.
SELECT azure_storage.account_add('pgquickstart', 'SECRET_ACCESS_KEY');
팁
스토리지 계정에서 액세스 키를 엽니다. 스토리지 계정 이름을 복사하고 key1 섹션의 키를 복사합니다(먼저 키 옆에 표시를 선택해야 함).
스토리지 계정의 액세스 키 제거
이 예제에서는 스토리지 계정에 대한 액세스 키를 제거하는 방법을 보여줍니다. 이 작업을 수행하면 컨테이너의 프라이빗 버킷에 호스트된 파일에 대한 액세스 권한이 제거됩니다.
SELECT azure_storage.account_remove('pgquickstart');
역할의 Azure Blob 스토리지에 대한 액세스 권한 추가
SELECT * FROM azure_storage.account_user_add('pgquickstart', 'support');
Azure Blob 스토리지에 대한 액세스 권한이 있는 모든 역할 나열
SELECT * FROM azure_storage.account_list();
Azure Blob 스토리지에 대한 액세스 권한이 있는 역할 제거
SELECT * FROM azure_storage.account_user_remove('pgquickstart', 'support');
public
컨테이너의 개체 나열
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer');
private
컨테이너의 개체 나열
SELECT * FROM azure_storage.blob_list('pgquickstart','privatecontainer');
참고 항목
액세스 키 추가는 필수입니다.
공용 컨테이너의 개체 중에서 특정 문자열 이니셜이 있는 개체 나열
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer','e');
또는
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer') WHERE path LIKE 'e%';
컨테이너에 들어 있는 개체의 콘텐츠 읽기
blob_get
함수는 Blob Storage의 파일을 검색합니다. blob_get이 데이터를 구문 분석하는 방법을 알게 하려면 파일과 동일한 형식의 값(NULL::table_name)을 전달하거나
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events.csv.gz'
, NULL::events)
LIMIT 5;
FROM
절에서 열을 명시적으로 정의하면 됩니다.
SELECT * FROM azure_storage.blob_get('pgquickstart','publiccontainer','events.csv')
AS res (
event_id BIGINT
,event_type TEXT
,event_public BOOLEAN
,repo_id BIGINT
,payload JSONB
,repo JSONB
,user_id BIGINT
,org JSONB
,created_at TIMESTAMP WITHOUT TIME ZONE)
LIMIT 5;
디코더 옵션 사용
이 예제에서는 decoder
옵션의 사용법을 보여줍니다. 일반적으로 파일의 확장명을 보면 형식을 유추할 수 있지만, 파일 콘텐츠에 일치하는 확장명이 없는 경우에는 디코더 인수를 전달하면 됩니다.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events'
, NULL::events
, decoder := 'csv')
LIMIT 5;
디코더 옵션과 함께 압축 사용
이 예제에서는 표준 .gz 확장명 없이 gzip 압축 파일에서 gzip 압축을 사용하여 적용하는 방법을 보여줍니다.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events-compressed'
, NULL::events
, decoder := 'csv'
, compression := 'gzip')
LIMIT 5;
csv 형식 개체에서 로드하기 전에 필터링된 콘텐츠 가져오기 및 수정
이 예제에서는 SQL 테이블에 로드하기 전에 컨테이너의 개체에서 가져오는 콘텐츠를 필터링하고 수정할 수 있는 가능성을 보여 줍니다.
SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events.csv'
, NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;
헤더, 사용자 지정 구분 기호, 이스케이프 문자를 사용하여 파일의 콘텐츠 쿼리
azure_storage.options_copy
의 결과를 options
인수에 전달하여 사용자 지정 구분 기호 및 이스케이프 문자를 사용할 수 있습니다.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events_pipe.csv'
,NULL::events
,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
);
컨테이너에 있는 개체의 콘텐츠에 대한 집계 쿼리
다음과 같이 하면 데이터를 가져오지 않고도 데이터를 쿼리할 수 있습니다.
SELECT event_type,COUNT(1) FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events.csv'
, NULL::events)
GROUP BY event_type
ORDER BY 2 DESC
LIMIT 5;