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 에 대한 인수로 전달해야 하므로 access_key 값을 복사해야 합니다. 두 액세스 키 중 첫 번째 키를 가져오려면 다음 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용 PostgreSQL(미리 보기), psql, PgAdmin 또는 기본 설정의 클라이언트를 사용하여 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 Database for PostgreSQL 유연한 서버 인스턴스의 확장에서 제공하는 azure_storage 기능을 통해 콘텐츠에 액세스하는 데 필요한 해당 스토리지 계정의 액세스 키와 함께 스토리지 계정에 대한 참조를 추가하는 방법을 보여 줍니다.

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

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

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

팁 (조언)

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

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

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

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

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

컨테이너의 모든 Blob 나열

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

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

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

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

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

<blob_name_prefix> 은 Blob을 열거할 접두사로 설정하여 이름에 포함해야 합니다. 모든 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 문을 사용하여 데이터 가져오기

다음 예제에서는 명령을 통해 storage_extension_sample.parquet Azure Storage 계정<container_name>의 Blob 컨테이너 <account_name> 에 상주하는 Blob에서 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 문을 사용하여 데이터 내보내기

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

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

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

테이블에 데이터를 로드합니다. INSERT 문을 실행하여 여러 가상 행으로 채웁니다. 또는 COPY FROM 문 예제를 사용하여 데이터 가져오기를 사용하여 샘플 데이터 집합의 내용으로 채웁니다.

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_name> 은 내용을 읽으려는 Blob의 전체 경로로 설정해야 합니다.

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

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

또는 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_copy 결과를 options 인수에 전달하여 사용자 지정 구분 기호 및 이스케이프 문자를 사용하는 방법을 보여 줍니다.

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으로 blob_put업로드하는 집계 함수에 전달 sample_data_copy.parquet 됩니다.

인코딩 형식은 파일 확장자를 기반으로 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_storage 과 각 스토리지 계정에 액세스하는 데 사용되는 인증 유형, azure_storage.account_user_add 함수를 통해 권한이 부여된 사용자 또는 역할과 함께 확장에서 제공하는 기능을 통해 해당 Azure Storage 계정에 액세스하는 방법을 보여 줍니다.

SELECT * FROM azure_storage.account_list();

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

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