RDS 데이터 API 사용

RDS 데이터 API(데이터 API)를 사용하면 Aurora DB 클러스터에 대한 웹 서비스 인터페이스로 작업할 수 있습니다. 데이터 API에서 DB 클러스터에 지속적으로 연결하지 않아도 됩니다. 대신에 AWS SDK와의 통합과 보안 HTTP 엔드포인트를 제공합니다. 연결을 관리하지 않고 엔드포인트를 사용하여 SQL 문을 실행할 수 있습니다.

데이터 API는 AWS Secrets Manager에 저장된 데이터베이스 보안 인증 정보를 사용하기 때문에 사용자는 데이터 API 호출과 함께 보안 인증 정보를 전달할 필요가 없습니다. Secrets Manager에 보안 인증 정보를 저장하려면 사용자에게 Secrets Manager 및 데이터 API를 사용할 수 있는 적절한 권한을 부여해야 합니다. 사용자 인증에 대한 자세한 내용은 RDS 데이터 API에 대한 액세스 권한 부여 단원을 참조하세요.

또한 데이터 API를 사용하여 Amazon Aurora를 다른 AWS 애플리케이션(예: AWS Lambda, AWS AppSync, AWS Cloud9)과 통합할 수 있습니다 데이터 API는 AWS Lambda를 사용하는 더 안전한 방법도 제공합니다. Virtual Private Cloud(VPC)의 리소스에 액세스하는 Lambda 함수를 구성할 필요 없이 DB 클러스터에 액세스할 수 있습니다. 자세한 내용은 AWS Lambda, AWS AppSync, AWS Cloud9 단원을 참조하십시오.

Aurora DB 클러스터를 생성할 때 데이터 API를 활성화할 수 있습니다. 나중에 구성을 수정할 수도 있습니다. 자세한 내용은 RDS 데이터 API 활성화 단원을 참조하십시오.

데이터 API를 활성화하면 VPC에서 Aurora에 액세스하도록 쿼리 도구를 구성하지 않고도 쿼리 편집기를 사용하여 임시 쿼리를 실행할 수 있습니다. 자세한 내용은 Aurora 쿼리 편집기 사용하기 단원을 참조하십시오.

리전 및 버전 사용 가능 여부

데이터 API에 사용할 수 있는 리전 및 엔진 버전에 대한 자세한 내용은 다음 섹션을 참조하세요.

명령줄 인터페이스 또는 API를 통해 데이터 API에 액세스할 때 FIPS 140-2에서 유효성을 검사한 암호화 모듈이 필요한 경우 FIPS 엔드포인트를 사용합니다. 사용 가능한 FIPS 엔드포인트에 대한 자세한 내용은 Federal Information Processing Standard(FIPS) 140-2를 참조하십시오.

RDS 데이터 API의 제한

RDS 데이터 API(데이터 API)에는 다음과 같은 제한 사항이 적용됩니다.

Serverless v2 및 프로비저닝과 RDS 데이터 API의 비교 및 Aurora Serverless v1

RDS 데이터 API의 최신 개선 사항을 통해 최신 버전의 PostgreSQL 또는 MySQL 엔진을 사용하는 클러스터에서도 사용할 수 있습니다. 이러한 클러스터는 db.r6g 또는 db.r6i 등의 프로비저닝된 인스턴스 클래스나 Aurora Serverless v2를 사용하도록 구성할 수 있습니다.

다음 표에는 Aurora Serverless v2 및 프로비저닝된 DB 클러스터와 Aurora Serverless v1 DB 클러스터를 사용하는 RDS 데이터 API(데이터 API) 간의 차이점이 나와 있습니다. Aurora Serverless v1 DB 클러스터는 serverless 엔진 모드를 사용합니다. 프로비저닝 DB 클러스터는 provisioned 엔진 모드를 사용합니다. 또한 Aurora Serverless v2 DB 클러스터는 provisioned 엔진 모드를 사용하며, db.serverless 인스턴스 클래스와 함께 하나 이상의 Aurora Serverless v2 DB 인스턴스를 포함합니다.

RDS 데이터 API에 대한 액세스 권한 부여

사용자는 권한이 있는 경우에만 RDS 데이터 API(데이터 API) 작업을 간접 호출할 수 있습니다. 권한을 정의하는 AWS Identity and Access Management(IAM) 정책을 연결하여 데이터 API를 사용할 수 있는 권한을 사용자에게 부여할 수 있습니다. IAM 역할을 사용하는 경우 정책을 역할에 연결할 수도 있습니다. AWS 관리형 정책인 AmazonRDSDataFullAccess에는 데이터 API에 대한 권한이 포함되어 있습니다.

AmazonRDSDataFullAccess 정책에는 사용자가 AWS Secrets Manager에서 보안 암호 값을 가져올 수 있는 권한도 포함되어 있습니다. 사용자는 데이터 API 호출에 사용할 수 있는 보안 암호를 저장하는 데 Secrets Manager를 사용해야 합니다. 보안 암호를 사용하면 사용자가 데이터 API 호출의 대상이 되는 리소스에 대한 데이터베이스 보안 인증 정보를 포함할 필요가 없습니다. 데이터 API는 투명하게 Secrets Manager를 호출하여 사용자의 보안 암호에 대한 요청을 허용(또는 거부)합니다. 데이터 API와 함께 사용할 보안 암호 설정에 대한 자세한 내용은 AWS Secrets Manager에 데이터베이스 자격 증명 저장 섹션을 참조하세요.

AmazonRDSDataFullAccess 정책은 데이터 API를 통해 리소스에 대한 완전한 액세스를 제공합니다. 리소스의 Amazon 리소스 이름(ARN)을 지정하는 사용자 고유의 정책을 정의하여 범위를 좁힐 수 있습니다.

예를 들어, 다음 정책은 사용자가 ARN으로 식별되는 DB 클러스터의 데이터 API에 액세스하는 데 필요한 최소 권한을 보여줍니다. 정책에는 Secrets Manager에 액세스하고 사용자의 DB 인스턴스에 대한 권한 부여를 얻는 데 필요한 권한이 포함되어 있습니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SecretsManagerDbCredentialsAccess",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*"
        },
        {
            "Sid": "RDSDataServiceAccess",
            "Effect": "Allow",
            "Action": [
                "rds-data:BatchExecuteStatement",
                "rds-data:BeginTransaction",
                "rds-data:CommitTransaction",
                "rds-data:ExecuteStatement",
                "rds-data:RollbackTransaction"
            ],
            "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod"
        }
    ]
}

예제와 같이 정책 문에서 와일드카드(*) 대신 “Resources” 요소에 대한 특정 ARN을 사용하는 것이 좋습니다.

태그 기반 권한 부여 작업

RDS 데이터 API(데이터 API) 및 Secrets Manager 모두 태그 기반 권한 부여를 지원합니다. 태그는 RDS 클러스터와 같은 리소스에 추가 문자열 값을 사용하여 레이블을 지정하는 키-값 쌍입니다. 예를 들면 다음과 같습니다.

비용 할당, 운영 지원, 액세스 제어 및 기타 여러 이유로 리소스에 태그를 적용할 수 있습니다. 리소스에 아직 태그가 없는 상태에서 태그를 적용하려는 경우 Amazon RDS 리소스 태그 지정에서 자세한 내용을 확인할 수 있습니다. 정책 문의 태그를 사용하여 이러한 태그로 레이블이 지정된 RDS 클러스터에 대한 액세스를 제한할 수 있습니다. 예를 들어 Aurora DB 클러스터에는 환경을 프로덕션 또는 개발로 식별하는 태그가 있을 수 있습니다.

다음 예제에서는 정책 문에서 태그를 사용하는 방법을 보여줍니다. 이 문을 사용하려면 클러스터와 데이터 API 요청에 전달된 보안 암호에 environment:production 태그가 있어야 합니다.

정책이 적용되는 방법은 다음과 같습니다. 사용자가 데이터 API를 사용하여 호출하면 요청이 서비스로 전송됩니다. 데이터 API는 먼저 요청에서 전달된 클러스터 ARN에 environment:production으로 태그가 지정되어 있는지 확인합니다. 그런 다음 Secrets Manager를 호출하여 요청에서 사용자의 비밀 값을 검색합니다. Secrets Manager는 또한 environment:production이 사용자의 비밀에 태깅되었는지 확인됩니다. 그렇다면 데이터 API는 사용자의 DB 암호에 대해 검색된 값을 사용합니다. 마지막으로, 올바른 경우 사용자에 대해 데이터 API 요청이 성공적으로 호출됩니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SecretsManagerDbCredentialsAccess",
            "Effect": "Allow",
            "Action": [
                 "secretsmanager:GetSecretValue"
               ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*",
            "Condition": {
                    "StringEquals": {
                        "aws:ResourceTag/environment": [
                                         "production"
                                        ]
                     }
             }
        },
        {
            "Sid": "RDSDataServiceAccess",
            "Effect": "Allow",
            "Action": [
                  "rds-data:*"
               ],
            "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*",
            "Condition": {
                    "StringEquals": {
                        "aws:ResourceTag/environment": [
                                         "production"
                                        ]
                     }
             }
         }
     ]
}

이 예제에서는 데이터 API 및 Secrets Manager의 rds-data 및 secretsmanager에 대한 별도의 작업을 보여줍니다. 그러나 여러 가지 방법으로 작업을 결합하고 태그 조건을 정의하여 특정 사용 사례를 지원할 수 있습니다. 자세한 내용은 Secrets Manager에 대한 자격 증명 기반 정책(IAM 정책) 사용을 참조하십시오.

정책의 “Condition” 요소에 대해 다음 중에서 태그 키를 선택할 수 있습니다.

리소스 태그 및 aws:TagKeys 사용 방법에 대한 자세한 내용은 리소스 태그를 사용하여 AWS 리소스에 대한 액세스 제어를 참조하십시오.

AWS Secrets Manager에 데이터베이스 자격 증명 저장

RDS 데이터 API(데이터 API)를 호출할 때 Secrets Manager에서 보안 암호를 사용하여 Aurora DB 클러스터에 대한 보안 인증 정보를 전달합니다. 이 방식으로 자격 증명을 전달하려면 보안 암호의 이름 또는 보안 암호의 Amazon 리소스 이름(ARN)을 지정합니다.

Secrets Manager 사용에 대한 자세한 내용은 AWS Secrets Manager 사용 설명서를 참조하세요.

Amazon Aurora이 자격 증명 및 액세스를 관리하는 방법을 이해하려면 IAM에서 Amazon Aurora을 사용하는 방식을 참조하십시오.

IAM 정책 생성에 대한 자세한 내용은 IAM 사용 설명서의 IAM 정책 생성을 참조하십시오. 사용자에게 IAM 정책 추가에 대한 자세한 내용은 IAM 사용 설명서의 IAM 자격 증명 권한 추가 및 제거를 참조하십시오.

RDS 데이터 API 활성화

RDS 데이터 API(데이터 API)를 사용하려면 Aurora DB 클러스터에 대해 RDS 데이터 API(데이터 API)를 활성화합니다. DB 클러스터를 생성하거나 수정할 때 데이터 API를 활성화할 수 있습니다.

데이터베이스를 생성할 때 RDS 데이터 API 활성화

RDS 데이터 API(데이터 API)를 지원하는 데이터베이스를 생성하는 동안 이 기능을 활성화할 수 있습니다. 다음 절차에서는 AWS Management Console, AWS CLI 또는 RDS API를 사용할 때 해당 작업을 수행하는 방법을 설명합니다.

기존 데이터베이스에서 RDS 데이터 API 활성화

RDS 데이터 API(데이터 API)를 지원하는 DB 클러스터를 수정하여 이 기능을 활성화하거나 비활성화할 수 있습니다.

데이터 API 활성화 또는 비활성화(Aurora Serverless v2 및 프로비저닝)

다음 절차를 사용하여 Aurora Serverless v2 및 프로비저닝된 데이터베이스에서 데이터 API를 활성화 또는 비활성화합니다. Aurora Serverless v1 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)의 절차를 사용하세요.

데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)

다음 절차를 사용하여 기존 Aurora Serverless v1 데이터베이스에서 데이터 API를 활성화 또는 비활성화합니다. Aurora Serverless v2 및 프로비저닝된 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 데이터 API 활성화 또는 비활성화(Aurora Serverless v2 및 프로비저닝)의 절차를 사용하세요.

RDS 데이터 API(AWS PrivateLink)에 대한 Amazon VPC 엔드포인트 생성

Amazon VPC를 사용하면 Aurora DB 클러스터 및 애플리케이션과 같은 AWS 리소스를 Virtual Private Cloud(VPC)에서 시작할 수 있습니다. AWS PrivateLink는 Amazon 네트워크에서 VPC 및 AWS 서비스 간의 프라이빗 연결을 안전하게 제공합니다. AWS PrivateLink를 사용하면 Amazon VPC 엔드포인트를 생성하여 Amazon VPC 기반의 다른 계정 및 VPC에서 서비스에 연결할 수 있습니다. AWS PrivateLink에 대한 자세한 내용은 Amazon Virtual Private Cloud 사용 설명서의 VPC 엔드포인트 서비스(AWS PrivateLink)를 참조하세요.

Amazon VPC 엔드포인트를 사용하여 RDS 데이터 API(데이터 API)를 호출할 수 있습니다. Amazon VPC 엔드포인트를 사용하면 퍼블릭 IP 주소를 사용하지 않고 Amazon VPC의 애플리케이션과 AWS 네트워크의 데이터 API 간에 트래픽을 유지합니다. Amazon VPC 엔드포인트를 사용하면 퍼블릭 인터넷 연결 제한과 관련된 규정 준수 및 규정 요구 사항을 충족할 수 있습니다. 예를 들어, Amazon VPC 엔드포인트를 사용하는 경우 Amazon EC2 인스턴스에서 실행되는 애플리케이션과 해당 애플리케이션이 포함된 VPC의 데이터 API 간 트래픽을 유지할 수 있습니다.

Amazon VPC 엔드포인트를 생성한 후에는 애플리케이션에서 코드나 구성을 변경하지 않고 엔드포인트를 사용할 수 있습니다.

엔드포인트를 생성한 후 AWS Management Console에서 링크를 선택하여 엔드포인트 세부 정보를 봅니다.

엔드포인트 세부 정보 탭에는 Amazon VPC 엔드포인트를 만드는 동안 생성된 DNS 호스트 이름이 표시됩니다.

표준 엔드포인트(rds-data.region.amazonaws.com) 또는 VPC 관련 엔드포인트 중 하나를 사용하여 Amazon VPC에서 데이터 API를 호출할 수 있습니다. 표준 데이터 API 엔드포인트는 자동으로 Amazon VPC 엔드포인트로 라우팅됩니다. 이 라우팅은 Amazon VPC 엔드포인트를 생성할 때 프라이빗 DNS 호스트 이름을 활성화했기 때문에 발생합니다.

데이터 API 호출에서 Amazon VPC 엔드포인트를 사용하는 경우 애플리케이션과 데이터 API 간의 모든 트래픽은 해당 트래픽이 포함된 Amazon VPC에 남아 있습니다. 모든 유형의 데이터 API 호출에 Amazon VPC 엔드포인트를 사용할 수 있습니다. 데이터 API 호출에 대한 자세한 내용은 RDS 데이터 API 호출 섹션을 참조하세요.

RDS 데이터 API 호출

Aurora DB 클러스터에서 RDS 데이터 API(데이터 API)를 활성화하면 데이터 API 또는 AWS CLI를 사용하여 Aurora DB 클러스터에서 SQL 문을 실행할 수 있습니다. 데이터 API는 AWS SDK에서 지원되는 프로그래밍 언어를 지원합니다. 자세한 내용은 AWS 기반 구축 도구를 참조하세요.

데이터 API 작업 참조

데이터 API는 SQL 문을 수행하는 다음 작업을 제공합니다.

두 작업 중 하나를 사용하여 개별 SQL 문을 실행하거나 트랜잭션을 실행할 수 있습니다. 트랜잭션의 경우 데이터 API는 다음과 같은 작업을 제공합니다.

SQL 문을 수행하고 트랜잭션을 지원하기 위한 작업에는 다음과 같은 일반적인 데이터 API 파라미터와 AWS CLI 옵션이 있습니다. 일부 작업은 다른 파라미터 또는 옵션을 지원합니다.

RDS 데이터 API는 Aurora MySQL에 대해 다음 데이터 유형을 지원합니다.

RDS 데이터 API는 다음 Aurora PostgreSQL 스칼라 유형을 지원합니다.

RDS 데이터 API는 다음 Aurora PostgreSQL 배열 유형을 지원합니다.

ExecuteStatement 및 BatchExecuteStatement에 대한 데이터 API 호출에서, 그리고 AWS CLI 명령 execute-statement 및 batch-execute-statement 실행 시 파라미터를 사용할 수 있습니다. 파라미터를 사용하려면 SqlParameter 데이터 형식에 이름-값 페어를 지정합니다. Field 데이터 형식으로 값을 지정하십시오. 다음 표는 JDBC(Java Database Connectivity) 데이터 형식을 Data API 호출에서 지정하는 데이터 형식에 매핑합니다.

DECIMAL 및 TIME 등 특정 유형에는 데이터 API가 String 값을 데이터베이스에 올바른 유형으로 전달할 수 있도록 힌트가 필요합니다. 힌트를 사용하려면 typeHint에 대한 값을 SqlParameter 데이터 형식에 포함합니다. typeHint에 가능한 값은 다음과 같습니다.

AWS CLI를 사용하여 RDS 데이터 API 호출

AWS CLI를 사용하여 RDS 데이터 API(데이터 API)를 호출할 수 있습니다.

다음 예제에서는 데이터 API용 AWS CLI를 사용합니다. 자세한 내용은 AWS CLI Data API 참조를 참조하세요.

각 예에서 DB 클러스터의 Amazon 리소스 이름(ARN)을 Aurora DB 클러스터의 ARN으로 바꿉니다. 또한 DB 클러스터에 대한 액세스를 허용하는 Secrets Manager의 보안 암호의 ARN으로 보안 암호 ARN을 바꿉니다.

SQL 트랜잭션 시작

aws rds-data begin-transaction CLI 명령을 사용하여 SQL 트랜잭션을 시작할 수 있습니다. 이 호출은 트랜잭션 식별자를 반환합니다.

일반 옵션 외에도, 데이터베이스 이름을 제공하는 --database 옵션을 지정합니다.

예를 들어, 다음 CLI 명령은 SQL 트랜잭션을 시작합니다.

대상 LinuxmacOS, 또는Unix:

aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

Windows의 경우:

aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

다음은 이 응답의 예입니다.

{
    "transactionId": "ABC1234567890xyz"
}

SQL 문 실행

aws rds-data execute-statement CLI 명령을 사용하여 SQL 문을 실행할 수 있습니다.

--transaction-id 옵션으로 트랜잭션 식별자를 지정하여 트랜잭션에서 SQL 문을 실행할 수 있습니다. aws rds-data begin-transaction CLI 명령을 사용하여 트랜잭션을 시작할 수 있습니다. aws rds-data commit-transaction CLI 명령을 사용하여 트랜잭션을 끝내고 커밋할 수 있습니다.

일반 옵션 외에도 다음 옵션을 지정하십시오.

DB 클러스터는 각 호출에 대한 응답을 반환합니다.

예를 들어, 다음 CLI 명령은 단일 SQL 문을 실행하고 결과에서 메타데이터를 생략합니다(기본값).

대상 LinuxmacOS, 또는Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"

Windows의 경우:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"

다음은 이 응답의 예입니다.

{
    "numberOfRecordsUpdated": 0,
    "records": [
        [
            {
                "longValue": 1
            },
            {
                "stringValue": "ValueOne"
            }
        ],
        [
            {
                "longValue": 2
            },
            {
                "stringValue": "ValueTwo"
            }
        ],
        [
            {
                "longValue": 3
            },
            {
                "stringValue": "ValueThree"
            }
        ]
    ]
}

다음 CLI 명령은 --transaction-id 옵션을 지정하여 트랜잭션에서 단일 SQL 문을 실행합니다.

대상 LinuxmacOS, 또는Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

Windows의 경우:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

다음은 이 응답의 예입니다.

{
    "numberOfRecordsUpdated": 1
}

다음 CLI 명령은 파라미터가 있는 단일 SQL 문을 실행합니다.

대상 LinuxmacOS, 또는Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

Windows의 경우:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

다음은 이 응답의 예입니다.

{
    "numberOfRecordsUpdated": 1
}

다음 CLI 명령은 데이터 정의 언어(DDL) SQL 문을 실행합니다. DDL 문은 job 열을 role 열로 이름을 바꿉니다.

대상 LinuxmacOS, 또는Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

Windows의 경우:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

다음은 이 응답의 예입니다.

{
    "generatedFields": [],
    "numberOfRecordsUpdated": 0
}

데이터 배열에서 일괄 SQL 문 실행

aws rds-data batch-execute-statement CLI 명령을 사용하여 데이터 배열에 대해 일괄 SQL 문을 실행할 수 있습니다. 이 명령을 사용하여 일괄 가져오기 또는 업데이트 작업을 수행할 수 있습니다.

--transaction-id 옵션으로 트랜잭션 식별자를 지정하여 트랜잭션에서 SQL 문을 실행할 수 있습니다. aws rds-data begin-transaction CLI 명령을 사용하여 트랜잭션을 시작할 수 있습니다. aws rds-data commit-transaction CLI 명령을 사용하여 트랜잭션을 종료하고 커밋할 수 있습니다.

일반 옵션 외에도 다음 옵션을 지정하십시오.

DB 클러스터는 호출에 대한 응답을 반환합니다.

예를 들어, 다음 CLI 명령은 파라미터 세트를 이용해 데이터 배열에 대해 배치 SQL 문을 실행합니다.

대상 LinuxmacOS, 또는Unix:

aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" \
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"

Windows의 경우:

aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" ^
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"

SQL 트랜잭션 커밋

aws rds-data commit-transaction CLI 명령을 사용하여 aws rds-data begin-transaction으로 시작한 SQL 트랜잭션을 종료하고 변경 사항을 커밋할 수 있습니다.

일반 옵션 외에 다음 옵션을 지정하십시오.

예를 들어 다음 CLI 명령은 SQL 트랜잭션을 끝내고 변경 내용을 커밋합니다.

대상 LinuxmacOS, 또는Unix:

aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

Windows의 경우:

aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

다음은 이 응답의 예입니다.

{
    "transactionStatus": "Transaction Committed"
}

SQL 트랜잭션 롤백

aws rds-data rollback-transaction CLI 명령을 사용하여 aws rds-data begin-transaction으로 시작한 SQL 트랜잭션을 롤백할 수 있습니다. 트랜잭션을 롤백하면 변경 내용이 취소됩니다.

일반 옵션 외에 다음 옵션을 지정하십시오.

예를 들어 다음 AWS CLI 명령은 SQL 트랜잭션을 롤백합니다.

대상 LinuxmacOS, 또는Unix:

aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

Windows의 경우:

aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

다음은 이 응답의 예입니다.

{
    "transactionStatus": "Rollback Complete"
    }

Python 애플리케이션에서 RDS 데이터 API 호출

Python 애플리케이션에서 RDS 데이터 API(데이터 API)를 호출할 수 있습니다.

다음 예제에서는 AWS SDK for Python(Boto)을 사용합니다. Boto에 대한 자세한 내용은 AWS SDK for Python(Boto 3) 설명서를 참조하세요.

각 예에서 DB 클러스터의 Amazon 리소스 이름(ARN)을 Aurora DB 클러스터의 ARN으로 바꿉니다. 또한 DB 클러스터에 대한 액세스를 허용하는 Secrets Manager의 보안 암호의 ARN으로 보안 암호 ARN을 바꿉니다.

SQL 쿼리 실행

SELECT 문을 실행하고 Python 애플리케이션으로 결과를 가져올 수 있습니다.

다음 예는 SQL 쿼리를 실행합니다.

import boto3

rdsData = boto3.client('rds-data')

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

response1 = rdsData.execute_statement(
            resourceArn = cluster_arn,
            secretArn = secret_arn,
            database = 'mydb',
            sql = 'select * from employees limit 3')

print (response1['records'])
[
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'ROSALEZ'
        },
        {
            'stringValue': 'ALEJANDRO'
        },
        {
            'stringValue': '2016-02-15 04:34:33.0'
        }
    ],
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'DOE'
        },
        {
            'stringValue': 'JANE'
        },
        {
            'stringValue': '2014-05-09 04:34:33.0'
        }
    ],
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'STILES'
        },
        {
            'stringValue': 'JOHN'
        },
        {
            'stringValue': '2017-09-20 04:34:33.0'
        }
    ]
]

DML SQL 문 실행

데이터 조작 언어(DML) 문을 실행하여 데이터베이스의 데이터를 삽입, 업데이트 또는 삭제할 수 있습니다. DML 문에 파라미터를 사용할 수도 있습니다.

다음 예제는 insert SQL 문을 실행하고 파라미터를 사용합니다.

import boto3

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

rdsData = boto3.client('rds-data')


param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO'}}
paramSet = [param1, param2]

response2 = rdsData.execute_statement(resourceArn=cluster_arn,
                                      secretArn=secret_arn,
                                      database='mydb',
                                      sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)',
                                      parameters = paramSet)

print (response2["numberOfRecordsUpdated"])

SQL 트랜잭션 실행

SQL 트랜잭션을 시작하고 하나 이상의 SQL 문을 실행한 다음, 변경 사항을 Python 애플리케이션으로 커밋할 수 있습니다.

다음 예에서는 테이블에 행을 삽입하는 SQL 트랜잭션을 실행합니다.

import boto3

rdsData = boto3.client('rds-data')

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

tr = rdsData.begin_transaction(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     database = 'mydb')

response3 = rdsData.execute_statement(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     database = 'mydb',
     sql = 'insert into employees(first_name, last_name) values('XIULAN', 'WANG')',
     transactionId = tr['transactionId'])

cr = rdsData.commit_transaction(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     transactionId = tr['transactionId'])

cr['transactionStatus']
'Transaction Committed'

response3['numberOfRecordsUpdated']
1

Java 애플리케이션에서 RDS 데이터 API 호출

Java 애플리케이션에서 RDS 데이터 API(데이터 API)를 호출할 수 있습니다.

다음 예제는 AWS SDK for Java를 사용합니다. 자세한 내용은 AWS SDK for Java 개발자 안내서를 참조하십시오.

각 예에서 DB 클러스터의 Amazon 리소스 이름(ARN)을 Aurora DB 클러스터의 ARN으로 바꿉니다. 또한 DB 클러스터에 대한 액세스를 허용하는 Secrets Manager의 보안 암호의 ARN으로 보안 암호 ARN을 바꿉니다.

SQL 쿼리 실행

SELECT 문을 실행하고 Java 애플리케이션으로 결과를 가져올 수 있습니다.

다음 예는 SQL 쿼리를 실행합니다.

package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;

import java.util.List;

public class FetchResultsExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
    AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    ExecuteStatementRequest request = new ExecuteStatementRequest()
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withDatabase("mydb")
            .withSql("select * from mytable");

    ExecuteStatementResult result = rdsData.executeStatement(request);

    for (List<Field> fields: result.getRecords()) {
      String stringValue = fields.get(0).getStringValue();
      long numberValue = fields.get(1).getLongValue();

      System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
    }
  }
}

SQL 트랜잭션 실행

SQL 트랜잭션을 시작하고 하나 이상의 SQL 문을 실행한 다음, 변경 사항을 Java 애플리케이션으로 커밋할 수 있습니다.

다음 예는 SQL 트랜잭션을 실행합니다.

package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BeginTransactionRequest;
import com.amazonaws.services.rdsdata.model.BeginTransactionResult;
import com.amazonaws.services.rdsdata.model.CommitTransactionRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;

public class TransactionExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
    AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    BeginTransactionRequest beginTransactionRequest = new BeginTransactionRequest()
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withDatabase("mydb");
    BeginTransactionResult beginTransactionResult = rdsData.beginTransaction(beginTransactionRequest);
    String transactionId = beginTransactionResult.getTransactionId();

    ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest()
            .withTransactionId(transactionId)
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withSql("INSERT INTO test_table VALUES ('hello world!')");
    rdsData.executeStatement(executeStatementRequest);

    CommitTransactionRequest commitTransactionRequest = new CommitTransactionRequest()
            .withTransactionId(transactionId)
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN);
    rdsData.commitTransaction(commitTransactionRequest);
  }
}

일괄 SQL 작업 실행

Java 애플리케이션을 사용하여 데이터 배열에 대해 대량 삽입 및 업데이트 작업을 실행할 수 있습니다. 파라미터 세트의 배열을 사용하여 DML 문을 실행할 수 있습니다.

다음 예제에서는 대량 삽입 작업을 실행합니다.

package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;

import java.util.Arrays;

public class BatchExecuteExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
      AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
            .withDatabase("test")
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withSql("INSERT INTO test_table2 VALUES (:string, :number)")
            .withParameterSets(Arrays.asList(
                    Arrays.asList(
                            new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
                            new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
                    ),
                    Arrays.asList(
                            new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
                            new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
                    )
            ));

    rdsData.batchExecuteStatement(request);
  }
}

데이터 API 시간 초과 동작 제어

데이터 API에 대한 모든 호출은 동기식입니다. INSERT 또는 CREATE TABLE과 같은 SQL 문을 실행하는 데이터 API 작업을 수행한다고 가정해 보겠습니다. 데이터 API 호출이 성공적으로 반환되면 호출이 반환되는 시점에 SQL 처리가 완료됩니다.

기본적으로 데이터 API는 45초 이내에 처리가 완료되지 않으면 작업을 취소하고 시간 초과 오류를 반환합니다. 이 경우 데이터가 삽입되지 않고 테이블이 생성되지 않는 등의 문제가 발생합니다.

데이터 API를 사용하여 45초 이내에 완료할 수 없는 장기 실행 작업을 수행할 수 있습니다. 대용량 테이블에 대한 대량 INSERT 또는 DDL 작업과 같은 작업이 45초보다 오래 걸릴 것으로 예상되는 경우, ExecuteStatement 작업에 continueAfterTimeout 파라미터를 지정할 수 있습니다. 애플리케이션에 여전히 시간 초과 오류가 발생합니다. 하지만 작업은 계속 실행되며 취소되지 않습니다. 예시는 SQL 트랜잭션 실행을 확인하세요.

사용 중인 프로그래밍 언어용 AWS SDK에 API 호출 또는 HTTP 소켓 연결에 대한 자체 시간 초과 기간이 있는 경우 이러한 시간 초과 기간이 모두 45초 이상인지 확인하세요. 일부 SDK의 경우 기본적으로 시간 초과 기간이 45초 미만입니다. SDK별 또는 클라이언트별 시간 초과 기간을 최소 1분으로 설정하는 것이 좋습니다. 이렇게 하면 데이터 API 작업이 성공적으로 완료되는 동안 애플리케이션에 시간 초과 오류가 발생할 가능성을 방지할 수 있습니다. 이렇게 하면 작업을 다시 시도할지 여부를 확인할 수 있습니다.

예를 들어 SDK가 애플리케이션에 시간 초과 오류를 반환하지만 데이터 API 작업이 여전히 데이터 API 시간 초과 간격 내에 완료되었다고 가정해 보겠습니다. 이 경우 작업을 다시 시도하면 중복 데이터가 삽입되거나 잘못된 결과가 발생할 수 있습니다. SDK가 자동으로 작업을 다시 시도하여 애플리케이션에서 아무런 조치를 취하지 않아도 잘못된 데이터가 발생할 수 있습니다.

시간 초과 간격은 Java 2 SDK에서 특히 중요합니다. 해당 SDK에서 API 호출 시간 초과와 HTTP 소켓 시간 초과 모두 기본적으로 30초입니다. 다음은 이러한 시간 제한을 더 높은 값으로 설정하는 예제입니다.

public RdsDataClient createRdsDataClient() {
    return RdsDataClient.builder()
        .region(Region.US_EAST_1) // Change this to your desired Region
        .overrideConfiguration(createOverrideConfiguration())
        .httpClientBuilder(createHttpClientBuilder())
        .credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
        .build();
}

private static ClientOverrideConfiguration createOverrideConfiguration() {
    return ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofSeconds(60))
        .build();
}
    
private HttpClientBuilder createHttpClientBuilder() {
    return ApacheHttpClient.builder() // Change this to your desired HttpClient
        .socketTimeout(Duration.ofSeconds(60));
}

다음은 비동기 데이터 클라이언트를 사용한 동일한 예제입니다.

public static RdsDataAsyncClient createRdsDataAsyncClient() {
    return RdsDataAsyncClient.builder()
        .region(Region.US_EAST_1) // Change this to your desired Region
        .overrideConfiguration(createOverrideConfiguration())
        .credentialsProvider(defaultCredentialsProvider())  // Change this to your desired credentials provider
        .build();
}

private static ClientOverrideConfiguration createOverrideConfiguration() {
    return ClientOverrideConfiguration.builder()
        .apiCallAttemptTimeout(Duration.ofSeconds(60))
        .build();
}

private HttpClientBuilder createHttpClientBuilder() {
    return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient
        .readTimeout(Duration.ofSeconds(60));
}

RDS 데이터 API용 Java 클라이언트 라이브러리 사용

RDS 데이터 API(데이터 API)용 Java 클라이언트 라이브러리를 다운로드하여 사용할 수 있습니다. 이 Java 클라이언트 라이브러리는 데이터 API를 사용할 수 있는 다른 방법을 제공합니다. 이 라이브러리를 사용하면 클라이언트 측 클래스를 데이터 API 요청 및 응답에 매핑할 수 있습니다. 이러한 매핑 지원을 통해 Date, Time, BigDecimal 등 일부 특정 Java 유형과 쉽게 통합할 수 있습니다.

데이터 API용 Java 클라이언트 라이브러리 다운로드

Data API Java 클라이언트 라이브러리는 다음 위치의 GitHub에서 오픈 소스로 제공됩니다.

https://github.com/awslabs/rds-data-api-client-library-java

소스 파일에서 라이브러리를 수동으로 빌드할 수 있지만 모범 사례는 Apache Maven 종속성 관리를 사용해 라이브러리를 사용하는 것입니다. Maven POM 파일에 다음 종속성을 추가하세요.

AWS SDK 2.x와 호환되는 버전 2.x의 경우 다음을 사용하세요.

<dependency>
   <groupId>software.amazon.rdsdata</groupId>
   <artifactId>rds-data-api-client-library-java</artifactId>
   <version>2.0.0</version>
</dependency>

AWS SDK 1.x와 호환되는 버전 1.x의 경우 다음을 사용하세요.

<dependency>
    <groupId>software.amazon.rdsdata</groupId>
    <artifactId>rds-data-api-client-library-java</artifactId>
    <version>1.0.8</version>
</dependency>

Java 클라이언트 라이브러리 예시

아래에는 데이터 API Java 클라이언트 라이브러리 사용에 관한 몇 가지 일반적인 예시가 나와 있습니다. 이 예시에서는 accounts와 accountId이라는 두 개의 열이 있는 name라는 테이블이 있다고 가정합니다. 또한 다음과 같은 데이터 전송 객체(DTO)도 있습니다.

public class Account {
    int accountId;
    String name;
    // getters and setters omitted
}

클라이언트 라이브러리를 통해 DTO를 입력 파라미터로 전달할 수 있습니다. 다음 예시에서는 고객 DTO가 입력 파라미터 세트로 매핑되는 방식을 보여줍니다.

var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParamSets(account1, account2)
         .execute();

어떤 경우에는 입력 파라미터인 간단한 값으로 작업하는 것이 더 쉽습니다. 다음 구문을 사용하면 이러한 작업이 가능합니다.

client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParameter("accountId", 3)
         .withParameter("name", "Zhang")
         .execute();

다음은 입력 파라미터인 간단한 값으로 작업하는 또 다른 예시입니다.

client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
         .execute();
                

클라이언트 라이브러리에서는 결과가 반환될 때 DTO에 대한 자동 매핑을 제공합니다. 다음 예시에서는 결과가 DTO에 매핑되는 방식을 보여줍니다.

List<Account> result = client.forSql("SELECT * FROM accounts")
          .execute()
          .mapToList(Account.class);

Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
          .execute()
          .mapToSingle(Account.class);

대부분의 경우 데이터베이스 결과 집합에는 단일 값만 포함됩니다. 이러한 결과 검색을 단순화하기 위해 클라이언트 라이브러리는 다음 API를 제공합니다.

int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
          .execute()
          .singleValue(Integer.class);

JSON 형식의 RDS 데이터 API 쿼리 결과 처리

ExecuteStatement 작업을 호출할 때 쿼리 결과를 JSON 형식의 문자열로 반환하도록 선택할 수 있습니다. 이렇게 하면 프로그래밍 언어의 JSON 구문 분석 기능을 사용하여 결과 집합을 해석하고 형식을 다시 지정할 수 있습니다. 그러면 결과 집합을 반복하고 각 열 값을 해석하는 추가 코드를 작성하지 않아도 됩니다.

결과 집합을 JSON 형식으로 요청하려면 선택적으로 formatRecordsAs 파라미터를 JSON 값과 함께 전달합니다. JSON 형식의 결과 집합이 ExecuteStatementResponse 구조의 formattedRecords 필드에 반환됩니다.

BatchExecuteStatement 작업은 결과 집합을 반환하지 않습니다. 따라서 JSON 옵션은 해당 작업에 적용되지 않습니다.

JSON 해시 구조에서 키를 사용자 정의하려면 결과 집합에서 열 별칭을 정의합니다. SQL 쿼리의 열 목록에 있는 AS 절을 사용하면 됩니다.

JSON 기능을 사용하여 결과 집합을 더 쉽게 읽도록 하고 내용을 언어별 프레임워크에 매핑할 수 있습니다. ASCII로 인코딩된 결과 집합의 볼륨이 기본 표현보다 크기 때문에 많은 수의 행이나 큰 열 값을 반환하여 애플리케이션에서 사용할 수 있는 것보다 많은 메모리를 사용하는 쿼리에 기본 표현을 선택할 수 있습니다.

JSON 형식의 쿼리 결과 검색

결과 집합을 JSON 문자열로 수신하려면 ExecuteStatement 호출에 .withFormatRecordsAs(RecordsFormatType.JSON)을 포함하세요. 반환 값은 formattedRecords 필드에 JSON 문자열로 반환됩니다. 이 경우 columnMetadata는 null입니다. 열 레이블은 각 행을 나타내는 객체의 키입니다. 이 열 이름은 결과 집합의 각 행에서 반복됩니다. 열 값은 따옴표로 묶인 문자열, 숫자 값 또는 true, false 또는 null을 나타내는 특수 값입니다. 길이 제약 조건 및 숫자 및 문자열의 정확한 유형과 같은 열 메타데이터는 JSON 응답에 보존되지 않습니다.

.withFormatRecordsAs() 호출을 생략하거나 NONE의 파라미터를 지정하는 경우 결과 집합은 Records 및 columnMetadata 필드를 사용하여 이진 형식으로 반환됩니다.

데이터 유형 매핑

결과 집합의 SQL 값은 더 작은 JSON 유형 집합에 매핑됩니다. 값은 JSON에서 문자열, 숫자 및 true, false 및 null과 같은 특수 상수로 표시됩니다. 프로그래밍 언어에 적합하도록 강한 타이핑 또는 약한 타이핑을 사용하여 이 값을 애플리케이션에서 변수로 변환할 수 있습니다.

문제 해결

JSON 응답은 10MB로 제한됩니다. 응답이 이 한도보다 크면 프로그램에서 BadRequestException 오류를 받습니다. 이런 경우 다음 기법 중 하나를 사용하여 오류를 해결할 수 있습니다.

예시

다음 Java 예제는 응답이 JSON 형식의 문자열인 ExecuteStatement를 호출한 후 결과 집합을 해석하는 방법을 보여줍니다. databaseName, secretStoreArn 및 clusterArn 파라미터를 적절한 값으로 대체합니다.

다음 Java 예제에서는 결과 집합에서 소수 값을 반환하는 쿼리를 보여줍니다. assertThat 호출은 응답 필드에 JSON 결과 집합에 대한 규칙을 기반으로 예상되는 속성이 있는지 테스트합니다.

이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.

create table test_simplified_json (a float);
insert into test_simplified_json values(10.0);

public void JSON_result_set_demo() {
    var sql = "select * from test_simplified_json";
    var request = new ExecuteStatementRequest()
      .withDatabase(databaseName)
      .withSecretArn(secretStoreArn)
      .withResourceArn(clusterArn)
      .withSql(sql)
      .withFormatRecordsAs(RecordsFormatType.JSON);
    var result = rdsdataClient.executeStatement(request);
}

이전 프로그램의 formattedRecords 필드 값은 다음과 같습니다.

[{"a":10.0}]

JSON 결과 집합이 있기 때문에 응답의 Records 및 ColumnMetadata 필드는 모두 Null입니다.

다음 Java 예제에서는 결과 집합에서 정수 값을 반환하는 쿼리를 보여줍니다. 예제는 getFormattedRecords를 호출하여 JSON 형식의 문자열만 반환하고 비어 있거나 Null인 다른 응답 필드는 무시합니다. 이 예제에서는 결과를 레코드 목록을 나타내는 구조로 역직렬화합니다. 각 레코드에는 이름이 결과 집합의 열 별칭에 해당하는 필드가 있습니다. 이 기법은 결과 집합을 구문 분석하는 코드를 단순화합니다. 애플리케이션에서 결과 집합의 행과 열을 반복하여 각 값을 적절한 유형으로 변환할 필요가 없습니다.

이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.

create table test_simplified_json (a int);
insert into test_simplified_json values(17);

public void JSON_deserialization_demo() {
    var sql = "select * from test_simplified_json";
    var request = new ExecuteStatementRequest()
      .withDatabase(databaseName)
      .withSecretArn(secretStoreArn)
      .withResourceArn(clusterArn)
      .withSql(sql)
      .withFormatRecordsAs(RecordsFormatType.JSON);
    var result = rdsdataClient.executeStatement(request)
      .getFormattedRecords();

/* Turn the result set into a Java object, a list of records.
   Each record has a field 'a' corresponding to the column
   labelled 'a' in the result set. */
    private static class Record { public int a; }
    var recordsList = new ObjectMapper().readValue(
        response, new TypeReference<List<Record>>() {
        });
}

이전 프로그램의 formattedRecords 필드 값은 다음과 같습니다.

[{"a":17}]

결과 행 0의 a 열을 검색하려면 애플리케이션은 recordsList.get(0).a를 참조합니다.

반대로 다음 Java 예제에서는 JSON 형식을 사용하지 않을 때 결과 집합을 포함하는 데이터 구조를 구성하는 데 필요한 코드 종류를 보여줍니다. 이 경우 결과 집합의 각 행에는 단일 사용자에 대한 정보가 포함된 필드가 포함됩니다. 결과 집합을 나타내는 데이터 구조를 구축하려면 행을 반복해야 합니다. 각 행에 대해 코드는 각 필드의 값을 검색하고 적절한 형식 변환을 수행하며 행을 나타내는 객체의 해당 필드에 결과를 할당합니다. 그런 다음 코드는 각 사용자를 나타내는 객체를 전체 결과 집합을 나타내는 데이터 구조에 추가합니다. 결과 집합에서 필드를 재정렬, 추가 또는 제거하도록 쿼리가 변경된 경우 애플리케이션 코드도 변경해야 합니다.

/* Verbose result-parsing code that doesn't use the JSON result set format */
for (var row: response.getRecords()) {
    var user = User.builder()
      .userId(row.get(0).getLongValue())
      .firstName(row.get(1).getStringValue())
      .lastName(row.get(2).getStringValue())
      .dob(Instant.parse(row.get(3).getStringValue()))
      .build();
    result.add(user);
  } 

다음 샘플 값은 열, 열 별칭 및 열 데이터 유형이 서로 다른 결과 집합에 대한 formattedRecords 필드의 값을 보여줍니다.

결과 집합에 여러 행이 포함된 경우 각 행은 배열 요소인 객체로 표시됩니다. 결과 집합의 각 열은 객체 내에서 키가 됩니다. 키는 결과 집합의 각 행에서 반복됩니다. 따라서 여러 행과 열로 구성된 결과 집합의 경우 전체 응답의 길이 제한을 초과하지 않도록 짧은 열 별칭을 정의해야 할 수 있습니다.

이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.

create table sample_names (id int, name varchar(128));
insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");

[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"},
{"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]

결과 집합의 열이 표현식으로 정의된 경우 표현식의 텍스트가 JSON 키가 됩니다. 따라서 일반적으로 쿼리의 선택 목록에서 각 표현식에 대한 설명 열 별칭을 정의하는 것이 편리합니다. 예를 들어, 다음 쿼리는 선택 목록에 함수 호출 및 산술 연산과 같은 표현식을 포함합니다.

select count(*), max(id), 4+7 from sample_names;

이러한 표현식은 키로 JSON 결과 집합을 통해 전달됩니다.

[{"count(*)":5,"max(id)":4,"4+7":11}]

설명 레이블이 있는 AS 열을 추가하면 JSON 결과 집합에서 키를 보다 간단하게 해석할 수 있습니다.

select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;

수정된 SQL 쿼리의 경우, AS 절에 의해 정의된 열 레이블이 키 이름으로 사용됩니다.

[{"rows":5,"largest_id":4,"addition_result":11}]

JSON 문자열의 각 키 값 쌍의 값은 따옴표로 묶인 문자열일 수 있습니다. 문자열에는 유니코드 문자가 포함될 수 있습니다. 문자열에 이스케이프 시퀀스가 포함되어 있거나 " 또는 \문자가 포함되어 있는 경우 이러한 문자 앞에는 백슬래시 이스케이프 문자가 있습니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다. 예를 들어 string_with_escape_sequences 결과에는 특수 문자 백스페이스, 줄 바꿈, 캐리지 리턴, 탭, 양식 피드 및 \가 포함됩니다.

[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}] 

JSON 문자열의 각 키 값 쌍의 값은 숫자를 나타낼 수도 있습니다. 숫자는 정수, 부동 소수점 값, 음수 값 또는 지수 표기법으로 표현되는 값일 수 있습니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다.

[{"integer_value":17}]
[{"float_value":10.0}]
[{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}]
[{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}] 

부울 값과 Null 값은 따옴표 없는 특수 키워드 true, false 및 null로 표현됩니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다.

[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}] 

BLOB 유형의 값을 선택하면 결과가 JSON 문자열에서 base64로 인코딩된 값으로 표시됩니다. 값을 원래 표현으로 다시 변환하려면 애플리케이션의 언어로 적절한 디코딩 기능을 사용할 수 있습니다. 예를 들어 Java에서는 Base64.getDecoder().decode() 함수를 호출합니다. 다음 샘플 출력은 hello world의 BLOB 값을 선택하고 결과 집합을 JSON 문자열로 반환한 것을 보여줍니다.

[{"blob_column":"aGVsbG8gd29ybGQ="}]

다음 Python 예제는 Python execute_statement 함수에 대한 호출의 결과에서 값에 액세스하는 방법을 보여줍니다. 결과 집합은 필드 response['formattedRecords']의 문자열 값입니다. 이 코드는 json.loads 함수를 호출하여 JSON 문자열을 데이터 구조로 변환합니다. 그러면 결과 집합의 각 행은 데이터 구조 내의 목록 요소이며 각 행 내에서 이름으로 결과 집합의 각 필드를 참조할 수 있습니다.

import json

result = json.loads(response['formattedRecords'])
print (result[0]["id"])

다음 JavaScript 예제는 JavaScript executeStatement 함수에 대한 호출의 결과에서 값에 액세스하는 방법을 보여줍니다. 결과 집합은 필드 response.formattedRecords의 문자열 값입니다. 이 코드는 JSON.parse 함수를 호출하여 JSON 문자열을 데이터 구조로 변환합니다. 그러면 결과 집합의 각 행은 데이터 구조 내의 배열 요소이며 각 행 내에서 이름으로 결과 집합의 각 필드를 참조할 수 있습니다.

<script>
    const result = JSON.parse(response.formattedRecords);
    document.getElementById("display").innerHTML = result[0].id;
</script> 

RDS 데이터 API 문제 해결

공통 오류 메시지를 소개하는 다음 섹션부터는 RDS 데이터 API(데이터 API)를 사용하면서 발생하는 문제를 해결하는 데 유용합니다.

트랜잭션 <transaction_ID>을 찾을 수 없습니다

위 오류 메시지는 데이터 API 호출 시 지정한 트랜잭션 ID를 찾을 수 없다는 것을 의미합니다. 이러한 문제가 발생하는 원인이 오류 메시지에 추가되며, 다음 중 한 가지로 표시됩니다.

트랜잭션 실행에 대한 자세한 내용은 RDS 데이터 API 호출 단원을 참조하세요.

쿼리 패킷이 너무 큽니다

위 오류 메시지는 행마다 반환되는 결과 집합이 너무 크다는 것을 의미합니다. 데이터 API는 데이터베이스에서 반환되는 결과 집합에서 각 행의 크기를 64KB로 제한합니다.

이 문제를 해결하려면 결과 집합의 각 행마다 크기를 64KB 이하로 유지해야 합니다.

데이터베이스 응답이 크기 제한을 초과했습니다

위 오류 메시지는 데이터베이스에서 반환되는 결과 집합의 크기가 너무 크다는 것을 의미합니다. Data API는 데이터베이스에서 반환되는 결과 집합의 크기를 1MiB로 제한합니다.

이러한 문제를 해결하려면 데이터 API 호출 시 반환되는 데이터 크기를 1MiB 이하로 유지해야 합니다. 반환해야 하는 결과 집합의 크기가 1MiB보다 크면 쿼리에서 다수의 ExecuteStatement 호출을 LIMIT 절과 함께 사용할 수 있습니다.

LIMIT 절에 대한 자세한 내용은 MySQL 설명서에서 SELECT 구문을 참조하세요.

HttpEndpoint가 클러스터 <cluster_ID>에서 활성화되지 않았습니다

이 문제의 잠재적인 원인은 다음과 같습니다.