Mengakses Amazon QLDB menggunakan shell QLDB (hanya API data)

Amazon QLDB menyediakan shell baris perintah untuk interaksi dengan API data transaksional. Dengan shell QLDB, Anda dapat menjalankan pernyataan PartiQL pada data buku besar.

Versi terbaru dari shell ini ditulis dalam Rust dan open source di awslabs/ GitHub repositoriamazon-qldb-shell padamain cabang default. Versi Python (v1) juga masih tersedia untuk digunakan dalam repositori yang sama dimaster cabang.

catatan

Shell Amazon QLDB hanya mendukung API dataqldb-session transaksional. API ini hanya digunakan untuk menjalankan pernyataan PartiQL pada buku besar QLDB.

Untuk berinteraksi dengan operasi APIqldb manajemen menggunakan antarmuka baris perintah, lihatMengakses Amazon QLDB menggunakan (hanya API manajemen AWS CLI ).

Alat ini tidak dimaksudkan untuk dimasukkan ke dalam aplikasi atau diadopsi untuk tujuan produksi. Tujuan dari alat ini adalah untuk membiarkan Anda cepat bereksperimen dengan QLDB dan PartiQL.

Bagian berikut menjelaskan cara memulai shell QLDB.

Prasyarat

Sebelum memulai shell QLDB, Anda harus melakukan hal berikut:

1. Ikuti petunjukAWS pengaturan diMengakses Amazon QLDB. Hal ini termasuk skenario berikut:

   1. Daftar ke AWS.

   2. Buat pengguna dengan izin QLDB yang sesuai.

   3. Memberikan akses terprogram untuk pengembangan.

2. SiapkanAWS kredensi dan default AndaWilayah AWS. Untuk petunjuknya, lihat Dasar-dasar konfigurasi di PanduanAWS Command Line Interface Pengguna.

   Untuk daftar lengkap Wilayah yang tersedia, lihat titik akhir dan kuota Amazon QLDB di bagian Referensi Umum AWS.

3. Untuk buku besar apa pun dalam modeSTANDARD izin, buat kebijakan IAM yang memberi Anda izin untuk menjalankan pernyataan PartiQL pada tabel yang sesuai. Untuk mempelajari cara membuat kebijakan ini, lihatMemulai dengan mode izin standar di Amazon QLDB.

Memasang shell

Untuk menginstal versi terbaru dari shell QLDB, lihat file README.md aktif GitHub. QLDB menyediakan file biner bawaan untuk Linux, macOS, dan Windows di bagian Rilis GitHub repositori.

Untuk macOS, shell terintegrasi dengan keranaws/tap Homebrew. Untuk menginstal shell di macOS menggunakan Homebrew, jalankan perintah berikut.

$ xcode-select --install # Required to use Homebrew
$ brew tap aws/tap # Add AWS as a Homebrew tap
$ brew install qldbshell

Konfigurasi

Setelah instalasi, shell memuat file konfigurasi default yang terletak di$XDG_CONFIG_HOME/qldbshell/config.ion selama inisialisasi. Di Linux dan macOS, file ini biasanya berada di~/.config/qldbshell/config.ion. Jika file seperti itu tidak ada, shell berjalan dengan pengaturan default.

Anda dapat membuatconfig.ion file secara manual setelah instalasi. File konfigurasi ini menggunakan format data Amazon Ion. Berikut ini adalah contohconfig.ion file minimal.

{
  default_ledger: "my-example-ledger"
}

Jikadefault_ledger tidak diatur dalam file konfigurasi Anda,--ledger parameter diperlukan saat Anda memanggil shell. Untuk daftar lengkap opsi konfigurasi, lihat file README.md aktif GitHub.

Memanggil shell

Untuk memanggil shell QLDB pada terminal baris perintah Anda untuk buku besar tertentu, jalankan perintah berikut. Ganti my-example-ledgerdengan nama buku besar Anda.

$ qldb --ledger my-example-ledger

Perintah ini terhubung ke default AndaWilayah AWS. Untuk secara eksplisit menentukan Region, Anda dapat menjalankan perintah dengan--qldb-session-endpoint parameter--region or, seperti yang dijelaskan di bagian berikut.

Setelah memohon sesiqldb shell, Anda dapat memasukkan jenis berikut masukan:

• Perintah shell

• Pernyataan PartiQL tunggal dalam transaksi terpisah

• Beberapa pernyataan PartiQL dalam transaksi

Parameter shell

Untuk daftar lengkap bendera dan opsi yang tersedia untuk memohon shell, jalankanqldb perintah dengan--help bendera, sebagai berikut.

$ qldb --help

Berikut ini adalah beberapa bendera kunci dan opsi untukqldb perintah. Anda dapat menambahkan parameter opsional ini untuk menggantiWilayah AWS, profil kredensyal, titik akhir, format hasil, dan opsi konfigurasi lainnya.

Pemakaian

$ qldb [FLAGS] [OPTIONS]

BENDERA

-h, --help

Mencetak informasi bantuan.

-v, --verbose

Mengkonfigurasi verbositas logging. Secara default, shell log kesalahan saja. Untuk meningkatkan tingkat verbositas, ulangi argumen ini (misalnya,-vv). Tingkat tertinggi adalah-vvv yang sesuai dengantrace verbositas.

-V, --version

Mencetak informasi versi.

OPSI

-l,--ledger LEDGER_NAMA

Nama buku besar untuk terhubung. Ini adalah parameter shell yang diperlukan jikadefault_ledger tidak diatur dalamconfig.ion file Anda. Dalam file ini, Anda dapat mengatur opsi tambahan, seperti Wilayah.

-c,--config CONFIG_FILE

File tempat Anda dapat menentukan opsi konfigurasi shell apa pun. Untuk memformat detail dan daftar lengkap opsi konfigurasi, lihat file README.md aktif GitHub.

-f, --format ion|table

Format output dari hasil kueri Anda. Defaultnya adalah ion.

-p,--profile PROFIL

Lokasi profilAWS kredensial Anda untuk autentikasi.

Jika tidak disediakan, shell menggunakanAWS profil default Anda, yang terletak di~/.aws/credentials.

-r,--region KODE WILAYAH

Wilayah AWSKode buku besar QLDB untuk terhubung ke. Misalnya: us-east-1.

Jika tidak disediakan, shell terhubung ke default AndaWilayah AWS seperti yang ditentukan dalamAWS profil Anda.

-s,--qldb-session-endpoint QLDB_SESSION_ENDPOINT

Endpointqldb-session API untuk terhubung ke.

Untuk daftar lengkap Wilayah QLDB dan titik akhir yang tersedia, lihat titik akhir dan kuota Amazon QLDB di bagian Referensi Umum AWS.

Referensi perintah

Setelah Anda memanggilqldb sesi, shell mendukung kunci berikut dan perintah database:

Tombol shell
Key	Deskripsi fungsi
Enter	Menjalankan pernyataan.
Escape+Enter (MacOS, Linux) Shift+Enter (Jendela)	Mulai baris baru untuk memasukkan pernyataan yang mencakup beberapa baris. Anda juga dapat menyalin teks input dengan beberapa baris dan menempelkannya ke dalam shell. Untuk petunjuk tentang pengaturan,Option bukanEscape sebagai kunci Meta di macOS, lihat situs OS X Daily.
Ctrl+C	Membatalkan perintah saat ini.
Ctrl+D	Sinyal akhir file (EOF) dan keluar tingkat shell. Jika tidak dalam transaksi aktif, keluar shell. Dalam transaksi aktif, membatalkan transaksi.

Perintah basis data shell
Perintah	Deskripsi fungsi
help	Menampilkan informasi bantuan.
begin	Memulai transaksi.
start transaction
commit	Melakukan transaksi Anda ke jurnal buku besar.
abort	Menghentikan transaksi Anda dan menolak setiap perubahan yang Anda buat.
exit	Keluar shell.
quit

catatan

Semua perintah shell QLDB tidak peka huruf besar/kecil.

Menjalankan pernyataan individual

Kecuali untuk perintah database dan perintah meta shell yang tercantum dalam README.md, shell menafsirkan setiap perintah yang Anda masukkan sebagai pernyataan PartiQL terpisah. Secara default, shell mengaktifkanauto-commit mode. Mode ini dapat dikonfigurasi.

Dalamauto-commit mode, shell secara implisit menjalankan setiap pernyataan dalam transaksinya sendiri dan secara otomatis melakukan transaksi jika tidak ada kesalahan yang ditemukan. Ini berarti bahwa Anda tidak perlu menjalankanstart transaction (ataubegin) dancommit secara manual setiap kali Anda menjalankan pernyataan.

Mengelola transaksi

Atau, shell QLDB memungkinkan Anda mengontrol transaksi secara manual. Anda dapat menjalankan beberapa pernyataan dalam transaksi secara interaktif, atau non-interaktif dengan mengelompokkan perintah dan pernyataan secara berurutan.

Transaksi interaktif

Untuk menjalankan transaksi interaktif, lakukan langkah-langkah berikut.

1. Untuk memulai transaksi, masukkanbegin perintah.

   qldb> begin

   Setelah Anda memulai transaksi, shell menampilkan prompt perintah berikut.

   qldb *>  

2. Kemudian, setiap pernyataan yang Anda masukkan berjalan dalam transaksi yang sama.

   • Misalnya, Anda dapat menjalankan pernyataan tunggal sebagai berikut.

     qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'

     Setelah Anda menekanEnter, shell menampilkan hasil pernyataan.

   • Anda juga dapat memasukkan beberapa pernyataan atau perintah dipisahkan oleh titik koma (;) pembatas sebagai berikut.

     qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; commit

3. Untuk mengakhiri transaksi, masukkan salah satu perintah berikut.

   • Masukkancommit perintah untuk melakukan transaksi Anda ke jurnal buku besar.

     qldb *> commit

   • Masukkanabort perintah untuk menghentikan transaksi Anda dan menolak perubahan yang Anda buat.

     qldb *> abort
     transaction was aborted

Batas batas waktu transaksi

Transaksi interaktif mematuhi batas waktu transaksi QLDB. Jika Anda tidak melakukan transaksi dalam waktu 30 detik sejak memulainya, QLDB secara otomatis akan kedaluwarsa transaksi dan menolak setiap perubahan yang dilakukan selama transaksi.

Kemudian, alih-alih menampilkan hasil pernyataan, shell menampilkan pesan kesalahan kedaluwarsa dan kembali ke prompt perintah normal. Untuk mencoba lagi, Anda harus memasukkanbegin perintah lagi untuk memulai transaksi baru.

transaction failed after 1 attempts, last error: communication failure: Transaction 2UMpiJ5hh7WLjVgEiMLOoO has expired

Transaksi non-interaktif

Anda dapat menjalankan transaksi lengkap dengan beberapa pernyataan dengan mengelompokkan perintah dan pernyataan secara berurutan sebagai berikut.

qldb> begin; SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; SELECT * FROM Person p, DriversLicense l WHERE p.GovId = l.LicenseNumber; commit

Anda harus memisahkan setiap perintah dan pernyataan dengan titik koma (;) pembatas. Jika ada pernyataan dalam transaksi yang tidak valid, shell secara otomatis menolak transaksi. Shell tidak melanjutkan dengan pernyataan berikutnya yang Anda masukkan.

Anda juga dapat mengatur beberapa transaksi.

qldb> begin; statement1; commit; begin; statement2; statement3; commit

Mirip dengan contoh sebelumnya, jika transaksi gagal, shell tidak melanjutkan transaksi atau pernyataan berikutnya yang Anda masukkan.

Jika Anda tidak mengakhiri transaksi, shell beralih ke mode interaktif dan meminta Anda untuk perintah atau pernyataan berikutnya.

qldb> begin; statement1; commit; begin
qldb *>  

Keluar shell

Untuk keluar dari sesiqldb shell saat ini, masukkanquit perintahexit atau, atau gunakan pintasan keyboardCtrl +D saat shell tidak dalam transaksi.

qldb> exit
$ 

qldb> quit
$ 

Contoh

Untuk informasi tentang menulis pernyataan PartiQL di QLDB, lihatReferensi PartiQLDB QLDB.

Contoh berikut menunjukkan urutan perintah dasar.

catatan

Shell QLDB menjalankan setiap pernyataan PartiQL dalam contoh ini dalam transaksi sendiri.

Contoh ini mengasumsikan bahwa buku besartest-ledger sudah ada dan aktif.

$ 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