# Amazon Athena PostgreSQL 커넥터
<a name="connectors-postgresql"></a>

Amazon Athena PostgreSQL 커넥터를 사용하면 Athena에서 PostgreSQL 데이터베이스에 액세스할 수 있습니다.

이 커넥터는 Glue 데이터 카탈로그에 페더레이션 카탈로그로 등록할 수 있습니다. 카탈로그, 데이터베이스, 테이블, 열, 행 및 태그 수준에서 Lake Formation에 정의된 데이터 액세스 제어를 지원합니다. 이 커넥터는 Glue Connections를 사용하여 Glue의 구성 속성을 중앙 집중화합니다.

## 사전 조건
<a name="connectors-postgres-prerequisites"></a>
+ Athena 콘솔 또는 AWS Serverless Application Repository를 사용하여 AWS 계정에 커넥터를 배포합니다. 자세한 내용은 [데이터 소스 연결 생성](connect-to-a-data-source.md) 또는 [AWS Serverless Application Repository을 사용하여 데이터 소스 커넥터 배포](connect-data-source-serverless-app-repo.md) 섹션을 참조하세요.

## 제한 사항
<a name="connectors-postgresql-limitations"></a>
+ DDL 쓰기 작업은 지원되지 않습니다.
+ 멀티플렉서 설정에서 유출 버킷과 접두사는 모든 데이터베이스 인스턴스에서 공유됩니다.
+ 모든 관련 Lambda 제한. 자세한 내용은 *AWS Lambda 개발자 안내서*에서 [Lambda 할당량](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)을 참조하세요.
+ PostgreSQL과 마찬가지로 Athena는 길이 및 비교 목적으로 PostgreSQL `CHAR` 형식의 후행 공백을 의미상 중요하지 않은 것으로 취급합니다. 이는 `CHAR` 형식에만 적용되며 `VARCHAR` 형식에는 적용되지 않습니다. Athena는 `CHAR` 형식의 후행 공백을 무시하지만 `VARCHAR` 형식의 후행 공백은 유의미한 것으로 취급합니다.
+ 대/소문자를 구분하지 않는 [citext](https://www.postgresql.org/docs/current/citext.html) 문자열 데이터 유형을 사용하는 경우 PostgreSQL은 Athena와 다른, 대소문자를 구분하지 않는 데이터 비교를 사용합니다. 이러한 차이로 인해 SQL `JOIN` 작업 중에 데이터 불일치가 발생합니다. 이러한 문제를 해결하려면 PostgreSQL 커넥터 패스스루 쿼리 기능을 사용합니다. 자세한 내용은 이 문서의 후반부에 있는 [패스스루 쿼리](#connectors-postgres-passthrough-queries)를 참조하세요.

## 용어
<a name="connectors-postgresql-terms"></a>

다음 용어는 PostgreSQL 커넥터와 관련이 있습니다.
+ **데이터베이스 인스턴스** - 온프레미스, Amazon EC2 또는 Amazon RDS에 배포된 데이터베이스의 모든 인스턴스.
+ **핸들러** - 데이터베이스 인스턴스에 액세스하는 Lambda 핸들러. 핸들러는 메타데이터 또는 데이터 레코드용일 수 있습니다.
+ **메타데이터 핸들러** - 데이터베이스 인스턴스에서 메타데이터를 검색하는 Lambda 핸들러.
+ **레코드 핸들러** - 데이터베이스 인스턴스에서 데이터 레코드를 검색하는 Lambda 핸들러.
+ **복합 핸들러** - 데이터베이스 인스턴스에서 메타데이터와 데이터 레코드를 모두 검색하는 Lambda 핸들러.
+ **속성 또는 파라미터** - 핸들러에서 데이터베이스 정보를 추출하는 데 사용되는 데이터베이스 속성. 이러한 속성을 Lambda 환경 변수로 구성합니다.
+ **연결 문자열** - 데이터베이스 인스턴스에 대한 연결을 설정하는 데 사용되는 텍스트 문자열.
+ **카탈로그** - `connection_string` 속성의 필수 접두사로서 Athena에 등록된 비 AWS Glue Glue 카탈로그.
+ **멀티플렉싱 핸들러** - 여러 데이터베이스 연결을 수락하고 사용할 수 있는 Lambda 핸들러.

## 파라미터
<a name="connectors-postgresql-parameters"></a>

이 섹션의 파라미터를 사용하여 PostgreSQL 커넥터를 구성합니다.

**참고**  
2024년 12월 3일 이후에 생성된 Athena 데이터 소스 커넥터는 AWS Glue 연결을 사용합니다.

### Glue 연결(권장)
<a name="connectors-postgresql-gc"></a>

Glue 연결 객체를 사용하여 PostgreSQL 커넥터를 구성하는 것이 좋습니다.

이렇게 하려면 PostgreSQL 커넥터 Lambda의 `glue_connection` 환경 변수를 사용할 Glue 연결 이름으로 설정합니다.

다음 명령을 사용하여 Glue 연결 객체에 대한 스키마를 가져옵니다. 이 스키마에는 연결을 제어할 때 사용할 수 있는 모든 파라미터가 포함되어 있습니다.

```
aws glue describe-connection-type --connection-type POSTGRESQL
```

**Lambda 환경 속성**

**glue\$1connection** - 페더레이션 커넥터와 연결된 Glue 연결의 이름을 지정합니다.

**참고**  
Glue 연결을 사용하는 모든 커넥터는 AWS Secrets Manager를 사용하여 자격 증명을 저장해야 합니다.
Glue 연결을 사용하여 생성된 PostgreSQL 커넥터는 멀티플렉싱 핸들러 사용을 지원하지 않습니다.
Glue 연결을 사용하여 생성된 PostgreSQL 커넥터는 `ConnectionSchemaVersion` 2만 지원합니다.

### 레거시 연결
<a name="connectors-postgresql-connection-legacy"></a>

아래에 나열된 파라미터 이름과 정의는 연결된 Glue 연결 없이 생성된 Athena 데이터 소스 커넥터에 대한 것입니다. Athena 데이터 소스 커넥터의 이전 버전을 [수동으로 배포](connect-data-source-serverless-app-repo.md)하거나 `glue_connection` 환경 속성이 지정되지 않은 경우에만 다음 파라미터를 사용합니다.

#### 연결 문자열
<a name="connectors-postgresql-connection-string"></a>

다음 형식의 JDBC 연결 문자열을 사용하여 데이터베이스 인스턴스에 연결합니다.

```
postgres://${jdbc_connection_string}
```

#### 멀티플렉싱 핸들러 사용
<a name="connectors-postgresql-using-a-multiplexing-handler"></a>

멀티플렉서를 사용하여 단일 Lambda 함수로 여러 데이터베이스 인스턴스에 연결할 수 있습니다. 요청은 카탈로그 이름을 기준으로 라우팅됩니다. Lambda에서 다음 클래스를 사용합니다.


****  

| 핸들러 | Class | 
| --- | --- | 
| 복합 핸들러 | PostGreSqlMuxCompositeHandler | 
| 메타데이터 핸들러 | PostGreSqlMuxMetadataHandler | 
| 레코드 핸들러 | PostGreSqlMuxRecordHandler | 

##### 멀티플렉싱 핸들러 파라미터
<a name="connectors-postgresql-multiplexing-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| \$1catalog\$1connection\$1string | 필수 사항입니다. 데이터베이스 인스턴스 연결 문자열. Athena에서 사용되는 카탈로그의 이름을 환경 변수 앞에 붙입니다. 예를 들어, Athena에 등록된 카탈로그가 mypostgrescatalog인 경우 환경 변수 이름은 mypostgrescatalog\$1connection\$1string입니다. | 
| default | 필수 사항입니다. 기본 연결 문자열. 이 문자열은 카탈로그가 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1일 때 사용됩니다. | 

다음은 `postgres1`(기본값)과 `postgres2`라는 2개의 데이터베이스 인스턴스를 지원하는 PostGreSql MUX Lambda 함수에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 | 
| postgres\$1catalog1\$1connection\$1string | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 | 
| postgres\$1catalog2\$1connection\$1string | postgres://jdbc:postgresql://postgres2.host:5432/default?user=sample&password=sample | 

##### 자격 증명 제공
<a name="connectors-postgresql-providing-credentials"></a>

JDBC 연결 문자열에서 데이터베이스의 사용자 이름과 암호를 제공하려면 연결 문자열 속성 또는 AWS Secrets Manager를 사용합니다.
+ **연결 문자열** - 사용자 이름과 암호를 JDBC 연결 문자열에 속성으로 지정할 수 있습니다.
**중요**  
보안 모범 사례로, 환경 변수 또는 연결 문자열에서 하드 코딩된 자격 증명은 사용하지 않습니다. 하드 코딩된 보안 암호를 AWS Secrets Manager로 이동하는 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [하드 코딩된 보안 암호를 AWS Secrets Manager로 이동](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)을 참조하세요.
+ **AWS Secrets Manager** - AWS Secrets Manager에서 Athena 연합 쿼리 기능을 사용하려면 Secrets Manager 연결을 위한 [VPC 엔드포인트](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) 또는 [인터넷 액세스](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)가 Lambda 함수에 연결된 VPC에 있어야 합니다.

  JDBC 연결 문자열에 AWS Secrets Manager의 보안 암호 이름을 입력할 수 있습니다. 커넥터는 암호 이름을 Secrets Manager의 `username` 및 `password` 값으로 바꿉니다.

  Amazon RDS 데이터베이스 인스턴스의 경우 이 지원은 긴밀하게 통합됩니다. Amazon RDS를 사용하는 경우 AWS Secrets Manager 및 자격 증명 교체를 사용하는 것이 좋습니다. 데이터베이스에서 Amazon RDS를 사용하지 않는 경우 자격 증명을 다음 형식의 JSON으로 저장합니다.

  ```
  {"username": "${username}", "password": "${password}"}
  ```

**보안 암호 이름이 있는 연결 문자열의 예제**  
다음 문자열의 보안 암호 이름은 `${Test/RDS/PostGres1}`입니다.

```
postgres://jdbc:postgresql://postgres1.host:5432/default?...&${Test/RDS/PostGres1}&...
```

커넥터는 다음 예제와 같이 보안 암호 이름을 사용하여 보안 암호를 검색하고 사용자 이름과 암호를 제공합니다.

```
postgres://jdbc:postgresql://postgres1.host:5432/default?...&user=sample2&password=sample2&...
```

현재 PostgreSQL 커넥터는 `user` 및 `password` JDBC 속성을 인식합니다.

##### SSL 활성화
<a name="connectors-postgresql-ssl"></a>

PostgreSQL 연결에서 SSL을 지원하려면 연결 문자열에 다음을 추가합니다.

```
&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory
```

**예제**  
다음 연결 문자열 예제에서는 SSL을 사용하지 않습니다.

```
postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword
```

SSL을 활성화하려면 다음과 같이 문자열을 수정합니다.

```
postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory
```

#### 단일 연결 핸들러 사용
<a name="connectors-postgresql-using-a-single-connection-handler"></a>

다음과 같은 단일 연결 메타데이터 및 레코드 핸들러를 사용하여 단일 PostgreSQL 인스턴스에 연결할 수 있습니다.


****  

| 핸들러 유형 | Class | 
| --- | --- | 
| 복합 핸들러 | PostGreSqlCompositeHandler | 
| 메타데이터 핸들러 | PostGreSqlMetadataHandler | 
| 레코드 핸들러 | PostGreSqlRecordHandler | 

##### 단일 연결 핸들러 파라미터
<a name="connectors-postgresql-single-connection-handler-parameters"></a>


****  

| 파라미터 | 설명 | 
| --- | --- | 
| default | 필수 사항입니다. 기본 연결 문자열. | 

단일 연결 핸들러는 하나의 데이터베이스 인스턴스를 지원하며 `default` 연결 문자열 파라미터를 제공해야 합니다. 다른 연결 문자열은 모두 무시됩니다.

다음은 Lambda 함수에서 지원하는 단일 PostgreSQL 인스턴스에 대한 예제 속성입니다.


****  

| 속성 | 값 | 
| --- | --- | 
| default | postgres://jdbc:postgresql://postgres1.host:5432/default?secret=\$1\$1Test/RDS/PostgreSQL1\$1 | 

#### 유출 파라미터
<a name="connectors-postgresql-spill-parameters"></a>

Lambda SDK는 데이터를 Amazon S3로 유출할 수 있습니다. 동일한 Lambda 함수에서 액세스하는 모든 데이터베이스 인스턴스는 동일한 위치로 유출됩니다.


****  

| 파라미터 | 설명 | 
| --- | --- | 
| spill\$1bucket | 필수 사항입니다. 유출 버킷 이름. | 
| spill\$1prefix | 필수 사항입니다. 유출 버킷 키 접두사. | 
| spill\$1put\$1request\$1headers | (선택 사항) 유출에 사용되는 Amazon S3 putObject 요청에 대한 요청 헤더 및 값의 JSON 인코딩 맵(예: \$1"x-amz-server-side-encryption" : "AES256"\$1). 다른 가능한 헤더를 알아보려면 Amazon Simple Storage Service API Reference(Amazon Simple Storage Service API 참조)의 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)를 참조하세요. | 

## 데이터 형식 지원
<a name="connectors-postgresql-data-type-support"></a>

다음 표에 JDBC, PostGreSQL 및 Arrow의 해당 데이터 형식이 나와 있습니다.


****  

| JDBC | PostGreSQL | 화살표 | 
| --- | --- | --- | 
| 부울 | 부울 | Bit | 
| Integer | 해당 사항 없음 | Tiny | 
| Short | smallint | Smallint | 
| Integer | 정수 | 정수 | 
| Long | bigint | Bigint | 
| 실수 | float4 | Float4 | 
| 배정밀도 실수 | float8 | Float8 | 
| 날짜 | 날짜 | DateDay | 
| 타임스탬프 | timestamp | DateMilli | 
| 문자열 | 텍스트 | Varchar | 
| 바이트 | bytes | Varbinary | 
| BigDecimal | numeric(p,s) | 10진수 | 
| ARRAY | 해당 사항 없음(참고 사항 참조) | List | 

**참고**  
`ARRAY` 형식은 다차원 배열(`<data_type>[][]` 또는 중첩 배열)은 지원되지 않는다는 제약 조건이 있는 PostgreSQL 커넥터에 대해 지원됩니다. 지원되지 않는 `ARRAY` 데이터 형식이 있는 열은 문자열 요소의 배열(`array<varchar>`)로 변환됩니다.

## 파티션 및 분할
<a name="connectors-postgresql-partitions-and-splits"></a>

파티션은 커넥터에 대한 분할을 생성하는 방법을 결정하는 데 사용됩니다. Athena는 커넥터가 분할을 생성하는 데 도움이 되도록 테이블에 대한 파티셔닝 체계를 나타내는 `varchar` 유형의 합성 열을 생성합니다. 커넥터는 실제 테이블 정의를 수정하지 않습니다.

## 성능
<a name="connectors-postgresql-performance"></a>

PostgreSQL은 기본 파티션을 지원합니다. Athena PostgreSQL 커넥터는 이러한 파티션에서 병렬로 데이터를 검색할 수 있습니다. 파티션 배포가 균일한 초대규모 데이터 세트를 쿼리하려면 기본 파티셔닝을 사용하는 것이 좋습니다.

Athena PostgreSQL 커넥터는 조건부 푸시다운을 수행하여 쿼리에서 스캔하는 데이터를 줄입니다. `LIMIT` 절, 간단한 조건자 및 복잡한 표현식을 커넥터로 푸시다운하여 스캔하는 데이터와 쿼리 실행 시간을 줄입니다. 그러나 열 하위 세트를 선택할 때 쿼리 실행 런타임이 길어지는 경우가 있습니다.

### LIMIT 절
<a name="connectors-postgres-performance-limit-clauses"></a>

`LIMIT N` 문은 쿼리로 스캔하는 데이터를 줄입니다. `LIMIT N` 푸시다운을 통해 커넥터는 Athena에 `N`개 행만 반환합니다.

### Predicates
<a name="connectors-postgres-performance-predicates"></a>

조건자는 부울 값으로 평가되고 여러 조건에 따라 행을 필터링하는 SQL 쿼리의 `WHERE` 절에 사용되는 표현식입니다. Athena PostgreSQL 커넥터는 이러한 표현식을 결합하고 PostgreSQL로 직접 푸시하여 기능을 개선하고 스캔하는 데이터를 줄일 수 있습니다.

다음 Athena PostgreSQL 커넥터 연산자는 조건자 푸시다운을 지원합니다.
+ **부울: **AND, OR, NOT
+ **관계: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL
+ **산술: **ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE
+ **기타: **LIKE\$1PATTERN, IN

### 결합된 푸시다운 예제
<a name="connectors-postgres-performance-pushdown-example"></a>

쿼리 기능을 개선하기 위해 다음 예제와 같이 푸시다운 유형을 결합합니다.

```
SELECT * 
FROM my_table 
WHERE col_a > 10 
    AND ((col_a + col_b) > (col_c % col_d))
    AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') 
LIMIT 10;
```

## 패스스루 쿼리
<a name="connectors-postgres-passthrough-queries"></a>

PostgreSQL 커넥터는 [패스스루 쿼리](federated-query-passthrough.md)를 지원합니다. 패스스루 쿼리는 테이블 함수를 사용하여 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운합니다.

PostgreSQL에서 패스스루 쿼리를 사용하려면 다음 구문을 사용합니다.

```
SELECT * FROM TABLE(
        system.query(
            query => 'query string'
        ))
```

다음 예제 쿼리는 PostgreSQL의 데이터 소스로 쿼리를 푸시다운합니다. 쿼리는 `customer` 테이블의 모든 열을 선택하여 결과를 10개로 제한합니다.

```
SELECT * FROM TABLE(
        system.query(
            query => 'SELECT * FROM customer LIMIT 10'
        ))
```

## 추가 리소스
<a name="connectors-postgresql-additional-resources"></a>

최신 JDBC 드라이버 버전 정보를 알아보려면 GitHub.com의 PostgreSQL 커넥터용 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-postgresql/pom.xml) 파일을 참조하세요.

이 커넥터에 대한 추가 정보를 알아보려면 GitHub.com의 [해당 사이트](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-postgresql)를 참조하세요.