Accès à Amazon QLDB via le QLDB shell (données API uniquement)

Amazon QLDB fournit un shell de ligne de commande pour interagir avec les données API transactionnelles. Avec le QLDB shell, vous pouvez exécuter des instructions partiQL sur des données de registre.

La dernière version de ce shell est écrite en Rust et est open source dans le GitHub dépôt awslabs/ amazon-qldb-shell sur la branche par défaut. main La version Python (v1) est également toujours disponible pour une utilisation dans le même dépôt de la master branche.

Cet outil n'est pas destiné à être intégré à une application ou adopté à des fins de production. L'objectif de cet outil est de vous permettre d'expérimenter rapidement QLDB et partiQL.

Les sections suivantes décrivent comment démarrer avec le QLDB shell.

Prérequis

Avant de commencer à utiliser le QLDB shell, vous devez effectuer les opérations suivantes :

Installation de la coque

Pour installer la dernière version du QLDB shell, consultez le fichier README.md sur GitHub. QLDBfournit des fichiers binaires prédéfinis pour Linux, macOS et Windows dans la section Releases du GitHub référentiel.

Pour macOS, le shell s'intègre au robinet aws/tap Homebrew. Pour installer le shell sur macOS à l'aide de Homebrew, exécutez les commandes suivantes.

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

Configuration

Après l'installation, le shell charge le fichier de configuration par défaut qui se trouve $XDG_CONFIG_HOME/qldbshell/config.ion lors de l'initialisation. Sous Linux et macOS, ce fichier se trouve généralement à l'adresse~/.config/qldbshell/config.ion. Si un tel fichier n'existe pas, le shell s'exécute avec les paramètres par défaut.

Vous pouvez créer un config.ion fichier manuellement après l'installation. Ce fichier de configuration utilise le format de données Amazon Ion. Voici un exemple de config.ion fichier minimal.

{
  default_ledger: "my-example-ledger"
}

S'il default_ledger n'est pas défini dans votre fichier de configuration, le --ledger paramètre est obligatoire lorsque vous appelez le shell. Pour obtenir la liste complète des options de configuration, consultez le fichier README.md sur GitHub.

Invoquer le shell

Pour appeler le QLDB shell sur votre terminal de ligne de commande pour un registre spécifique, exécutez la commande suivante. Remplacez my-example-ledger avec le nom de votre registre.

$ qldb --ledger my-example-ledger

Cette commande se connecte à votre commande par défaut Région AWS. Pour spécifier explicitement la région, vous pouvez exécuter la commande avec le --qldb-session-endpoint paramètre --region ou, comme décrit dans la section suivante.

Après avoir appelé une session qldb shell, vous pouvez saisir les types de saisie suivants :

Paramètres de la coque

Pour obtenir la liste complète des indicateurs et options disponibles pour appeler un shell, exécutez la qldb commande avec l'--helpindicateur, comme suit.

$ qldb --help

Voici quelques indicateurs clés et options de la qldb commande. Vous pouvez ajouter ces paramètres facultatifs pour remplacer le profil d'identification Région AWS, le point de terminaison, le format des résultats et les autres options de configuration.

Utilisation

$ qldb [FLAGS] [OPTIONS]

Référence de commande

Une fois que vous avez appelé une qldb session, le shell prend en charge les touches et commandes de base de données suivantes :

Exécution de relevés individuels

À l'exception des commandes de base de données et des méta-commandes du shell répertoriées dans le READMEfichier .md, le shell interprète chaque commande que vous entrez comme une instruction partiQL distincte. Par défaut, le shell active le auto-commit mode. Ce mode est configurable.

Dans ce auto-commit mode, le shell exécute implicitement chaque instruction dans sa propre transaction et valide automatiquement la transaction si aucune erreur n'est détectée. Cela signifie que vous n'avez pas à exécuter start transaction (oubegin) commit manuellement chaque fois que vous exécutez une instruction.

Gestion des transactions

Le QLDB shell vous permet également de contrôler manuellement les transactions. Vous pouvez exécuter plusieurs instructions au sein d'une transaction de manière interactive ou non interactive en regroupant les commandes et les instructions de manière séquentielle.

Transactions interactives

Pour exécuter une transaction interactive, procédez comme suit.

Délai d'expiration des transactions

Une transaction interactive respecte le délai d'expiration QLDB de la transaction. Si vous ne validez pas une transaction dans les 30 secondes suivant son lancement, elle fait QLDB automatiquement expirer la transaction et rejette toute modification apportée au cours de la transaction.

Ensuite, au lieu d'afficher les résultats de l'instruction, le shell affiche un message d'erreur d'expiration et revient à l'invite de commande normale. Pour réessayer, vous devez saisir à nouveau la begin commande pour commencer une nouvelle transaction.

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

Transactions non interactives

Vous pouvez exécuter une transaction complète avec plusieurs instructions en groupant les commandes et les instructions de manière séquentielle comme suit.

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

Vous devez séparer chaque commande et chaque instruction par un point-virgule ();. Si l'une des instructions de la transaction n'est pas valide, le shell rejette automatiquement la transaction. Le shell ne procède à aucune instruction que vous avez saisie ultérieurement.

Vous pouvez également configurer plusieurs transactions.

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

Comme dans l'exemple précédent, si une transaction échoue, le shell ne procède à aucune transaction ou instruction ultérieure que vous avez saisie.

Si vous ne mettez pas fin à une transaction, le shell passe en mode interactif et vous invite à saisir la commande ou l'instruction suivante.

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

Sortir de la coque

Pour quitter la session qldb shell en cours, entrez la quit commande exit ou, ou utilisez le raccourci-clavier Ctrl + D lorsque le shell n'est pas dans une transaction.

qldb> exit
$ 

qldb> quit
$ 

Exemple

Pour plus d'informations sur l'écriture d'instructions partiQL dansQLDB, consultez le. Référence Amazon QLDB PartiQL

$ 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