Azure Database for PostgreSQL 유연한 서버의 Azure Storage 확장에 대한 빠른 시작 예제

다음 예제에서는 Azure Storage 확장을 사용하는 방법을 알아봅니다.

Azure Storage 계정을 만들고 데이터로 채웁니다.

Azure Storage 계정을 만듭니다. Azure Storage 계정을 만들려면 <resource_group>, <location>, <account_name> 및 <container_name> 값을 사용자 지정하고 다음 Azure CLI 명령을 실행합니다.

random_suffix=$(tr -dc 'a-z0-9' </dev/urandom | head -c8)
resource_group="resource-group-$random_suffix"
location="eastus2"
storage_account="storageaccount$random_suffix"
blob_container="container-$random_suffix"
az group create --name $resource_group --location $location
az storage account create --resource-group $resource_group --name $storage_account --location $location --sku Standard_LRS --kind BlobStorage --public-network-access enabled --access-tier hot
echo "Take note of the storage account name, which you'll have to replace in subsequent examples, whenever you find a reference to <account_name>:"
echo $storage_account
echo "Take note of the container name, which you'll have to replace in subsequent examples, whenever you find a reference to <container_name>:"
echo $blob_container

Blob 컨테이너를 만듭니다.

Blob 컨테이너를 만들려면 다음 Azure CLI 명령을 실행합니다.
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
스토리지 계정에 할당된 두 개의 액세스 키 중 하나를 가져옵니다. 후속 단계에서 azure_storage.account_add 에 인수로 전달해야 하므로 액세스 키의 값을 복사해야 합니다.

두 액세스 키 중 첫 번째 키를 얻으려면 다음 Azure CLI 명령을 실행합니다.
```
access_key=$(az storage account keys list --resource-group $resource_group --account-name $storage_account --query [0].value)
echo "Following is the value of your access key:"
echo $access_key
```

예제 중에 사용되는 데이터 집합을 사용하여 파일을 다운로드하고 Blob 컨테이너에 업로드합니다.

데이터 집합을 사용하여 파일을 다운로드하려면 다음 Azure CLI 명령을 실행합니다.

mkdir --parents azure_storage_examples
cd azure_storage_examples
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/storage_extension_sample.parquet
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "storage_extension_sample.parquet" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/parquet_without_extension
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "parquet_without_extension" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/storage_extension_sample.csv
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "storage_extension_sample.csv" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/csv_without_extension
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "csv_without_extension" --account-key $access_key --overwrite --output none --only-show-errors

비고

특정 스토리지 계정에 대해 컨테이너 또는 컨테이너에 저장된 Blob을 나열할 수 있지만 PostgreSQL 사용자 또는 역할에 azure_storage.account_user_add를 사용하여 해당 스토리지 계정에 대한 참조 권한이 부여된 경우에만 나열할 수 있습니다. 역할의 azure_storage_admin 멤버는 azure_storage.account_add를 사용하여 추가된 모든 Azure Storage 계정에 대해 이 권한을 부여합니다. 기본적으로 역할의 azure_pg_admin 멤버만 부여 azure_storage_admin 됩니다.

데이터를 로드할 테이블 만들기

스토리지 계정에 업로드한 파일의 내용을 가져올 테이블을 만듭니다. 이렇게 하려면 Visual Studio Code(미리 보기), psql, PgAdmin 또는 기본 설정의 클라이언트용 PostgreSQL을 사용하여 Azure Database for PostgreSQL 유연한 서버의 인스턴스에 연결하고 다음 문을 실행합니다.

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

사용 확장을 준비합니다.

계속하기 전에 다음을 수행해야 합니다.

스토리지 계정의 액세스 키 추가

이 예제에서는 해당 스토리지 계정의 액세스 키와 함께 스토리지 계정에 대한 참조를 추가하는 방법을 보여 줍니다. 스토리지 계정의 콘텐츠 azure_storage 에 액세스하려면 Azure Database for PostgreSQL 유연한 서버 인스턴스의 확장에 액세스 키가 필요합니다.

스토리지 계정의 이름으로 설정합니다 <account_name> . 이전 스크립트를 사용한 경우 이 값은 해당 스크립트의 환경 변수에 storage_account 대해 설정한 값과 일치해야 합니다.

스토리지 계정에서 가져온 값으로 설정합니다 <access_key> .

SELECT azure_storage.account_add('<account_name>', '<access_key>');

팁 (조언)

Azure 포털에서 스토리지 계정 이름 및 해당 액세스 키 중 하나를 검색하려면 스토리지 계정을 검색합니다. 리소스 메뉴에서 액세스 키를 선택합니다. Storage 계정 이름을 복사하고 key1 섹션에서 키를 복사합니다. 먼저 키 옆에 표시 를 선택해야 합니다.

Azure Blob Storage 참조에서 사용자 또는 역할에 대한 액세스 권한 부여

이 예제에서는 PostgreSQL 사용자가 확장을 사용하여 <regular_user> 참조된 Azure 스토리지 계정에서 호스트하는 컨테이너에 저장된 Blob에 액세스할 수 있도록 명명azure_storage된 사용자 또는 역할에 대한 액세스 권한을 부여하는 방법을 보여 줍니다.

기존 사용자 또는 역할의 이름으로 설정합니다 <regular_user> .

SELECT * FROM azure_storage.account_user_add('<account_name>', '<regular_user>');

컨테이너의 모든 Blob 나열

이 예제에서는 스토리지 계정<container_name>의 컨테이너 <account_name> 내에 있는 모든 기존 Blob을 나열하는 방법을 보여 줍니다.

Blob 컨테이너의 이름으로 설정합니다 <container_name> . 이전 스크립트를 사용한 경우 이 값은 해당 스크립트의 환경 변수에 blob_container 대해 설정한 값과 일치해야 합니다.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>');

특정 이름 접두사를 사용하여 Blob 나열

이 예제에서는 Blob 이름이 .로 시작하는 스토리지 계정의 컨테이너 <container_name> 내에 있는 모든 기존 Blob을 나열하는 방법을 보여 줍니다<account_name>.<blob_name_prefix>

Blob을 열거할 접두사로 설정 <blob_name_prefix> 하여 이름에 포함합니다. 모든 Blob을 반환하려면 이 매개 변수를 빈 문자열로 설정하거나 이 매개 변수의 값을 지정하지 않습니다. 이 경우 값은 기본값이 빈 문자열로 설정됩니다.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>','<blob_name_prefix>');

또는 다음 구문을 사용할 수 있습니다.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>') WHERE path LIKE '<blob_name_prefix>%';

COPY FROM 문을 사용하여 데이터 가져오기

다음 예제에서는 Azure Storage 계정storage_extension_sample.parquet의 Blob 컨테이너 <container_name> 에 있는 Blob에서 <account_name> 데이터를 가져오는 방법을 보여 줍니다. 가져오기는 다음 명령을 사용합니다.COPY

원본 파일의 스키마와 일치하는 테이블을 만듭니다.

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

COPY 문을 사용하여 대상 테이블에 데이터를 복사합니다. 형식은 파일 확장에서 Parquet로 유추됩니다.

TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.parquet';

COPY 문을 사용하여 대상 테이블에 데이터를 복사합니다. 파일 확장 프로그램에서 인코딩 형식을 유추할 수 없으므로 옵션을 사용하여 FORMAT 명시적으로 지정합니다.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
COPY 문을 사용하여 대상 테이블에 데이터를 복사합니다. 파일 확장자에서 인코딩 형식을 유추할 수 있습니다. 그러나 옵션을 사용하여 HEADERS 첫 번째 행에 열 머리글이 있는지 명시적으로 구성해야 합니다.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
다음 SELECT 문을 실행하여 데이터가 테이블에 로드되어 있는지 확인합니다.
```
SELECT *
FROM sample_data
LIMIT 100;
```

COPY TO 문을 사용하여 데이터 내보내기

다음 예제에서는 인코딩 형식과 같이 이름과 특성이 다른 여러 Blob으로 명명된 sample_data 테이블에서 데이터를 내보내는 방법을 보여 줍니다. 모든 Blob은 Azure Storage 계정의 Blob 컨테이너 <container_name> 에 상주합니다<account_name>. 명령을 COPY 사용하여 데이터를 내보냅니다.

원본 파일의 스키마와 일치하는 테이블을 만듭니다.

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

원본 파일의 스키마와 일치하는 테이블을 만듭니다.

COPY 문을 사용하여 대상 테이블에서 데이터를 복사합니다. 인코딩 형식이 parquet이어야 하려면 지정합니다.

COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.parquet'
WITH (FORMAT 'parquet');

COPY 문을 사용하여 대상 테이블에서 데이터를 복사합니다. 인코딩 형식이 CSV여야 하고 결과 파일의 첫 번째 행에 열 머리글이 포함되도록 지정합니다.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

다음 SELECT 문을 실행하여 Blob이 스토리지 계정에 있는지 확인합니다.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>') WHERE path LIKE 'storage_extension_sample_exported%';

Blob에서 콘텐츠 읽기

이 함수는 blob_get 스토리지의 참조된 컨테이너 <container_name> 에서 특정 Blob의 콘텐츠를 검색합니다 <account_name> . 데이터를 구문 분석하는 데 도움이 blob_get 되도록 폼 NULL::table_name의 값을 전달합니다. 여기서 스키마가 읽고 있는 table_name Blob의 스키마와 일치하는 테이블을 참조합니다. 이 예제에서는 처음에 만든 테이블을 참조 sample_data 합니다.

내용을 읽으려는 Blob의 전체 경로로 설정합니다 <blob_name> .

이 경우 Blob을 구문 분석하는 디코더가 파일 확장자에서 .parquet 유추됩니다.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
LIMIT 5;

또는 blob_get 함수 뒤의 절을 사용하여 AS 결과의 스키마를 명시적으로 정의할 수 있습니다.

SELECT * FROM azure_storage.blob_get('<account_name>','<container_name>','storage_extension_sample.parquet')
AS res (
        id BIGINT PRIMARY KEY,
        sample_text TEXT,
        sample_integer INTEGER,
        sample_timestamp TIMESTAMP)
LIMIT 5;

Blob에서 읽은 콘텐츠 읽기, 필터링 및 수정

이 예제에서는 BLOB에서 가져온 콘텐츠를 SQL 테이블에 로드하기 전에 필터링하고 수정하는 방법을 보여줍니다.

SELECT concat('P-',id::text) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
WHERE sample_integer=780
LIMIT 5;

사용자 지정 옵션(헤더, 열 구분 기호, 이스케이프 문자)을 사용하여 파일에서 콘텐츠를 읽습니다.

이 예제에서는 options_copyoptions 결과를 인수에 전달하여 사용자 지정 구분 기호 및 이스케이프 문자를 사용하는 방법을 보여줍니다.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.csv'
        ,NULL::sample_data
        ,options := azure_storage.options_csv_get(header := 'true')
        );

디코더 옵션 사용

이 예제에서는 이 옵션을 사용하는 decoder 방법을 보여줍니다. 디코더 옵션을 포함하지 않으면 시스템에서 파일 확장 프로그램에서 유추합니다. 파일 이름에 확장명이 없거나 파일 이름 확장명이 시스템에서 파일 내용을 제대로 구문 분석해야 하는 디코더에 해당하지 않는 경우 디코더 인수를 명시적으로 전달할 수 있습니다.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'parquet_without_extension'
        , NULL::sample_data
        , decoder := 'parquet')
LIMIT 5;

Blob의 콘텐츠에 대한 집계 계산

이 예제에서는 Blob의 내용을 PostgreSQL 테이블로 가져올 필요 없이 Blob 컨테이너에 저장된 정보에 대해 집계 작업을 수행하는 방법을 보여 줍니다.

SELECT sample_integer, COUNT(*) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
GROUP BY sample_integer
ORDER BY 2 DESC
LIMIT 5;

Blob에 콘텐츠 쓰기

함수는 blob_put 하나의 특정 Blob(sample_data_copy.parquet 이 경우)의 내용을 구성하고 스토리지의 참조된 컨테이너 <container_name> 에 <account_name> 업로드합니다. 이 예제에서는 blob_get 5개의 행 집합을 생성한 다음, Blob으로 sample_data_copy.parquet업로드하는 집계 함수에 전달 blob_put 됩니다.

인코딩 형식은 파일 확장자를 기반으로 Parquet로 유추됩니다 .parquet.

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_data_copy.parquet'
        , top_5_sample_data)
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

인코딩 형식은 파일 확장자를 기반으로 CSV로 유추됩니다 .csv.

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_data_copy.csv'
        , top_5_sample_data)
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

파일에 파일 확장명이 없으므로 인코딩 형식을 유추할 수 없으므로 명시적으로 구성 parquet됩니다. 또한 압축 알고리즘은 .로 설정됩니다 zstd.

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_parquet_data_copy_without_extension_with_zstd_compression'
        , top_5_sample_data
        ,'parquet'
        ,'zstd')
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

Azure Storage 계정에 대한 모든 참조 나열

이 예제에서는 각 스토리지 계정에 azure_storage 액세스하는 데 사용되는 인증 유형과 함께 확장이 이 데이터베이스에서 참조할 수 있는 Azure 스토리지 계정을 찾는 방법을 보여 줍니다. 또한 확장에서 제공하는 기능을 통해 해당 Azure 스토리지 계정에 액세스하기 위해 azure_storage.account_user_add 함수를 통해 권한이 부여된 사용자 또는 역할을 보여 줍니다.

SELECT * FROM azure_storage.account_list();

Azure Blob Storage 참조의 사용자 또는 역할에서 액세스 취소

이 예제에서는 PostgreSQL 사용자가 확장을 사용하여 azure_storage 참조된 Azure 스토리지 계정에서 호스트되는 컨테이너에 저장된 Blob에 액세스할 수 없도록 사용자 또는 역할<regular_user>에서 액세스를 취소하는 방법을 보여 줍니다.