Accesso ad Amazon QLDB tramite QLDB shell (APIsolo dati)

Importante

Avviso di fine del supporto: i clienti esistenti potranno utilizzare Amazon QLDB fino alla fine del supporto il 31/07/2025. Per ulteriori dettagli, consulta Migrare un Amazon QLDB Ledger ad Amazon Aurora Postgre. SQL

Amazon QLDB fornisce una shell a riga di comando per l'interazione con i dati transazionali. API Con la QLDB shell, puoi eseguire istruzioni PartiQL sui dati del registro.

L'ultima versione di questa shell è scritta in Rust ed è open source nel GitHub repository amazon-qldb-shellawslabs/ nel ramo predefinito. main La versione Python (v1) è inoltre ancora disponibile per l'uso nello stesso repository sul ramo. master

Nota

La QLDB shell Amazon supporta solo i dati qldb-session transazionali. API APIViene utilizzato solo per eseguire istruzioni PartiQL su un QLDB registro.

Per interagire con le API operazioni di qldb gestione utilizzando un'interfaccia a riga di comando, vedere. Accesso ad Amazon QLDB tramite AWS CLI (APIsolo gestione)

Questo strumento non è pensato per essere incorporato in un'applicazione o adottato per scopi di produzione. L'obiettivo di questo strumento è quello di consentirti di sperimentare rapidamente con QLDB PartiQL.

Le sezioni seguenti descrivono come iniziare a usare la QLDB shell.

Prerequisiti

Prima di iniziare con la QLDB shell, devi fare quanto segue:

1. Segui le istruzioni AWS di configurazione riportate inAccesso ad Amazon QLDB. Questo include gli output seguenti:

   1. Iscriviti a AWS.

   2. Crea un utente con le QLDB autorizzazioni appropriate.

   3. Concedi l'accesso programmatico per lo sviluppo.

2. Imposta AWS le tue credenziali e le impostazioni predefinite. Regione AWS Per istruzioni, consulta Nozioni di base sulla configurazione nella Guida per l'AWS Command Line Interface utente.

   Per un elenco completo delle regioni disponibili, consulta gli QLDBendpoint e le quote di Amazon nel. Riferimenti generali di AWS

3. Per tutti i registri in modalità STANDARD autorizzazioni, crea IAM politiche che ti concedano le autorizzazioni per eseguire istruzioni PartiQL nelle tabelle appropriate. Per informazioni su come creare queste politiche, consulta. Guida introduttiva alla modalità di autorizzazione standard in Amazon QLDB

Installazione della shell

Per installare l'ultima versione della QLDB shell, consultate il READMEfile.md su GitHub. QLDBfornisce file binari predefiniti per Linux, macOS e Windows nella sezione Releases del repository. GitHub

Per macOS, la shell si integra con il tap Homebrew. aws/tap Per installare la shell su macOS usando Homebrew, esegui i seguenti comandi.

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

Configurazione

Dopo l'installazione, la shell carica il file di configurazione predefinito che si trova in $XDG_CONFIG_HOME/qldbshell/config.ion fase di inizializzazione. Su Linux e macOS, questo file si trova in genere in. ~/.config/qldbshell/config.ion Se tale file non esiste, la shell viene eseguita con le impostazioni predefinite.

È possibile creare un config.ion file manualmente dopo l'installazione. Questo file di configurazione utilizza il formato dati Amazon Ion. Di seguito è riportato un esempio di config.ion file minimo.

{
  default_ledger: "my-example-ledger"
}

Se default_ledger non è impostato nel file di configurazione, il --ledger parametro è obbligatorio quando si richiama la shell. Per un elenco completo delle opzioni di configurazione, consultate il READMEfile.md su. GitHub

Invocare la shell

Per richiamare la QLDB shell sul terminale a riga di comando per un registro specifico, esegui il comando seguente. Replace (Sostituisci) my-example-ledger con il nome del tuo libro mastro.

$ qldb --ledger my-example-ledger

Questo comando si connette all'impostazione predefinita Regione AWS. Per specificare in modo esplicito la regione, è possibile eseguire il comando con il --qldb-session-endpoint parametro --region or, come descritto nella sezione seguente.

Dopo aver richiamato una sessione di qldb shell, potete inserire i seguenti tipi di input:

• Comandi della shell

• Istruzioni PartiQL singole in transazioni separate

• Più istruzioni PartiQL all'interno di una transazione

Parametri della shell

Per un elenco completo dei flag e delle opzioni disponibili per invocare una shell, esegui il qldb comando con il --help flag, come segue.

$ qldb --help

Di seguito sono riportati alcuni flag e opzioni chiave per il comando. qldb È possibile aggiungere questi parametri opzionali per sovrascrivere il profilo delle credenziali Regione AWS, l'endpoint, il formato dei risultati e altre opzioni di configurazione.

Utilizzo

$ qldb [FLAGS] [OPTIONS]

FLAGS

-h, --help

Stampa le informazioni di aiuto.

-v, --verbose

Configura la verbosità della registrazione. Per impostazione predefinita, la shell registra solo gli errori. Per aumentare il livello di dettaglio, ripetete questo argomento (ad esempio,). -vv Il livello più alto è quello -vvv che corrisponde alla verbosità. trace

-V, --version

Stampa le informazioni sulla versione.

OPTIONS

-l, --ledger LEDGER_NAME

Il nome del registro a cui connettersi. Questo è un parametro di shell obbligatorio se default_ledger non è impostato nel config.ion file. In questo file, puoi impostare opzioni aggiuntive, come la regione.

-c, --config CONFIG_FILE

Il file in cui è possibile definire qualsiasi opzione di configurazione della shell. Per i dettagli sulla formattazione e un elenco completo delle opzioni di configurazione, consultate il READMEfile.md su. GitHub

-f, --format ion|table

Il formato di output dei risultati della query. Il valore predefinito è ion.

-p, --profile PROFILE

La posizione del profilo delle AWS credenziali da utilizzare per l'autenticazione.

Se non viene fornito, la shell utilizza il AWS profilo predefinito, che si trova in~/.aws/credentials.

-r, --region REGION_CODE

Il Regione AWS codice del QLDB libro mastro a cui connettersi. Ad esempio: us-east-1.

Se non viene fornito, la shell si connette all'impostazione predefinita Regione AWS , come specificato nel AWS profilo.

-s, --qldb-session-endpoint QLDB_SESSION_ENDPOINT

L'qldb-sessionAPIendpoint a cui connettersi.

Per un elenco completo delle QLDB regioni e degli endpoint disponibili, consulta gli QLDBendpoint e le quote di Amazon nel. Riferimenti generali di AWS

Riferimento ai comandi

Dopo aver richiamato una qldb sessione, la shell supporta le seguenti chiavi e comandi di database:

Chiavi Shell
Chiave	Descrizione della funzione
Enter	Esegue l'istruzione.
Escape+ Enter (macOS, Linux) Shift+ Enter (Windows)	Inizia una nuova riga per inserire un'istruzione che si estende su più righe. Puoi anche copiare il testo di input con più righe e incollarlo nella shell. Per istruzioni sulla configurazione Option anziché Escape come chiave Meta in macOS, consulta il sito OS X Daily.
Ctrl+C	Annulla il comando corrente.
Ctrl+D	Segnala la fine del file (EOF) ed esce dal livello corrente della shell. Se non è in una transazione attiva, esce dalla shell. In una transazione attiva, interrompe la transazione.

Comandi del database Shell
Comando	Descrizione della funzione
help	Visualizza le informazioni di aiuto.
begin	Inizia una transazione.
start transaction
commit	Salva la transazione nel giornale di registrazione del libro mastro.
abort	Interrompe la transazione e rifiuta tutte le modifiche apportate.
exit	Esce dalla shell.
quit

Nota

Tutti i comandi della QLDB shell non fanno differenza tra maiuscole e minuscole.

Esecuzione di istruzioni individuali

Ad eccezione dei comandi di database e dei meta comandi della shell elencati in README.md, la shell interpreta ogni comando immesso come un'istruzione PartiQL separata. Per impostazione predefinita, la shell abilita la modalità. auto-commit Questa modalità è configurabile.

In questa auto-commit modalità, la shell esegue implicitamente ogni istruzione nella propria transazione e commette automaticamente la transazione se non vengono rilevati errori. Ciò significa che non è necessario eseguire start transaction (obegin) e commit manualmente ogni volta che si esegue un'istruzione.

Gestione delle transazioni

In alternativa, la QLDB shell consente di controllare manualmente le transazioni. È possibile eseguire più istruzioni all'interno di una transazione in modo interattivo o non interattivo raggruppando in batch comandi e istruzioni in sequenza.

Transazioni interattive

Per eseguire una transazione interattiva, procedi nel seguente modo.

1. Per iniziare una transazione, inserisci il begin comando.

   qldb> begin

   Dopo aver iniziato una transazione, la shell visualizza il seguente prompt dei comandi.

   qldb *>  

2. Quindi, ogni istruzione inserita viene eseguita nella stessa transazione.

   • Ad esempio, è possibile eseguire una singola istruzione nel modo seguente.

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

     Dopo aver premutoEnter, la shell visualizza i risultati dell'istruzione.

   • Potete anche inserire più istruzioni o comandi separati da un delimitatore di punto e virgola (;) come segue.

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

3. Per terminare la transazione, immettete uno dei seguenti comandi.

   • Immettete il commit comando per salvare la transazione nel giornale di registrazione del libro mastro.

     qldb *> commit

   • Inserisci il abort comando per interrompere la transazione e rifiutare le modifiche apportate.

     qldb *> abort
     transaction was aborted

Limite di timeout della transazione

Una transazione interattiva rispetta il limite di timeout QLDB della transazione. Se non esegui una transazione entro 30 secondi dall'avvio, la transazione scade QLDB automaticamente e rifiuta qualsiasi modifica apportata durante la transazione.

Quindi, invece di visualizzare i risultati dell'istruzione, la shell visualizza un messaggio di errore di scadenza e torna al normale prompt dei comandi. Per riprovare, è necessario immettere nuovamente il begin comando per iniziare una nuova transazione.

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

Transazioni non interattive

È possibile eseguire una transazione completa con più istruzioni raggruppando in batch i comandi e le istruzioni in sequenza come segue.

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

È necessario separare ogni comando e istruzione con un delimitatore di punto e virgola (). ; Se un'istruzione nella transazione non è valida, la shell rifiuta automaticamente la transazione. La shell non procede con le istruzioni successive che hai inserito.

Puoi anche impostare più transazioni.

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

Analogamente all'esempio precedente, se una transazione fallisce, la shell non procede con le transazioni o le dichiarazioni successive che hai inserito.

Se non terminate una transazione, la shell passa alla modalità interattiva e richiede il comando o l'istruzione successiva.

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

Uscire dalla shell

Per uscire dalla sessione di qldb shell corrente, inserite il quit comando exit or o usate la scorciatoia da tastiera Ctrl + D quando la shell non è coinvolta in una transazione.

qldb> exit
$ 

qldb> quit
$ 

Esempio

Per informazioni sulla scrittura di istruzioni PartiQLQLDB, vedere. Riferimento Amazon QLDB PartiQL

L'esempio seguente mostra una sequenza comune di comandi di base.

Nota

La QLDB shell esegue ogni istruzione PartiQL in questo esempio nella propria transazione.

Questo esempio presuppone che il registro esista test-ledger già e sia attivo.

$ 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