기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# QLDB 쉘을 사용하여 Amazon QLDB에 액세스(데이터 API만 해당)
**중요**
지원 종료 알림: 기존 고객은 07/31/2025에 지원이 종료될 때까지 Amazon QLDB를 사용할 수 있습니다. 자세한 내용은 [Amazon QLDB 원장을 Amazon Aurora PostgreSQL로 마이그레이션](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)을 참조하세요.
Amazon QLDB는 트랜잭션 데이터 API와의 상호 작용을 위한 명령행 쉘을 제공합니다. QLDB 쉘을 사용하면 원장 데이터에 대해 [PartiQL](ql-reference.md) 문을 실행할 수 있습니다.
이 쉘의 최신 버전은 Rust에서 작성되었으며 기본 `main` 브랜치에 있는 GitHub 리포지토리 [awslabs/amazon-qldb-shell](https://github.com/awslabs/amazon-qldb-shell)에서 오픈 소스로 제공됩니다. Python 버전(v1)도 `master` 브랜치의 동일한 리포지토리에서 계속 사용할 수 있습니다.
**참고**
Amazon QLDB 쉘은 `qldb-session` 트랜잭션 데이터 API만 지원합니다. 이 API는 QLDB 원장에서 PartiQL 문을 실행하는 데만 사용됩니다.
명령행 인터페이스를 사용하여 `qldb` 관리 API 작업과 상호 작용하려면 [를 사용하여 Amazon QLDB에 액세스 AWS CLI (관리 API만 해당)](Tools.CLI.md) 섹션을 참조하세요.
이 도구는 애플리케이션에 통합하거나 프로덕션 목적으로 채택하기 위한 것이 아닙니다. 이 도구의 목적은 QLDB 및 PartiQL을 빠르게 실험해 볼 수 있도록 하는 것입니다.
다음 섹션에서는 QLDB shell 작업을 시작하는 방법을 설명합니다.
**Topics**
+ [
## 사전 조건
](#data-shell-prerequisites)
+ [
## 쉘 설치
](#data-shell-install)
+ [
## 쉘 호출
](#data-shell-invoking)
+ [
## 쉘 파라미터
](#data-shell-params)
+ [
## 명령 참조
](#data-shell-reference)
+ [
## 개별 명령문 실행
](#data-shell-indiv-statements)
+ [
## 트랜잭션 관리
](#data-shell-transactions)
+ [
## 쉘 종료
](#data-shell-exiting)
+ [
## 예제
](#data-shell-examples)
## 사전 조건
QLDB 쉘을 시작하기 전에 다음을 수행해야 합니다.
1. 의 AWS 설정 지침을 따릅니다[Amazon QLDB 액세스](accessing.md). 다음 내용이 포함됩니다:
1. 가입합니다 AWS.
1. 적절한 QLDB 권한을 가진 사용자를 생성합니다.
1. 개발을 위한 프로그래밍 방식 액세스 권한을 부여합니다.
1. AWS 자격 증명과 기본값을 설정합니다 AWS 리전. 자세한 설명은 *AWS Command Line Interface 사용자 가이드*에서 [구성 기본 사항](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)을 참조하세요.
사용 가능한 리전의 전체 목록은 *AWS 일반 참조*에서 [Amazon QLDB 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/qldb.html)을 참조하세요.
1. `STANDARD` 권한 모드의 모든 원장에 대해 적절한 표에서 PartiQL 문을 실행할 수 있는 권한을 부여하는 IAM 정책을 생성합니다. 이러한 정책을 생성하는 방법을 알아보려면 [Amazon QLDB에서 표준 권한 모드로 시작하기](getting-started-standard-mode.md)를 참조하세요.
## 쉘 설치
QLDB 쉘의 최신 버전을 설치하려면 GitHub의 [README.md](https://github.com/awslabs/amazon-qldb-shell/blob/main/README.md#installation) 파일을 참조하세요. QLDB는 GitHub 리포지토리의 [릴리스](https://github.com/awslabs/amazon-qldb-shell/releases) 섹션에서 Linux, macOS, Windows용으로 사전 빌드된 이진수 파일을 제공합니다.
macOS의 경우 쉘은 `aws/tap` [Homebrew](https://docs.brew.sh/) 탭과 통합됩니다. Homebrew를 사용하여 macOS에 쉘을 설치하려면 다음 명령을 실행합니다.
```
$ xcode-select --install # Required to use Homebrew
$ brew tap aws/tap # Add AWS as a Homebrew tap
$ brew install qldbshell
```
### 구성
설치 후 쉘은 초기화 중에 `$XDG_CONFIG_HOME/qldbshell/config.ion`에 있는 기본 구성 파일을 로드합니다. Linux 및 macOS의 경우 이 파일은 일반적으로 `~/.config/qldbshell/config.ion`에 있습니다. 이러한 파일이 없는 경우 쉘은 기본 설정으로 실행됩니다.
설치 후 수동으로 `config.ion` 파일을 만들 수 있습니다. 이 구성 파일은 [Amazon Ion](ion.md) 데이터 형식을 사용합니다. 다음은 최소 `config.ion` 파일의 예입니다.
```
{
default_ledger: "my-example-ledger"
}
```
`default_ledger`가 구성 파일에 설정되어 있지 않은 경우, 쉘을 호출할 때 `--ledger` 파라미터가 필요합니다. 구성 옵션의 전체 목록은 GitHub의 [README.md](https://github.com/awslabs/amazon-qldb-shell/blob/main/README.md#configuration) 파일을 참조하세요.
## 쉘 호출
명령행 터미널에서 특정 원장에 대해 QLDB 쉘을 호출하려면 다음 명령을 실행합니다. *my-example-ledger*를 원장 명칭을 바꿉니다.
```
$ qldb --ledger my-example-ledger
```
이 명령은 기본값에 연결됩니다 AWS 리전. 지역을 명시적으로 지정하려면 다음 섹션에 설명된 대로 `--region` 또는 `--qldb-session-endpoint` 파라미터를 사용하여 명령을 실행할 수 있습니다.
`qldb` 쉘 세션을 호출한 후 다음과 같은 입력 타입을 입력할 수 있습니다.
+ [쉘 명령](#data-shell-reference)
+ [개별 트랜잭션의 단일 PartiQL 명령문](#data-shell-indiv-statements)
+ [트랜잭션 내의 여러 PartiQL 명령문](#data-shell-transactions)
## 쉘 파라미터
쉘을 호출하는 데 사용할 수 있는 플래그 및 옵션의 전체 목록을 보려면 다음과 같이 `--help` 플래그와 함께 `qldb` 명령을 실행합니다.
```
$ qldb --help
```
다음은 `qldb` 명령의 몇 가지 주요 플래그와 옵션입니다. 이러한 선택적 파라미터를 추가하여 자격 증명 프로필 AWS 리전, 엔드포인트, 결과 형식 및 기타 구성 옵션을 재정의할 수 있습니다.
**사용량**
```
$ qldb [FLAGS] [OPTIONS]
```플래그
**`-h`, `--help`**
도움말 정보를 인쇄합니다.
**`-v`, `--verbose`**
로깅 세부 사항을 구성합니다. 기본적으로 쉘은 오류만 기록합니다. 세부 사항 수준을 높이려면 이 인수(예:`-vv`)를 반복합니다. 가장 높은 수준은 `trace` 세부 수준에 해당하는 `-vvv`입니다.
**`-V`, `--version`**
버전 정보를 인쇄합니다.OPTIONS
**`-l`, `--ledger` *LEDGER\$1NAME***
연결할 원장의 명칭입니다. `default_ledger`가 `config.ion` 파일에 설정되지 않은 경우 필요한 쉘 파라미터입니다. 이 파일에서 지역과 같은 추가 옵션을 설정할 수 있습니다.
**`-c`, `--config` *CONFIG\$1FILE***
모든 쉘 구성 옵션을 정의할 수 있는 파일입니다. 형식 지정 세부 정보 및 구성 옵션의 전체 목록은 GitHub의 [README.md](https://github.com/awslabs/amazon-qldb-shell/blob/main/README.md#configuration) 파일을 참조하세요.
**`-f`, `--format` `ion|table`**
쿼리 결과의 출력 형식입니다. 기본값은 `ion`입니다.
**`-p`, `--profile` *프로필***
인증에 사용할 AWS 자격 증명 프로필의 위치입니다.
제공되지 않은 경우 쉘은에 있는 기본 AWS 프로파일을 사용합니다`~/.aws/credentials`.
**`-r`, `--region` *REGION\$1CODE***
연결할 QLDB 원장의 AWS 리전 코드입니다. 예: `us-east-1`.
제공하지 않으면 쉘이 AWS 프로필에 지정된 AWS 리전 기본값에 연결됩니다.
**`-s`, `--qldb-session-endpoint` *QLDB\$1SESSION\$1ENDPOINT***
연결할 `qldb-session` API 엔드포인트.
사용 가능한 QLDB 지역 및 엔드포인트의 전체 목록은 *AWS 일반 참조*에서 [Amazon QLDB 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/qldb.html)을 참조하세요.
## 명령 참조
`qldb` 세션을 호출한 후 쉘은 다음 키와 데이터베이스 명령을 지원합니다.
**쉘 키**
| 키 | 함수 설명 |
| --- | --- |
| Enter | 문을 실행합니다. |
| Escape\$1Enter (macOS, Linux) Shift\$1Enter (Windows) | 새 행을 시작하여 여러 행에 걸친 문을 입력합니다. 입력 텍스트를 여러 행로 복사하여 쉘에 붙여넣을 수도 있습니다. macOS에서 Meta 키로 Escape 대신 Option을 설정하는 방법에 대한 지침은 [OS X Daily](https://osxdaily.com/2013/02/01/use-option-as-meta-key-in-mac-os-x-terminal/) 사이트를 참조하세요. |
| Ctrl\$1C | 현재 명령을 취소합니다. |
| Ctrl\$1D | 파일 끝(EOF)에 신호를 보내고 쉘의 현재 수준을 종료합니다. 활성 트랜잭션에 없는 경우 쉘을 종료합니다. 활성 트랜잭션에서 트랜잭션을 중단합니다. |
**쉘 데이터베이스 명령**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/qldb/latest/developerguide/data-shell.html)
**참고**
모든 QLDB 쉘 명령은 대소문자를 구분하지 않습니다.
## 개별 명령문 실행
[README.md](https://github.com/awslabs/amazon-qldb-shell/blob/main/README.md#command-interface)에 나열된 데이터베이스 명령과 쉘 메타 명령을 제외하고 쉘은 사용자가 입력하는 각 명령을 별도의 PartiQL 문으로 해석합니다. 기본적으로 쉘은 `auto-commit` 모드를 활성화합니다. 이 모드는 구성할 수 있습니다.
`auto-commit` 모드에서는 쉘이 각 명령문을 자체 트랜잭션에서 암시적으로 실행하고 오류가 발견되지 않으면 트랜잭션을 자동으로 체결합니다. 즉, 문을 실행할 때마다 `start transaction`(또는 `begin`) 및 `commit`을 수동으로 실행하지 않아도 됩니다.
## 트랜잭션 관리
또는 QLDB 쉘을 사용하여 트랜잭션을 수동으로 제어할 수 있습니다. 명령 및 명령문을 순차적으로 일괄 처리하여 트랜잭션 내에서 여러 명령문을 대화식으로 실행하거나 비대화식으로 실행할 수 있습니다.
### 대화형 트랜잭션
대화형 트랜잭션을 실행하려면 다음 단계를 수행합니다.
1. 트랜잭션을 시작하려면 `begin` 명령을 입력합니다.
```
qldb> begin
```
트랜잭션을 시작하면 쉘에 다음 명령 프롬프트가 표시됩니다.
```
qldb *>
```
1. 그러면 입력한 각 명령문이 동일한 트랜잭션에서 실행됩니다.
+ 예컨대 다음과 같이 단일 명령문을 실행할 수 있습니다.
```
qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'
```
Enter를 누르면 쉘에 명령문의 결과가 표시됩니다.
+ 다음과 같이 여러 개의 명령문이나 명령을 세미콜론(`;`)구분 기호로 구분하여 입력할 수도 있습니다.
```
qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; commit
```
1. 트랜잭션을 종료하려면 다음 명령 중 하나를 입력합니다.
+ `commit` 명령을 입력하여 트랜잭션을 원장 저널에 체결합니다.
```
qldb *> commit
```
+ `abort` 명령을 입력하여 트랜잭션을 중지하고 변경한 내용을 거부합니다.
```
qldb *> abort
transaction was aborted
```
**트랜잭션 시간 초과 제한**
대화형 트랜잭션은 QLDB의 [시간 초과 제한](limits.md#limits.fixed)을 준수합니다. 시작 후 **30초** 이내에 트랜잭션을 체결하지 않으면 QLDB는 트랜잭션을 자동으로 만료시키고 트랜잭션 중에 이루어진 모든 변경 사항을 거부합니다.
그러면 쉘은 명령문 결과를 표시하는 대신 만료 오류 메시지를 표시하고 일반 명령 프롬프트로 돌아갑니다. 다시 시도하려면 `begin` 명령을 다시 입력하여 새 트랜잭션을 시작해야 합니다.
```
transaction failed after 1 attempts, last error: communication failure: Transaction 2UMpiJ5hh7WLjVgEiMLOoO has expired
```
### 비대화형 트랜잭션
다음과 같이 명령과 명령문을 순차적으로 일괄 처리하여 여러 명령문으로 전체 트랜잭션을 실행할 수 있습니다.
```
qldb> begin; SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; SELECT * FROM Person p, DriversLicense l WHERE p.GovId = l.LicenseNumber; commit
```
각 명령과 명령문을 세미콜론(`;`) 구분 기호로 구분해야 합니다. 트랜잭션의 명령문이 유효하지 않은 경우 쉘은 자동으로 트랜잭션을 거부합니다. 쉘은 사용자가 입력한 후속 명령문을 처리하지 않습니다.
여러 트랜잭션을 설정할 수도 있습니다.
```
qldb> begin; statement1; commit; begin; statement2; statement3; commit
```
이전 예와 마찬가지로, 트랜잭션이 실패하면 쉘은 사용자가 입력한 후속 트랜잭션이나 명령문을 진행하지 않습니다.
트랜잭션을 종료하지 않으면 쉘이 대화형 모드로 전환되고 다음 명령문이나 문을 입력하라는 메시지가 표시됩니다.
```
qldb> begin; statement1; commit; begin
qldb *>
```
## 쉘 종료
현재 `qldb` 쉘 세션을 종료하려면 `exit` 또는 `quit` 명령을 입력하거나 쉘이 트랜잭션에 있지 않은 경우 키보드 단축키 Ctrl\$1D를 사용합니다.
```
qldb> exit
$
```
```
qldb> quit
$
```
## 예제
QLDB에서 PartiQL 문을 작성하는 방법에 대한 자세한 설명은 [Amazon QLDB PartiQL 참조](ql-reference.md) 섹션을 참조하세요.
**Example**
다음 예에서는 일반적인 기본 명령 순서를 보여줍니다.
QLDB 쉘은 이 예의 각 PartiQL 문을 자체 트랜잭션으로 실행합니다.
이 예에서는 원장 `test-ledger`이 이미 존재하고 활성 상태라고 가정합니다.
```
$ qldb --ledger test-ledger --region us-east-1
qldb> CREATE TABLE TestTable
qldb> INSERT INTO TestTable `{"Name": "John Doe"}`
qldb> SELECT * FROM TestTable
qldb> DROP TABLE TestTable
qldb> exit
```