# Aurora DSQL용 커넥터
<a name="SECTION_connectors"></a>

Aurora DSQL은 기존 데이터베이스 드라이버를 확장하여 AWS 서비스와의 원활한 IAM 인증 및 통합을 지원하는 전용 커넥터를 제공합니다. 이러한 커넥터는 기존 PostgreSQL 워크플로와의 호환성을 유지하면서 널리 사용되는 프로그래밍 언어 및 프레임워크와 함께 작동하도록 설계되었습니다.

향후 릴리스에 추가 커넥터가 계획되어 있습니다. 커넥터 가용성에 대한 최신 정보는 [Aurora DSQL 샘플 리포지토리](https://github.com/aws-samples/aurora-dsql-samples)를 참조하세요.

# JDBC 커넥터를 사용하여 Aurora DSQL 클러스터에 연결
<a name="SECTION_program-with-jdbc-connector"></a>

[JDBC용 Aurora DSQL 커넥터](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc)는 애플리케이션이 IAM 자격 증명을 사용하여 Aurora DSQL로 인증할 수 있도록 PostgreSQL JDBC 드라이버의 기능을 확장하는 인증 플러그인으로 설계되었습니다. 커넥터는 데이터베이스에 직접 연결되지 않지만 기본 PostgreSQL JDBC 드라이버를 기반으로 원활한 IAM 인증을 제공합니다.

JDBC용 Aurora DSQL 커넥터는 [PostgreSQL JDBC 드라이버](https://github.com/pgjdbc/pgjdbc)와 함께 작동하도록 빌드되었으며 Aurora DSQL의 IAM 인증 요구 사항과 원활하게 통합됩니다.

JDBC용 Aurora DSQL 커넥터는 PostgreSQL JDBC 드라이버와 함께 사용 시 Aurora DSQL에 대한 IAM 기반 인증을 지원합니다. [AWS Identity and Access Management](https://aws.amazon.com/iam/)(IAM)과 같은 AWS 인증 서비스와의 심층 통합을 제공합니다.

## 커넥터 정보
<a name="SECTION_program-with-jdbc-connector-about"></a>

Aurora DSQL은 PostgreSQL 호환 애플리케이션에 고가용성과 확장성을 제공하는 분산된 SQL 데이터베이스 서비스입니다. Aurora DSQL에는 기존 JDBC 드라이버가 기본적으로 지원하지 않는 시간 제한 토큰을 사용한 IAM 기반 인증이 필요합니다.

JDBC용 Aurora DSQL 커넥터의 기본 개념은 IAM 토큰 생성을 처리하는 PostgreSQL JDBC 드라이버 위에 인증 계층을 추가하여 사용자가 기존 JDBC 워크플로를 변경하지 않고도 Aurora DSQL에 연결할 수 있도록 하는 것입니다.

### Aurora DSQL 인증이란 무엇입니까?
<a name="SECTION_program-with-jdbc-connector-authentication"></a>

Aurora DSQL에서 **인증**에는 다음이 포함됩니다.
+ **IAM 인증**: 모든 연결은 시간 제한 토큰이 있는 IAM 기반 인증을 사용합니다.
+ **토큰 생성**: 인증 토큰은 AWS 자격 증명을 사용하여 생성되며 구성 가능한 수명이 있습니다.

JDBC용 Aurora DSQL 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성하도록 설계되었습니다.

### JDBC용 Aurora DSQL 커넥터의 이점
<a name="SECTION_program-with-jdbc-connector-benefits"></a>

Aurora DSQL은 PostgreSQL 호환 인터페이스를 제공하지만 기존 PostgreSQL 드라이버는 현재 Aurora DSQL의 IAM 인증 요구 사항을 지원하지 않습니다. JDBC용 Aurora DSQL 커넥터를 사용하면 다음을 통해 IAM 인증을 활성화하면서 기존 PostgreSQL 워크플로를 계속 사용할 수 있습니다.
+ **자동 토큰 생성**: AWS 자격 증명을 사용하여 IAM 토큰이 자동으로 생성됨
+ **원활한 통합**: 기존 JDBC 연결 패턴과 함께 작동함
+ **AWS 자격 증명 지원**: 다양한 AWS 자격 증명 공급자(기본값, 프로필 기반 등) 지원

### 연결 풀링과 함께 JDBC용 Aurora DSQL 커넥터 사용
<a name="SECTION_program-with-jdbc-connector-connection-pooling"></a>

JDBC용 Aurora DSQL 커넥터는 HikariCP와 같은 연결 풀링 라이브러리에서 작동합니다. 커넥터는 연결 설정 중에 IAM 토큰 생성을 처리하여 연결 풀이 정상적으로 작동할 수 있도록 합니다.

## 주요 기능
<a name="SECTION_program-with-jdbc-connector-features"></a>

자동 토큰 생성  
IAM 토큰은 AWS 자격 증명을 사용하여 자동으로 생성됩니다.

원활한 통합  
기존 JDBC 연결 패턴과 호환되며 워크플로 변경 없이 작동합니다.

AWS 자격 증명 지원  
다양한 AWS 자격 증명 공급자(기본값, 프로필 기반 등)를 지원합니다.

연결 풀링 호환성  
HikariCP와 같은 연결 풀링 라이브러리와 원활하게 작동합니다.

## 사전 조건
<a name="SECTION_program-with-jdbc-connector-prerequisites"></a>

시작하기 전에 다음 사전 조건을 완료했는지 확인합니다.
+ [Aurora DSQL에 클러스터 생성](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ JDK(Java Development Kit) 생성 버전 17 이상이 있는지 확인
+ 애플리케이션이 Aurora DSQL에 연결할 수 있도록 적절한 IAM 권한 설정
+ AWS CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성

## 기본 연결에 JDBC용 Aurora DSQL 커넥터 사용
<a name="SECTION_program-with-jdbc-connector-usage"></a>

Java 애플리케이션에서 JDBC용 Aurora DSQL 커넥터를 사용하려면 다음 단계를 따르세요.

1. 다음 종속성을 Maven 프로젝트에 추가합니다.

   ```
   <dependencies>
       <!-- Aurora DSQL Connector for JDBC -->
       <dependency>
           <groupId>software.amazon.dsql</groupId>
           <artifactId>aurora-dsql-jdbc-connector</artifactId>
           <version>1.0.0</version>
       </dependency>
   </dependencies>
   ```

   Gradle 프로젝트의 경우 다음 종속성을 추가합니다.

   ```
   implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:1.0.0")
   ```

1. AWS DSQL PostgreSQL 커넥터 형식을 사용하여 Aurora DSQL 클러스터에 대한 기본 연결을 생성합니다.

   ```
   import java.sql.Connection;
   import java.sql.DriverManager;
   import java.sql.ResultSet;
   import java.sql.SQLException;
   import java.sql.Statement;
   
   public class DsqlJdbcConnectorExample {
       public static void main(String[] args) {
           // Using AWS DSQL PostgreSQL Connector prefix
           String jdbcUrl = "jdbc:aws-dsql:postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin";
           
           try (Connection connection = DriverManager.getConnection(jdbcUrl)) {
               // Use the connection
               try (Statement statement = connection.createStatement()) {
                   // Create a table
                   statement.execute("CREATE TABLE IF NOT EXISTS test_table (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name VARCHAR(100))");
                   
                   // Insert data
                   statement.execute("INSERT INTO test_table (name) VALUES ('Test Name')");
                   
                   // Query data
                   try (ResultSet resultSet = statement.executeQuery("SELECT * FROM test_table")) {
                       while (resultSet.next()) {
                           System.out.println("ID: " + resultSet.getInt("id") + ", Name: " + resultSet.getString("name"));
                       }
                   }
               }
               
           } catch (SQLException e) {
               e.printStackTrace();
           }
       }
   }
   ```

### 구성 속성
<a name="SECTION_program-with-jdbc-connector-properties"></a>

JDBC용 Aurora DSQL 커넥터는 다음 연결 속성을 지원합니다.

user  
연결에 사용될 사용자 및 토큰 생성 방법을 결정합니다. 예시: `admin`

token-duration-secs  
토큰 유효 기간(초 단위)입니다. 토큰 제한에 대한 자세한 내용은 [Amazon Aurora DSQL에서 인증 토큰 생성](SECTION_authentication-token.md)을 참조하세요.

profile  
제공된 프로필 이름으로 토큰 생성을 위한 ProfileCredentialsProvider를 인스턴스화하는 데 사용됩니다.

region  
Aurora DSQL 연결을 위한 AWS 리전입니다. 이는 선택 사항입니다. 제공된 경우 URL에서 추출된 리전을 재정의합니다.

데이터베이스  
연결할 데이터베이스 이름입니다. 기본값은 `postgres`입니다.

### 로깅
<a name="SECTION_program-with-jdbc-connector-logging"></a>

Aurora DSQL JDBC 커넥터를 사용하는 동안 발생할 수 있는 문제를 해결하기 위해 로깅을 활성화합니다.

이 커넥터는 Java의 내장 로깅 시스템(java.util.logging)을 사용합니다. `logging.properties` 파일을 생성하여 로깅 수준을 구성할 수 있습니다.

```
# Set root logger level to INFO for clean output
.level = INFO

# Show Aurora DSQL Connector for JDBC FINE logs for detailed debugging
software.amazon.dsql.level = FINE

# Console handler configuration
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

# Detailed formatter pattern with timestamp and logger name
java.util.logging.SimpleFormatter.format = %1$tH:%1$tM:%1$tS.%1$tL [%4$s] %3$s - %5$s%n
```

### 예제
<a name="SECTION_program-with-jdbc-connector-examples"></a>

보다 포괄적인 예제 및 사용 사례는 다음을 포함하는 [JDBC용 Aurora DSQL 커넥터 리포지토리](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples)를 참조하세요.

# Python용 Aurora DSQL 커넥터
<a name="SECTION_program-with-dsql-connector-for-python"></a>

 [Python용 Aurora DSQL 커넥터](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector)는 Python 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합합니다. 내부적으로는 [psycopg](https://github.com/psycopg/psycopg), [psycopg2](https://github.com/psycopg/psycopg2) 및 [asyncpg](https://github.com/MagicStack/asyncpg) 클라이언트 라이브러리를 활용합니다.

 Python용 Aurora DSQL 커넥터는 psycopg, psycopg2, 및 asyncpg 클라이언트 및 라이브러리를 확장하는 인증 플러그인으로 설계되어 애플리케이션이 IAM 자격 증명을 사용하여 Amazon Aurora DSQL과 인증할 수 있도록 합니다. 커넥터는 데이터베이스에 직접 연결되지 않지만 기본 클라이언트 라이브러리를 기반으로 원활한 IAM 인증을 제공합니다.

## 커넥터 정보
<a name="about-the-connector"></a>

 Amazon Aurora DSQL은 PostgreSQL 호환 애플리케이션에 고가용성과 확장성을 제공하는 분산된 SQL 데이터베이스 서비스입니다. Aurora DSQL에는 기존 Python 라이브러리가 기본적으로 지원하지 않는 시간 제한 토큰을 사용한 IAM 기반 인증이 필요합니다.

 Python용 Aurora DSQL 커넥터의 개념은 IAM 토큰 생성을 처리하는 psycopg, psycopg2 및 asyncpg 클라이언트 라이브러리 위에 인증 계층을 추가하여 사용자가 기존 워크플로를 변경하지 않고도 Aurora DSQL에 연결할 수 있도록 하는 것입니다.

### Aurora DSQL 인증이란 무엇입니까?
<a name="what-is-aurora-dsql-authentication"></a>

 Aurora DSQL에서 인증에는 다음이 포함됩니다.
+  **IAM 인증**: 모든 연결은 시간 제한 토큰이 있는 IAM 기반 인증을 사용합니다.
+  **토큰 생성:** 인증 토큰은 AWS 자격 증명을 사용하여 생성되며 구성 가능한 수명이 있습니다.

 Python용 Aurora DSQL 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성하도록 설계되었습니다.

### 특성
<a name="features"></a>
+  **자동 IAM 인증** - IAM 토큰은 AWS 자격 증명을 사용하여 자동으로 생성됩니다.
+  **psycopg, psycopg2 및 asyncpg 기반** - psycopg, psycopg2 및 asyncpg 클라이언트 라이브러리 활용 
+  **원활한 통합** - 워크플로 변경 없이 기존 psycopg, psycopg2 및 asyncpg 연결 패턴과 함께 작동 
+  **리전 자동 검색** - DSQL 클러스터 호스트 이름에서 AWS 리전 추출 
+  **AWS 자격 증명 지원** - 다양한 AWS 자격 증명 공급자(기본값, 프로필 기반, 사용자 지정) 지원 
+  **연결 풀링 호환성** - psycopg, psycopg2 및 asyncpg 내장 연결 풀링과 함께 사용 가능 

## 빠른 시작 설명서
<a name="quick-start-guide"></a>

### 요구 사항
<a name="requirements"></a>
+  Python 3.10 이상 
+  [Aurora DSQL 클러스터에 대한 액세스](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  애플리케이션이 Aurora DSQL에 연결할 수 있도록 적절한 IAM 권한 설정 
+  AWS CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성 

### 설치
<a name="installation"></a>

```
pip install aurora-dsql-python-connector
```

#### psycopg 또는 psycopg2 또는 asyncpg를 별도로 설치
<a name="install-psycopg-or-psycopg2-or-asyncpg-separately"></a>

 Python용 Aurora DSQL 커넥터 설치 관리자는 기본 라이브러리를 설치하지 않습니다. 별도로 설치해야 합니다. 예: 

```
# Install psycopg and psycopg pool
pip install "psycopg[binary,pool]"
```

```
# Install psycopg2
pip install psycopg2-binary
```

```
# Install asyncpg
pip install asyncpg
```

 **참고:** 

 필요한 라이브러리만 설치해야 합니다. 따라서 클라이언트가 psycopg를 사용할 경우 psycopg만 설치하면 됩니다. 클라이언트가 psycopg2를 사용하려는 경우 psycopg2만 설치하면 됩니다. 클라이언트가 asyncpg를 사용하려는 경우 asyncpg만 설치하면 됩니다.

 클라이언트에 둘 이상 필요한 경우 필요한 모든 라이브러리를 설치해야 합니다.

### 기본 사용법
<a name="basic-usage"></a>

#### psycopg
<a name="psycopg"></a>

```
    import aurora_dsql_psycopg as dsql

    config = {
        'host': "your-cluster.dsql.us-east-1.on.aws",
        'region': "us-east-1",
        'user': "admin",
    }
        
    conn = dsql.connect(**config)
    with conn.cursor() as cur:
        cur.execute("SELECT 1")
        result = cur.fetchone()
        print(result)
```

#### psycopg2
<a name="psycopg2"></a>

```
    import aurora_dsql_psycopg2 as dsql

    config = {
        'host': "your-cluster.dsql.us-east-1.on.aws",
        'region': "us-east-1",
        'user': "admin",
    }
        
    conn = dsql.connect(**config)
    with conn.cursor() as cur:
        cur.execute("SELECT 1")
        result = cur.fetchone()
        print(result)
```

#### asyncpg
<a name="asyncpg"></a>

```
    import asyncio 
    import aurora_dsql_asyncpg as dsql 

    config = {
        'host': "your-cluster.dsql.us-east-1.on.aws",
        'region': "us-east-1",
        'user': "admin",
    }

    conn = await dsql.connect(**config)
    result = await conn.fetchrow("SELECT 1")
    await conn.close()
    print(result)
```

#### 호스트만 사용
<a name="using-just-host"></a>

##### psycopg
<a name="psycopg-1"></a>

```
    import aurora_dsql_psycopg as dsql

    conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```

##### psycopg2
<a name="psycopg2-1"></a>

```
    import aurora_dsql_psycopg2 as dsql

    conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```

##### asyncpg
<a name="asyncpg-1"></a>

```
    import asyncio 
    import aurora_dsql_asyncpg as dsql 

    conn = await dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```

#### 클러스터 ID만 사용
<a name="using-just-cluster-id"></a>

##### psycopg
<a name="psycopg-2"></a>

```
    import aurora_dsql_psycopg as dsql

    conn = dsql.connect("your-cluster")
```

##### psycopg2
<a name="psycopg2-2"></a>

```
    import aurora_dsql_psycopg2 as dsql

    conn = dsql.connect("your-cluster")
```

##### asyncpg
<a name="asyncpg-2"></a>

```
    import asyncio 
    import aurora_dsql_asyncpg as dsql 

    conn = await dsql.connect("your-cluster")
```

 **참고:** 

 "클러스터 ID만 사용" 시나리오에서는 시스템에 이전에 설정된 리전이 사용됩니다. 예: 

```
aws configure set region us-east-1
```

 리전이 설정되지 않았거나 지정된 클러스터 ID가 다른 리전에 있는 경우 연결이 실패합니다. 작동하려면 아래 예제와 같이 리전을 파라미터로 제공합니다.

##### psycopg
<a name="psycopg-3"></a>

```
    import aurora_dsql_psycopg as dsql

    config = {
            "region": "us-east-1",
    }

    conn = dsql.connect("your-cluster", **config)
```

##### psycopg2
<a name="psycopg2-3"></a>

```
    import aurora_dsql_psycopg2 as dsql

    config = {
            "region": "us-east-1",
    }

    conn = dsql.connect("your-cluster", **config)
```

##### asyncpg
<a name="asyncpg-3"></a>

```
    import asyncio 
    import aurora_dsql_asyncpg as dsql 

    config = {
            "region": "us-east-1",
    }

    conn = await dsql.connect("your-cluster", **config)
```

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

#### psycopg
<a name="psycopg-4"></a>

```
    import aurora_dsql_psycopg as dsql

    conn = dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```

#### psycopg2
<a name="psycopg2-4"></a>

```
    import aurora_dsql_psycopg2 as dsql

    conn = dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```

#### asyncpg
<a name="asyncpg-4"></a>

```
    import asyncio 
    import aurora_dsql_asyncpg as dsql 

    conn = await dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```

### 고급 구성
<a name="advanced-configuration"></a>

#### psycopg
<a name="psycopg-5"></a>

```
    import aurora_dsql_psycopg as dsql

    config = {
        'host': "your-cluster.dsql.us-east-1.on.aws",
        'region': "us-east-1",
        'user': "admin",
        "profile": "default",
        "token_duration_secs": "15",
    }
        
    conn = dsql.connect(**config)
    with conn.cursor() as cur:
        cur.execute("SELECT 1")
        result = cur.fetchone()
        print(result)
```

#### psycopg2
<a name="psycopg2-5"></a>

```
    import aurora_dsql_psycopg2 as dsql

    config = {
        'host': "your-cluster.dsql.us-east-1.on.aws",
        'region': "us-east-1",
        'user': "admin",
        "profile": "default",
        "token_duration_secs": "15",
    }
        
    conn = dsql.connect(**config)
    with conn.cursor() as cur:
        cur.execute("SELECT 1")
        result = cur.fetchone()
        print(result)
```

#### asyncpg
<a name="asyncpg-5"></a>

```
    import asyncio 
    import aurora_dsql_asyncpg as dsql 

    config = {
        'host': "your-cluster.dsql.us-east-1.on.aws",
        'region': "us-east-1",
        'user': "admin",
        "profile": "default",
        "token_duration_secs": "15",
    }

    conn = await dsql.connect(**config)
    result = await conn.fetchrow("SELECT 1")
    await conn.close()
    print(result)
```

### 구성 옵션
<a name="configuration-options"></a>


|  옵션  |  Type  |  필수  |  설명  | 
| --- | --- | --- | --- | 
|  host  |  string  |  예  |  DSQL 클러스터 호스트 이름 또는 클러스터 ID  | 
|  user  |  string  |  아니요  |  DSQL 사용자 이름입니다. 기본값: admin  | 
|  dbname  |  string  |  아니요  |  데이터베이스 이름. 기본값: postgres  | 
|  region  |  string  |  아니요  |  AWS 리전(제공되지 않은 경우 호스트 이름에서 자동 감지됨)  | 
|  port  |  int  |  아니요  |  기본값: 5432  | 
|  custom\$1credentials\$1provider  |  CredentialProvider  |  아니요  |  사용자 지정 AWS 자격 증명 공급자  | 
|  profile  |  string  |  아니요  |  IAM 프로파일 이름입니다. 기본값: default  | 
|  token\$1duration\$1secs  |  int  |  아니요  |  초 단위의 토큰 만료 시간  | 

 DSQL에서 지원되지 않는 asyncpg 파라미터 **krbsrvname** 및 **gsslib**를 제외하고 기본 psycopg, psycopg2 및 asyncpg 라이브러리의 모든 표준 연결 옵션도 지원됩니다.

### 연결 풀링과 함께 Python용 Aurora DSQL 커넥터 사용
<a name="using-the-aurora-dsql-connector-for-python-with-connection-pooling"></a>

 Python용 Aurora DSQL 커넥터는 psycopg, psycopg2 및 asyncpg 내장 연결 풀링과 함께 작동합니다. 커넥터는 연결 설정 중에 IAM 토큰 생성을 처리하여 연결 풀이 정상적으로 작동할 수 있도록 합니다.

#### psycopg
<a name="psycopg-6"></a>

 psycopg의 경우 커넥터는 psycopg\$1pool.ConnectionPool 생성자로 직접 전달할 수 있는 DSQLConnection ConnectionPool 이라는 연결 클래스를 구현합니다. 비동기 작업의 경우 DSQLAsyncConnection 버전도 있습니다.

```
    from psycopg_pool import ConnectionPool as PsycopgPool
    
    ...
    pool = PsycopgPool(
        "",  
        connection_class=dsql.DSQLConnection,
        kwargs=conn_params,
        min_size=2,
        max_size=8,
        max_lifetime=3300
    )
```

 **참고: 연결 max\$1lifetime 구성** 

 max\$1lifetime 파라미터는 Aurora DSQL 데이터베이스에서 허용되는 최대 연결 기간이므로 3600초(1시간) 미만으로 설정해야 합니다. max\$1lifetime을 낮게 설정하면 연결 풀이 연결 재활용을 사전에 관리할 수 있으므로 데이터베이스의 연결 제한 시간 오류를 처리하는 것보다 더 효율적입니다.

#### psycopg2
<a name="psycopg2-6"></a>

 psycopg2의 경우 커넥터는 psycopg2.pool.ThreadedConnectionPool에서 상속되는 AuroraDSQLThreadedConnectionPool이라는 클래스를 제공합니다. AuroraDSQLThreadedConnectionPool 클래스는 내부 \$1connect 메서드만 재정의합니다. 나머지 구현은 psycopg2.pool.ThreadedConnectionPool에서 변경 없이 제공됩니다.

```
    import aurora_dsql_psycopg2 as dsql

    pool = dsql.AuroraDSQLThreadedConnectionPool(
            minconn=2,
            maxconn=8,
            **conn_params,
    )
```

#### asyncpg
<a name="asyncpg-6"></a>

 asyncpg의 경우 커넥터는 asyncpg.Pool의 인스턴스를 반환하는 create\$1pool 함수를 제공합니다.

```
    import asyncio
    import os

    import aurora_dsql_asyncpg as dsql

    pool_params = {
        'host': "your-cluster.dsql.us-east-1.on.aws",
        'user': "admin",
        "min_size": 2,
        "max_size": 5,
    }

    pool = await dsql.create_pool(**pool_params)
```

## Authentication
<a name="authentication"></a>

 커넥터는 DSQL 클라이언트 토큰 생성기를 사용하여 토큰을 생성하여 DSQL 인증을 자동으로 처리합니다. AWS 리전이 제공되지 않으면 제공된 호스트 이름에서 자동으로 구문 분석됩니다.

 Aurora DSQL의 인증에 대한 자세한 내용은 [사용 설명서](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)를 참조하세요.

### 관리자 및 일반 사용자
<a name="admin-vs-regular-users"></a>
+  `"admin"`이라는 사용자가 관리자 인증 토큰을 자동으로 사용 
+  다른 모든 사용자는 관리자가 아닌 인증 토큰을 사용합니다.
+  토큰은 각 연결에 대해 동적으로 생성됩니다.

## 예제
<a name="examples"></a>

 전체 예제 코드는 아래 섹션에 표시된 예제를 참조하세요. 예제를 실행하는 방법에 대한 지침은 예제 READMDE 파일을 참조하세요.

### psycopg
<a name="psycopg-7"></a>

 [예제 README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg/README.md) 


|  설명  |  예제  | 
| --- | --- | 
|  기본 연결에 Python용 Aurora DSQL 커넥터 사용  |  [기본 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  기본 비동기식 연결에 Python용 Aurora DSQL 커넥터 사용  |  [기본 비동기 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/no_connection_pool/example_async_with_no_connection_pool.py)  | 
|  연결 풀링과 함께 Python용 Aurora DSQL 커넥터 사용  |  [연결 풀을 사용하는 기본 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [연결 풀을 사용하는 동시 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  비동기 연결 풀과 함께 Python용 Aurora DSQL 커넥터 사용  |  [비동기 연결 풀을 사용한 기본 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_async_connection_pool.py)  | 

### psycopg2
<a name="psycopg2-7"></a>

 [예제 README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg2/README.md) 


|  설명  |  예제  | 
| --- | --- | 
|  기본 연결에 Python용 Aurora DSQL 커넥터 사용  |  [기본 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 
|  연결 풀링과 함께 Python용 Aurora DSQL 커넥터 사용  |  [연결 풀을 사용하는 기본 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [연결 풀을 사용하는 동시 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 

### asyncpg
<a name="asyncpg-7"></a>

 [예제 README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/asyncpg/README.md) 


|  설명  |  예제  | 
| --- | --- | 
|  기본 연결에 Python용 Aurora DSQL 커넥터 사용  |  [기본 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  | 
|  연결 풀링과 함께 Python용 Aurora DSQL 커넥터 사용  |  [연결 풀을 사용하는 기본 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [연결 풀을 사용하는 동시 연결 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  | 

# Go 커넥터를 사용하여 Aurora DSQL 클러스터에 연결
<a name="SECTION_program-with-go-pgx-connector"></a>

[Go용 Aurora DSQL 커넥터](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx)는 [pgx](https://github.com/jackc/pgx)를 자동 IAM 인증으로 래핑합니다. 커넥터는 토큰 생성, SSL 구성 및 연결 관리를 처리하므로 애플리케이션 로직에 집중할 수 있습니다.

## 커넥터 정보
<a name="SECTION_program-with-go-pgx-connector-about"></a>

Aurora DSQL에는 기존 Go PostgreSQL 드라이버가 기본적으로 지원하지 않는 시간 제한 토큰을 사용한 IAM 기반 인증이 필요합니다. Go용 Aurora DSQL 커넥터는 IAM 토큰 생성을 처리하는 pgx 드라이버 위에 인증 계층을 추가하여 기존 pgx 워크플로를 변경하지 않고도 Aurora DSQL에 연결할 수 있도록 합니다.

### Aurora DSQL 인증이란 무엇인가요?
<a name="SECTION_program-with-go-pgx-connector-authentication"></a>

Aurora DSQL에서 **인증**에는 다음이 포함됩니다.
+ **IAM 인증**: 모든 연결은 시간 제한 토큰이 있는 IAM 기반 인증을 사용합니다.
+ **토큰 생성**: 커넥터는 AWS 자격 증명을 사용하여 인증 토큰을 생성하며 이러한 토큰에는 구성 가능한 수명이 있습니다.

Go용 Aurora DSQL 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성하도록 설계되었습니다.

### Go용 Aurora DSQL 커넥터의 이점
<a name="SECTION_program-with-go-pgx-connector-benefits"></a>

Go용 Aurora DSQL 커넥터를 사용하면 기존 pgx 워크플로를 계속 사용하면서 IAM 인증을 활성화할 수 있습니다.
+ **자동 토큰 생성**: 커넥터가 각 연결에 대해 IAM 토큰을 자동으로 생성
+ **연결 풀링**: 연결마다 자동으로 토큰을 생성하여 `pgxpool` 기본 지원
+ **유연한 구성**: 리전 자동 감지를 통해 전체 엔드포인트 또는 클러스터 ID 지원
+ **AWS 자격 증명 지원**: AWS 프로파일 및 사용자 지정 자격 증명 공급자 지원

## 주요 기능
<a name="SECTION_program-with-go-pgx-connector-features"></a>

자동 토큰 관리  
커넥터가 사전 확인된 자격 증명을 사용하여 새 연결마다 IAM 토큰을 자동으로 생성합니다.

연결 풀링  
연결마다 자동으로 토큰을 생성하여 `pgxpool`을 통해 연결을 풀링합니다.

유연한 호스트 구성  
자동 리전 감지를 통해 전체 클러스터 엔드포인트와 클러스터 ID를 모두 지원합니다.

SSL 보안  
SSL은 항상 verify-full 모드와 직접 TLS 협상으로 활성화됩니다.

## 사전 조건
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ Go 1.24 이상
+ AWS 자격 증명이 구성됨
+ Aurora DSQL 클러스터

커넥터는 다음 순서로 자격 증명을 확인하는 [AWS SDK for Go v2 기본 자격 증명 체인](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials)을 사용합니다.

1. 환경 변수(AWS\$1ACCESS\$1KEY\$1ID, AWS\$1SECRET\$1ACCESS\$1KEY)

1. 공유 자격 증명 파일(\$1/.aws/credentials)

1. 공유 구성 파일(\$1/.aws/config)

1. Amazon EC2/ECS/Lambda에 대한 IAM 역할

## 설치
<a name="SECTION_program-with-go-pgx-connector-installation"></a>

Go 모듈을 사용하여 커넥터 설치:

```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql
```

## 빠른 시작
<a name="SECTION_program-with-go-pgx-connector-quick-start"></a>

다음 예제에서는 연결 풀을 만들고 쿼리를 실행하는 방법을 보여줍니다.

```
package main

import (
    "context"
    "log"
    
    "github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql"
)

func main() {
    ctx := context.Background()
    
    // Create a connection pool
    pool, err := dsql.NewPool(ctx, dsql.Config{
        Host: "your-cluster.dsql.us-east-1.on.aws",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()
    
    // Execute a query
    var greeting string
    err = pool.QueryRow(ctx, "SELECT 'Hello, DSQL!'").Scan(&greeting)
    if err != nil {
        log.Fatal(err)
    }
    log.Println(greeting)
}
```

## 구성 옵션
<a name="SECTION_program-with-go-pgx-connector-configuration"></a>

커넥터는 다음과 같은 구성 옵션을 지원합니다.


| Field | Type | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| Host | 문자열 | (필수) | 클러스터 엔드포인트 또는 클러스터 ID | 
| 리전 | 문자열 | (자동 탐지됨) | AWS 리전, 호스트가 클러스터 ID인 경우 필수 | 
| User | 문자열 | "admin" | 데이터베이스 사용자 | 
| 데이터베이스 | 문자열 | "postgres" | 데이터베이스 이름 | 
| Port | int | 5432 | 데이터베이스 포트 | 
| 프로필 | 문자열 | "" | 자격 증명의 AWS 프로파일 이름 | 
| TokenDurationSecs | int | 900(15분) | 초 단위의 토큰 유효 기간(최대 허용: 1주, 기본값: 15분) | 
| MaxConns | int32 | 0 | 최대 풀 연결(0 = pgxpool 기본값) | 
| MinConns | int32 | 0 | 최소 풀 연결(0 = pgxpool 기본값) | 
| MaxConnLifetime | time.Duration | 55분 | 최대 연결 수명 | 

## 연결 문자열 형식
<a name="SECTION_program-with-go-pgx-connector-connection-string"></a>

커넥터는 다음의 PostgreSQL 및 DSQL 연결 문자열 형식을 지원합니다.

```
postgres://[user@]host[:port]/[database][?param=value&...]
dsql://[user@]host[:port]/[database][?param=value&...]
```

지원되는 쿼리 파라미터:
+ `region` - AWS 리전
+ `profile` - AWS 프로파일 이름
+ `tokenDurationSecs` - 토큰 유효 기간(초 단위)

예시:

```
// Full endpoint (region auto-detected)
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres")

// Using dsql:// scheme (also supported)
pool, _ := dsql.NewPool(ctx, "dsql://admin@cluster.dsql.us-east-1.on.aws/postgres")

// With explicit region
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/mydb?region=us-east-1")

// With AWS profile
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev")
```

## 고급 사용
<a name="SECTION_program-with-go-pgx-connector-advanced"></a>

### 호스트 구성
<a name="SECTION_program-with-go-pgx-connector-host-config"></a>

커넥터는 다음의 두 가지 호스트 형식을 지원합니다.

**전체 엔드포인트**(리전 자동 감지됨):

```
pool, _ := dsql.NewPool(ctx, dsql.Config{
    Host: "your-cluster.dsql.us-east-1.on.aws",
})
```

**클러스터 ID**(리전 필요):

```
pool, _ := dsql.NewPool(ctx, dsql.Config{
    Host:   "your-cluster-id",
    Region: "us-east-1",
})
```

### 풀 구성 튜닝
<a name="SECTION_program-with-go-pgx-connector-pool-tuning"></a>

워크로드에 대한 연결 풀을 구성합니다.

```
pool, err := dsql.NewPool(ctx, dsql.Config{
    Host:              "your-cluster.dsql.us-east-1.on.aws",
    MaxConns:          20,
    MinConns:          5,
    MaxConnLifetime:   time.Hour,
    MaxConnIdleTime:   30 * time.Minute,
    HealthCheckPeriod: time.Minute,
})
```

### 단일 연결 사용
<a name="SECTION_program-with-go-pgx-connector-single-connection"></a>

간단한 스크립트의 경우 또는 연결 풀링이 필요하지 않은 경우:

```
conn, err := dsql.Connect(ctx, dsql.Config{
    Host: "your-cluster.dsql.us-east-1.on.aws",
})
if err != nil {
    log.Fatal(err)
}
defer conn.Close(ctx)

// Use the connection
rows, err := conn.Query(ctx, "SELECT * FROM users")
```

### AWS 프로파일 사용
<a name="SECTION_program-with-go-pgx-connector-aws-profiles"></a>

자격 증명에 대한 AWS 프로파일 지정:

```
pool, err := dsql.NewPool(ctx, dsql.Config{
    Host:    "your-cluster.dsql.us-east-1.on.aws",
    Profile: "production",
})
```

## OCC 재시도
<a name="SECTION_program-with-go-pgx-connector-occ-retry"></a>

Aurora DSQL은 낙관적 동시성 제어(OCC)를 사용합니다. 두 개의 트랜잭션이 동일한 데이터를 수정할 경우, 먼저 커밋된 트랜잭션이 우선권을 가지며 두 번째 트랜잭션은 OCC 오류를 수신합니다.

`occretry` 패키지는 지수 백오프 및 지터를 사용한 자동 재시도 도우미를 제공합니다. 다음을 사용하여 설치합니다.

```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/occretry
```

트랜잭션 쓰기에는 `WithRetry`를 사용합니다.

```
err := occretry.WithRetry(ctx, pool, occretry.DefaultConfig(), func(tx pgx.Tx) error {
    _, err := tx.Exec(ctx, "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, fromID)
    if err != nil {
        return err
    }
    _, err = tx.Exec(ctx, "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, toID)
    return err
})
```

DDL 또는 단일 문에는 `ExecWithRetry`를 사용합니다.

```
err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(),
    "CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)")
```

**중요**  
`WithRetry`는 `BEGIN`/`COMMIT`/`ROLLBACK`을 내부적으로 관리합니다. 콜백은 트랜잭션을 수신하며, 데이터베이스 작업만 포함하고 재시도해도 안전해야 합니다.

## 예제
<a name="SECTION_program-with-go-pgx-connector-examples"></a>

보다 포괄적인 예제 및 사용 사례는 [Go용 Aurora DSQL 커넥터 예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example)를 참조하세요.


| 예제 | 설명 | 
| --- | --- | 
|  [example\$1preferred](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go)  | 권장: 동시 쿼리가 있는 연결 풀 | 
|  [transaction](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction)  | BEGIN/COMMIT/ROLLBACK을 사용한 트랜잭션 처리 | 
|  [occ\$1retry](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry)  | 지수 백오프와 OCC 충돌 처리 | 
|  [connection\$1string](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string)  | 구성에 연결 문자열 사용 | 

# Node.js용 Aurora DSQL 커넥터
<a name="SECTION_Node-js-connectors"></a>

node-postgres용 Aurora DSQL 커넥터와 Postgres.js용 Aurora DSQL 커넥터는 애플리케이션이 IAM 자격 증명을 사용하여 Aurora DSQL로 인증할 수 있도록 node-postgres 및 Postgres.js 클라이언트의 기능을 확장하는 인증 플러그인입니다.

# node-postgres용 Aurora DSQL 커넥터
<a name="SECTION_program-with-dsql-connector-for-node-postgres"></a>

 [node-postgres용 Aurora DSQL 커넥터](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres)는 JavaScript/TypeScript 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합하는 [node-postgres](https://node-postgres.com/)를 기반으로 구축된 Node.js 커넥터입니다.

 Aurora DSQL 커넥터는 node-postgres의 클라이언트 및 풀 기능을 확장하는 인증 플러그인으로 설계되어 애플리케이션이 IAM 자격 증명을 사용하여 Amazon Aurora DSQL과 인증할 수 있도록 합니다.

## 커넥터 정보
<a name="about-the-connector"></a>

 Amazon Aurora DSQL은 PostgreSQL과 호환되는 클라우드 네이티브 분산 데이터베이스입니다. IAM 인증 및 시간 제한 토큰이 필요하지만 기존 Node.js 데이터베이스 드라이버에는 이러한 기본 지원이 없습니다.

 node-postgres용 Aurora DSQL 커넥터는 node-postgres와 원활하게 작동하는 인증 미들웨어를 구현하여 이 격차를 해소합니다. 이 접근 방식을 통해 개발자는 자동화된 토큰 관리를 통해 Aurora DSQL 클러스터에 대한 안전한 IAM 기반 액세스를 확보하면서 기존 노드 포스트 코드를 유지할 수 있습니다.

### Aurora DSQL 인증이란 무엇입니까?
<a name="what-is-aurora-dsql-authentication"></a>

 Aurora DSQL에서 인증에는 다음이 포함됩니다.
+  **IAM 인증**: 모든 연결은 시간 제한 토큰이 있는 IAM 기반 인증을 사용합니다.
+  **토큰 생성:** 인증 토큰은 AWS 자격 증명을 사용하여 생성되며 구성 가능한 수명이 있습니다.

 node-postgres용 Aurora DSQL JDBC 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성하도록 설계되었습니다.

### 특성
<a name="features"></a>
+  **자동 IAM 인증** - DSQL 토큰 생성 및 새로 고침 처리 
+  **node-postgres 기반** - Node.js에 널리 사용되는 PostgreSQL 클라이언트를 활용합니다.
+  **원활한 통합**: 기존 node-postgres 연결 패턴과 호환 
+  **리전 자동 검색** - DSQL 클러스터 호스트 이름에서 AWS 리전 추출 
+  **전체 TypeScript 지원** - 전체 유형 안전 제공 
+  **AWS 자격 증명 지원** - 다양한 AWS 자격 증명 공급자(기본값, 프로필 기반, 사용자 지정) 지원 
+  **연결 풀링 호환성** - 기본 제공 연결 풀링과 원활하게 작동 

## 애플리케이션 예제
<a name="example-application"></a>

 [예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example)에는 node-postgres용 Aurora DSQL 커넥터를 사용하는 방법을 보여주는 샘플 애플리케이션이 포함되어 있습니다. 포함된 예제를 실행하려면 예제 [README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)를 참조하세요.

## 빠른 시작 설명서
<a name="quick-start-guide"></a>

### 요구 사항
<a name="requirements"></a>
+  Node.js 20\$1 
+  [Aurora DSQL 클러스터에 대한 액세스](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  애플리케이션이 Aurora DSQL에 연결할 수 있도록 적절한 IAM 권한 설정 
+  AWS CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성 

## 설치
<a name="installation"></a>

```
npm install @aws/aurora-dsql-node-postgres-connector
```

## 피어 종속성
<a name="peer-dependencies"></a>

```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```

## 사용법
<a name="usage"></a>

### 클라이언트 연결
<a name="client-connection"></a>

```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";

const client = new AuroraDSQLClient({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```

### 풀 연결
<a name="pool-connection"></a>

```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";

const pool = new AuroraDSQLPool({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
  max: 3,
  idleTimeoutMillis: 60000,
});

const result = await pool.query("SELECT NOW()");
```

### 고급 사용
<a name="advanced-usage"></a>

```
import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";

const client = new AuroraDSQLClient({
  host: "example.dsql.us-east-1.on.aws",
  user: "admin",
  customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
});

await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```

## 구성 옵션
<a name="configuration-options"></a>


|  옵션  |  Type  |  필수  |  설명  | 
| --- | --- | --- | --- | 
|  host  |  string  |  예  |  DSQL 클러스터 호스트 이름  | 
|  username  |  string  |  예  |  DSQL 사용자 이름  | 
|  database  |  string  |  아니요  |  데이터베이스 이름  | 
|  region  |  string  |  아니요  |  AWS 리전(제공되지 않은 경우 호스트 이름에서 자동 감지됨)  | 
|  port  |  number  |  아니요  |  기본값: 5432  | 
|  customCredentialsProvider  |  AwsCredentialIdentity / AwsCredentialIdentityProvider  |  아니요  |  사용자 지정 AWS 자격 증명 공급자  | 
|  profile  |  string  |  아니요  |  IAM 프로파일 이름입니다. 기본값은 "default"입니다. | 
|  tokenDurationSecs  |  number  |  아니요  |  초 단위의 토큰 만료 시간  | 

 [클라이언트](https://node-postgres.com/apis/client)/[풀](https://node-postgres.com/apis/pool)의 다른 모든 파라미터가 지원됩니다.

## Authentication
<a name="authentication"></a>

 커넥터는 DSQL 클라이언트 토큰 생성기를 사용하여 토큰을 생성하여 DSQL 인증을 자동으로 처리합니다. AWS 리전이 제공되지 않으면 제공된 호스트 이름에서 자동으로 구문 분석됩니다.

 Aurora DSQL의 인증에 대한 자세한 내용은 [사용 설명서](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)를 참조하세요.

### 관리자 및 일반 사용자
<a name="admin-vs-regular-users"></a>
+  "admin"이라는 사용자는 관리자 인증 토큰을 자동으로 사용 
+  다른 모든 사용자는 일반 인증 토큰을 사용합니다.
+  토큰은 각 연결에 대해 동적으로 생성됩니다.

# Postgres.js용 Aurora DSQL 커넥터
<a name="SECTION_program-with-dsql-connector-for-postgresjs"></a>

 [Postgres.js용 Aurora DSQL 커넥터](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js)는 JavaScript 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합하는 [Postgres.js](https://github.com/porsager/postgres)를 기반으로 구축된 Node.js 커넥터입니다.

 Postgres.js용 Aurora DSQL 커넥터는 Postgres.js 클라이언트 및 풀 기능을 확장하는 인증 플러그인으로 설계되어 애플리케이션이 IAM 자격 증명을 사용하여 Amazon Aurora DSQL과 인증할 수 있도록 합니다. 커넥터는 데이터베이스에 직접 연결되지 않지만 기본 Postgres.js 드라이버를 기반으로 원활한 IAM 인증을 제공합니다.

## 커넥터 정보
<a name="about-the-connector"></a>

 Amazon Aurora DSQL은 PostgreSQL 호환 애플리케이션에 고가용성과 확장성을 제공하는 분산된 SQL 데이터베이스 서비스입니다. Aurora DSQL에는 기존 Node.js 드라이버가 기본적으로 지원하지 않는 시간 제한 토큰을 사용한 IAM 기반 인증이 필요합니다.

 Postgres.js용 Aurora DSQL 커넥터의 기본 개념은 Postgres.js 클라이언트 위에 IAM 토큰 생성을 처리하는 인증 계층을 추가하여, 사용자가 기존 Postgres.js 워크플로를 변경하지 않고도 Aurora DSQL에 연결할 수 있도록 하는 것입니다.

 Postgres.js용 Aurora DSQL 커넥터는 대부분의 Postgres.js 버전에서 작동합니다. 사용자는 Postgres.js를 직접 설치하여 자체 버전을 제공합니다.

### Aurora DSQL 인증이란 무엇입니까?
<a name="what-is-aurora-dsql-authentication"></a>

 Aurora DSQL에서 인증에는 다음이 포함됩니다.
+  **IAM 인증**: 모든 연결은 시간 제한 토큰이 있는 IAM 기반 인증을 사용합니다.
+  **토큰 생성:** 인증 토큰은 AWS 자격 증명을 사용하여 생성되며 구성 가능한 수명이 있습니다.

 Postgres.js용 Aurora DSQL 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성하도록 설계되었습니다.

### 특성
<a name="features"></a>
+  **자동 IAM 인증** - DSQL 토큰 생성 및 새로 고침 처리 
+  **Postgres.js 기반** - Node.js용 빠른 PostgreSQL 클라이언트 활용 
+  **원활한 통합** - 기존 Postgres.js 연결 패턴과 호환 
+  **리전 자동 검색** - DSQL 클러스터 호스트 이름에서 AWS 리전 추출 
+  **전체 TypeScript 지원** - 전체 유형 안전 제공 
+  **AWS 자격 증명 지원** - 다양한 AWS 자격 증명 공급자(기본값, 프로필 기반, 사용자 지정) 지원 
+  **연결 풀링 호환성** - Postgres.js의 기본 제공 연결 풀링과 원활하게 작동 

## 빠른 시작 설명서
<a name="quick-start-guide"></a>

### 요구 사항
<a name="requirements"></a>
+  Node.js 20\$1 
+  [Aurora DSQL 클러스터에 대한 액세스](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  애플리케이션이 Aurora DSQL에 연결할 수 있도록 적절한 IAM 권한 설정 
+  AWS CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성 

### 설치
<a name="installation"></a>

```
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```

### 기본 사용법
<a name="basic-usage"></a>

```
import { auroraDSQLPostgres } from '@aws/aurora-dsql-postgresjs-connector';

const sql = auroraDSQLPostgres({
  host: 'your-cluster.dsql.us-east-1.on.aws',
  username: 'admin',
    
});

// Execute queries
const result = await sql`SELECT current_timestamp`;
console.log(result);

// Clean up
await sql.end();
```

#### 호스트 대신 클러스터 ID 사용
<a name="using-cluster-id-instead-of-host"></a>

```
const sql = auroraDSQLPostgres({
  host: 'your-cluster-id',
  region: 'us-east-1',
  username: 'admin',
    
});
```

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

```
const sql = AuroraDSQLPostgres(
  'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);

const result = await sql`SELECT current_timestamp`;
```

### 고급 구성
<a name="advanced-configuration"></a>

```
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';

const sql = AuroraDSQLPostgres({
  host: 'your-cluster.dsql.us-east-1.on.aws',
  database: 'postgres',
  username: 'admin',
  customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
  tokenDurationSecs: 3600,                            // Token expiration (seconds)
  
  // Standard Postgres.js options
  max: 20,                              // Connection pool size
  ssl: { rejectUnauthorized: false }    // SSL configuration
});
```

## 구성 옵션
<a name="configuration-options"></a>


|  옵션  |  Type  |  필수  |  설명  | 
| --- | --- | --- | --- | 
|  host  |  string  |  예  |  DSQL 클러스터 호스트 이름 또는 클러스터 ID  | 
|  database  |  string?  |  아니요  |  데이터베이스 이름  | 
|  username  |  string?  |  아니요  |  데이터베이스 사용자 이름(제공되지 않은 경우 관리자 사용)  | 
|  region  |  string?  |  아니요  |  AWS 리전(제공되지 않은 경우 호스트 이름에서 자동 감지됨)  | 
|  customCredentialsProvider  |  AwsCredentialIdentityProvider?  |  아니요  |  사용자 지정 AWS 자격 증명 공급자  | 
|  tokenDurationSecs  |  number?  |  아니요  |  초 단위의 토큰 만료 시간  | 

 모든 표준 [Postgres.js 옵션](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details)도 지원됩니다.

## Authentication
<a name="authentication"></a>

 커넥터는 DSQL 클라이언트 토큰 생성기를 사용하여 토큰을 생성하여 DSQL 인증을 자동으로 처리합니다. AWS 리전이 제공되지 않으면 제공된 호스트 이름에서 자동으로 구문 분석됩니다.

 Aurora DSQL의 인증에 대한 자세한 내용은 [사용 설명서](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)를 참조하세요.

### 관리자 및 일반 사용자
<a name="admin-vs-regular-users"></a>
+  "admin"이라는 사용자는 관리자 인증 토큰을 자동으로 사용 
+  다른 모든 사용자는 일반 인증 토큰을 사용합니다.
+  토큰은 각 연결에 대해 동적으로 생성됩니다.

## 샘플 사용
<a name="sample-usage"></a>

 Postgres.js용 Aurora DSQL 커넥터를 사용하는 JavaScript 예제는 GitHub에서 확인할 수 있습니다. 예제 실행 방법에 대한 자세한 내용은 [예제 디렉터리](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example)를 참조하세요.


|  설명  |  예제  | 
| --- | --- | 
|  여러 작업자의 테이블 생성, 만들기 및 읽기를 포함한 동시 쿼리를 사용한 연결 풀링  |  [연결 풀 예제(선호됨)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js)  | 
|  연결 풀링이 없는 CRUD 작업(테이블 만들기, 삽입, 선택, 삭제)  |  [연결 풀이 없는 예제](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js)  | 

# Ruby 커넥터를 사용하여 Aurora DSQL 클러스터에 연결
<a name="SECTION_program-with-dsql-connector-for-ruby-pg"></a>

[Ruby용 Aurora DSQL 커넥터](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg)는 Ruby 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합하는 [pg](https://github.com/ged/ruby-pg)를 기반으로 구축된 .NET 커넥터입니다.

이 커넥터는 토큰 생성, SSL 구성 및 연결 풀링을 처리하므로 애플리케이션 로직에 집중할 수 있습니다.

## 커넥터 정보
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

Amazon Aurora DSQL에는 기존 Ruby PostgreSQL 드라이버가 기본적으로 지원하지 않는 시간 제한 토큰을 사용한 IAM 인증이 필요합니다. Ruby용 Aurora DSQL 커넥터는 IAM 토큰 생성을 처리하는 pg gem 위에 인증 계층을 추가하여 기존 pg 워크플로를 변경하지 않고도 Aurora DSQL에 연결할 수 있도록 합니다.

### Aurora DSQL 인증이란 무엇인가요?
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-authentication"></a>

Aurora DSQL에서 **인증**에는 다음이 포함됩니다.
+ **IAM 인증**: 모든 연결은 시간 제한 토큰이 있는 IAM 기반 인증을 사용합니다.
+ **토큰 생성**: 커넥터는 AWS 자격 증명을 사용하여 인증 토큰을 생성하며 이러한 토큰에는 구성 가능한 수명이 있습니다.

Ruby용 Aurora DSQL 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성합니다.

### 특성
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-features"></a>
+ **자동 IAM 인증** - Aurora DSQL 토큰 생성 및 새로 고침 처리
+ **pg 기반** - 널리 사용되는 Ruby용 PostgreSQL gem 래핑
+ **원활한 통합** - 기존 pg gem 워크플로와 함께 작동
+ **연결 풀링** - 최대 수명 적용으로 `connection_pool` gem을 통한 지원 기본 제공
+ **리전 자동 감지** - DSQL 클러스터 호스트 이름에서 AWS 리전 추출
+ **AWS 자격 증명 지원**: AWS 프로파일 및 사용자 지정 자격 증명 공급자 지원
+ **OCC 재시도** - 지수 백오프를 사용하여 옵트인 낙관적 동시성 제어 재시도

## 애플리케이션 예시
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-example-application"></a>

전체 예제는 GitHub의 [예제 애플리케이션](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example)을 참조하세요.

## 빠른 시작 설명서
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-quick-start"></a>

### 요구 사항
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-requirements"></a>
+ Ruby 3.1 이상
+ [Aurora DSQL 클러스터에 대한 액세스](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성

## 설치
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-installation"></a>

Gemfile에 추가합니다.

```
gem "aurora-dsql-ruby-pg"
```

또는 직접 설치합니다.

```
gem install aurora-dsql-ruby-pg
```

## 사용법
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-usage"></a>

### 풀 연결
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-pool-connection"></a>

```
require "aurora_dsql_pg"

# Create a connection pool with OCC retry enabled
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  occ_max_retries: 3
)

# Read
pool.with do |conn|
  result = conn.exec("SELECT 'Hello, DSQL!'")
  puts result[0]["?column?"]
end

# Write — you must wrap writes in a transaction
pool.with do |conn|
  conn.transaction do
    conn.exec_params("INSERT INTO users (id, name) VALUES (gen_random_uuid(), $1)", ["Alice"])
  end
end

pool.shutdown
```

### 단일 연결
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-single-connection"></a>

간단한 스크립트의 경우 또는 연결 풀링이 필요하지 않은 경우:

```
conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close
```

### 고급 사용
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-advanced"></a>

**호스트 구성**

커넥터는 전체 클러스터 엔드포인트(리전 자동 감지)와 클러스터 ID(리전 필수)를 모두 지원합니다.

```
# Full endpoint (region auto-detected)
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws"
)

# Cluster ID (region required)
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster-id",
  region: "us-east-1"
)
```

**AWS 프로필**

자격 증명에 대한 AWS 프로파일 지정:

```
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  profile: "production"
)
```

**연결 문자열 형식**

커넥터는 다음의 PostgreSQL 연결 문자열 형식을 지원합니다.

```
postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]
```

지원되는 쿼리 파라미터: `region`, `profile`, `tokenDurationSecs`.

```
# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
  "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)
```

**OCC 재시도**

Aurora DSQL은 낙관적 동시성 제어(OCC)를 사용합니다. 두 개의 트랜잭션이 동일한 데이터를 수정할 경우, 먼저 커밋된 트랜잭션이 우선권을 가지며 두 번째 트랜잭션은 OCC 오류를 수신합니다.

OCC 재시도가 옵트인되었습니다. `pool.with`에서 지수 백오프 및 지터를 사용하여 자동 재시도를 활성화하려면 풀을 생성할 때 `occ_max_retries`를 설정합니다.

```
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  occ_max_retries: 3
)

pool.with do |conn|
  conn.transaction do
    conn.exec_params("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, from_id])
    conn.exec_params("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, to_id])
  end
end
```

**주의**  
`pool.with`는 블록을 트랜잭션에 자동으로 래핑하지 않습니다. 쓰기 작업을 위해 `conn.transaction`을 직접적으로 호출해야 합니다. OCC 충돌 시 커넥터는 전체 블록을 다시 실행하므로 데이터베이스 작업만 포함하고 재시도해도 안전해야 합니다.

개별 직접 호출에 대한 재시도를 건너뛰려면 `retry_occ: false`를 전달합니다.

```
pool.with(retry_occ: false) do |conn|
  conn.exec("SELECT 1")
end
```

## 구성 옵션
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-configuration"></a>


| Field | Type | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| host | 문자열 | (필수) | 클러스터 엔드포인트 또는 클러스터 ID | 
| region | 문자열 | (자동 탐지됨) | AWS 리전, 호스트가 클러스터 ID인 경우 필수 | 
| user | 문자열 | "admin" | 데이터베이스 사용자 | 
| 데이터베이스 | 문자열 | "postgres" | 데이터베이스 이름 | 
| 포트 | Integer | 5432 | 데이터베이스 포트 | 
| profile | 문자열 | nil | 자격 증명의 AWS 프로파일 이름 | 
| token\$1duration | Integer | 900(15분) | 초 단위의 토큰 유효 기간(최대 허용: 1주, 기본값: 15분) | 
| credentials\$1provider | Aws::Credentials | nil | 사용자 지정 자격 증명 공급자 | 
| max\$1lifetime | Integer | 3300(55분) | 최대 연결 수명(초 단위) | 
| application\$1name | 문자열 | nil | application\$1name의 ORM 접두사 | 
| 로거 | Logger | nil | OCC 재시도 경고에 대한 로거 | 
| occ\$1max\$1retries | Integer | nil(비활성화됨) | pool.with에서 최대 OCC 재시도 횟수, 설정 시 재시도 활성화 | 

`create_pool`은 `ConnectionPool.new`에 직접 전달하는 옵션 해시가 있는 `pool:` 키워드도 허용합니다. `pool:`을 생략하는 경우 커넥터의 기본값은 `{size: 5, timeout: 5}`입니다. 제공하는 키는 특정 기본값만 재정의합니다.

```
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  pool: { size: 10, timeout: 10 }
)
```

## Authentication
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-auth"></a>

커넥터는 AWS 자격 증명을 사용해 토큰을 생성하여 Aurora DSQL 인증을 자동으로 처리합니다. AWS 리전을 제공하지 않으면 커넥터가 호스트 이름에서 리전을 구문 분석합니다.

Aurora DSQL의 인증에 대한 자세한 내용은 [Aurora DSQL에 대한 인증 및 권한 부여](authentication-authorization.md) 섹션을 참조하세요.

### 관리자와 일반 사용자
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-admin-vs-regular"></a>
+ "admin"이라는 사용자는 관리자 인증 토큰을 자동으로 사용
+ 다른 모든 사용자는 일반 인증 토큰을 사용합니다.
+ 커넥터는 각 연결에 대해 동적으로 토큰을 생성합니다.

# .NET 커넥터를 사용하여 Aurora DSQL 클러스터에 연결
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql"></a>

[.NET용 Amazon Aurora DSQL 커넥터](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql)는 .NET 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합하는 [Npgsql](https://www.npgsql.org/)을 기반으로 구축된 .NET 커넥터입니다.

이 커넥터는 토큰 생성, SSL 구성 및 연결 풀링을 처리하므로 애플리케이션 로직에 집중할 수 있습니다.

## 커넥터 정보
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-about"></a>

Amazon Aurora DSQL에는 기존 .NET PostgreSQL 드라이버가 기본적으로 지원하지 않는 시간 제한 토큰을 사용한 IAM 인증이 필요합니다. .NET용 Aurora DSQL 커넥터는 IAM 토큰 생성을 처리하는 Npgsql 위에 인증 계층을 추가하여 기존 Npgsql 워크플로를 변경하지 않고도 Aurora DSQL에 연결할 수 있도록 합니다.

### Aurora DSQL 인증이란 무엇인가요?
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

Aurora DSQL에서 **인증**에는 다음이 포함됩니다.
+ **IAM 인증**: 모든 연결은 시간 제한 토큰이 있는 IAM 기반 인증을 사용합니다.
+ **토큰 생성**: 커넥터는 AWS 자격 증명을 사용하여 인증 토큰을 생성하며 이러한 토큰에는 구성 가능한 수명이 있습니다.

.NET용 Aurora DSQL 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성합니다.

### 특성
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-features"></a>
+ **자동 IAM 인증** - Aurora DSQL 토큰 생성 및 새로 고침 처리
+ **Npgsql 기반** - .NET용 주요 PostgreSQL 드라이버 래핑
+ **원활한 통합** - 기존 Npgsql 워크플로와 함께 작동
+ **연결 풀링** - 최대 수명 적용으로 `NpgsqlDataSource`를 통한 지원 기본 제공
+ **리전 자동 감지** - DSQL 클러스터 호스트 이름에서 AWS 리전 추출
+ **AWS 자격 증명 지원**: AWS 프로파일 및 사용자 지정 자격 증명 공급자 지원
+ **OCC 재시도** - 지수 백오프를 사용하여 옵트인 낙관적 동시성 제어 재시도
+ **SSL 적용** - 항상 `verify-full` 모드 및 직접 TLS 협상과 함께 SSL 사용

## 애플리케이션 예시
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-example-application"></a>

전체 예제는 GitHub의 [예제 애플리케이션](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example)을 참조하세요.

## 빠른 시작 설명서
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-quick-start"></a>

### 요구 사항
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-requirements"></a>
+ .NET 8.0 이상
+ [Aurora DSQL 클러스터에 대한 액세스](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성

## 설치
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-installation"></a>

패키지를 프로젝트에 추가합니다.

```
dotnet add package Amazon.AuroraDsql.Npgsql
```

## 사용법
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-usage"></a>

### 풀 연결
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-pool-connection"></a>

```
using Amazon.AuroraDsql.Npgsql;

// Create a connection pool
await using var ds = await AuroraDsql.CreateDataSourceAsync(new DsqlConfig
{
    Host = "your-cluster.dsql.us-east-1.on.aws",
    OccMaxRetries = 3
});

// Read
await using (var conn = await ds.OpenConnectionAsync())
{
    await using var cmd = conn.CreateCommand();
    cmd.CommandText = "SELECT 'Hello, DSQL!'";
    var greeting = await cmd.ExecuteScalarAsync();
    Console.WriteLine(greeting);
}

// Transactional write with OCC retry
await ds.WithTransactionRetryAsync(async conn =>
{
    await using var cmd = conn.CreateCommand();
    cmd.CommandText = "INSERT INTO users (id, name) VALUES (gen_random_uuid(), @name)";
    cmd.Parameters.AddWithValue("name", "Alice");
    await cmd.ExecuteNonQueryAsync();
});
```

### 단일 연결
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-single-connection"></a>

간단한 스크립트의 경우 또는 연결 풀링이 필요하지 않은 경우:

```
await using var conn = await AuroraDsql.ConnectAsync(new DsqlConfig
{
    Host = "your-cluster.dsql.us-east-1.on.aws"
});

await using var cmd = conn.CreateCommand("SELECT 1");
await cmd.ExecuteScalarAsync();
```

### OCC 재시도
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-occ-retry"></a>

Aurora DSQL은 낙관적 동시성 제어(OCC)를 사용합니다. 두 개의 트랜잭션이 동일한 데이터를 수정할 경우, 먼저 커밋된 트랜잭션이 우선권을 가지며 두 번째 트랜잭션은 OCC 오류를 수신합니다.

OCC 재시도가 옵트인되었습니다. 지수 백오프 및 지터를 사용하여 자동 재시도를 활성화하려면 구성에서 `OccMaxRetries`를 설정합니다. 트랜잭션 쓰기에는 `WithTransactionRetryAsync`를 사용합니다.

```
await ds.WithTransactionRetryAsync(async conn =>
{
    await using var cmd = conn.CreateCommand();

    cmd.CommandText = "UPDATE accounts SET balance = balance - 100 WHERE id = @from";
    cmd.Parameters.AddWithValue("from", fromId);
    await cmd.ExecuteNonQueryAsync();

    cmd.CommandText = "UPDATE accounts SET balance = balance + 100 WHERE id = @to";
    cmd.Parameters.Clear();
    cmd.Parameters.AddWithValue("to", toId);
    await cmd.ExecuteNonQueryAsync();
});
```

DDL 또는 단일 문에는 `ExecWithRetryAsync`를 사용합니다.

```
await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");
```

**중요**  
`WithTransactionRetryAsync`는 `BEGIN`/`COMMIT`/`ROLLBACK`을 내부적으로 관리하고 각 시도에 대해 새 연결을 엽니다. 콜백은 데이터베이스 작업만 포함하고 재시도해도 안전해야 합니다.

## 구성 옵션
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-configuration"></a>

커넥터는 `region` 및 `profile` 쿼리 파라미터가 있는 `postgres://` 및 `postgresql://` 연결 문자열도 허용합니다.


| Field | Type | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| Host | string | (필수) | 클러스터 엔드포인트 또는 26자 클러스터 ID | 
| Region | string? | (자동 탐지됨) | AWS 리전, Host가 클러스터 ID인 경우 필수 | 
| User | string | "admin" | 데이터베이스 사용자 | 
| Database | string | "postgres" | 데이터베이스 이름 | 
| Port | int | 5432 | 데이터베이스 포트 | 
| Profile | string? | null | 자격 증명의 AWS 프로파일 이름 | 
| CustomCredentialsProvider | AWSCredentials? | null | 사용자 지정 AWS 자격 증명 공급자 | 
| TokenDurationSecs | int? | null(SDK 기본값, 900초) | 토큰 유효 기간(초 단위) | 
| OccMaxRetries | int? | null(비활성) | 데이터 소스의 재시도 메서드에 대한 기본 최대 OCC 재시도 횟수 | 
| OrmPrefix | string? | null | application\$1name 앞에 추가되는 ORM 접두사 | 
| LoggerFactory | ILoggerFactory? | null | 재시도 경고 및 진단을 위한 로거 팩토리 | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | 풀 설정을 재정의하거나 추가 Npgsql 연결 문자열 속성을 설정하는 콜백입니다. SSL 및 Enlist는 보안 불변수이며 재정의할 수 없습니다. | 

## Authentication
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-auth"></a>

커넥터는 AWS 자격 증명을 사용해 토큰을 생성하여 Aurora DSQL 인증을 자동으로 처리합니다. AWS 리전을 제공하지 않으면 커넥터가 호스트 이름에서 리전을 구문 분석합니다.

Aurora DSQL의 인증에 대한 자세한 내용은 [Aurora DSQL에 대한 인증 및 권한 부여](authentication-authorization.md) 섹션을 참조하세요.

### 관리자와 일반 사용자
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ "admin"이라는 사용자는 관리자 인증 토큰을 자동으로 사용
+ 다른 모든 사용자는 일반 인증 토큰을 사용합니다.
+ 커넥터는 각 연결에 대해 동적으로 토큰을 생성합니다.