Acceso a Amazon QLDB mediante el shell de QLDB (solo API de datos) - Amazon Quantum Ledger Database (Amazon QLDB)

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Acceso a Amazon QLDB mediante el shell de QLDB (solo API de datos)

Amazon QLDB proporciona un shell de línea de comandos para interactuar con la API de datos transaccionales. Con el shell QLDB, puede ejecutarPartiQLestados de cuenta sobre los datos del libro mayor.

La última versión de este shell está escrita en Rust y es de código abierto en el repositorio de GitHubawslabs/amazon-qldb-shellen el valor predeterminadomainramificación. La versión de Python (v1) también está disponible para su uso en el mismo repositorio delmasterramificación.

nota

El shell de Amazon QLDB solo admite elqldb-sessionAPI de datos transaccionales. Esta API se utiliza solo para ejecutar sentencias partiQL en un libro mayor de QLDB.

Para interactuar con laqldboperaciones de API de administración mediante una interfaz de línea de comandos, consulteAcceso a Amazon QLDB medianteAWS CLI(solo API de administración).

Esta herramienta no está diseñada para incorporarse a una aplicación ni adoptarse con fines de producción. El objetivo de esta herramienta es permitirle experimentar rápidamente con QLDB y PartiQL.

En las siguientes secciones se describe cómo empezar a utilizar el shell de QLDB.

Requisitos previos

Antes de comenzar a utilizar el shell de QLDB, debe hacer lo siguiente:

  1. Seguimiento deAWSinstrucciones de configuración enAcceso a Amazon QLDB. Estas incluyen las siguientes:

    1. Registrarse enAWS.

    2. Creación de unAWS Identity and Access Management(IAM) con los permisos QLDB adecuados.

    3. Obtenga una clave de acceso de IAM para el desarrollo.

  2. Configurar elAWScredenciales y su valor predeterminadoAWSRegión . Para obtener instrucciones, consulteFundamentos de configuraciónen laAWS Command Line InterfaceGuía del usuario de.

    Para obtener una lista completa de regiones disponibles, consulteCuotas y puntos de enlace de Amazon QLDBen laAWSReferencia general de.

  3. Para cualquier libro mayor delSTANDARDmodo permisos, cree políticas de IAM que le otorguen permisos para ejecutar sentencias PartiQL en las tablas apropiadas. Para obtener información sobre cómo crear estas políticas de, consulteIntroducción al modo de permisos estándar en Amazon QLDB.

Instalación del shell

Para instalar la versión más reciente del shell de QLDB, consulte laLéame.mdarchivo en GitHub. QLDB proporciona archivos binarios precompilados para Linux, macOS y Windows en elVersiones deSección sobre de la GitHub .

Para macOS, el shell se integra con elaws/tap HomebrewPulse. Para instalar el shell en macOS mediante Homebrew, ejecute los siguientes comandos.

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

Configuración

Tras la instalación, el shell carga el archivo de configuración predeterminado que se encuentra en$XDG_CONFIG_HOME/qldbshell/config.iondurante la inicialización. En Linux y macOS, este archivo se encuentra normalmente en~/.config/qldbshell/config.ion. Si dicho archivo no existe, el shell se ejecuta con la configuración predeterminada.

Puede crear unconfig.ionarchivo manualmente después de la instalación. Este archivo de configuración utiliza elAmazon Ionformato de datos. A continuación se muestra un ejemplo de un mínimoconfig.ionfile.

{ default_ledger: "my-example-ledger" }

Sidefault_ledgerno está configurado en el archivo de configuración, el--ledgeres necesario al invocar el shell. Para ver una lista completa de opciones de configuración, consulte laLéame.mdarchivo en GitHub.

Invocación del shell

Para invocar el shell QLDB en el terminal de línea de comandos para un libro mayor específico, ejecute el siguiente comando. Reemplazarmi-ejemplo-ledgercon el nombre de su libro mayor.

$ qldb --ledger my-example-ledger

Este comando se conecta a la configuración predeterminadaAWSRegión . Para especificar explícitamente la región, puede ejecutar el comando con la--regiono--qldb-session-endpoint, tal y como se describe en la siguiente sección.

Tras invocar unqldbsesión de shell, puede introducir los siguientes tipos de entrada:

Parámetros del shell

Para obtener una lista completa de los indicadores disponibles y las opciones para invocar un shell, ejecute laqldbcomando con el--helpbandera, según se indica a continuación.

$ qldb --help

A continuación, se muestran algunos indicadores y opciones clave para elqldbcomando. Puede añadir estos parámetros opcionales para anular laAWSRegión, perfil de credenciales, punto final, formato de resultados y otras opciones de configuración.

Uso

$ qldb [FLAGS] [OPTIONS]

MARCADORES

-h, --help

Imprime información de ayuda.

-v, --verbose

Configura la verbosidad del registro. De forma predeterminada, el shell registra solo los errores. Para aumentar el nivel de verbosidad, repita este argumento (por ejemplo,-vv). El nivel más alto es-vvvque corresponde contracedetalle.

-V, --version

Imprime información de versión.

OPTIONS

-l,--ledger LEDGER_NAME

Nombre del libro mayor al que desea conectarse. Este es un parámetro de shell obligatorio sidefault_ledgerno está configurado en tuconfig.ionfile. En este archivo, puede configurar opciones adicionales, como la región.

-c,--config CONFIG_FILE

El archivo en el que puede definir cualquier opción de configuración de shell. Para obtener detalles de formato y una lista completa de las opciones de configuración de, consulte laLéame.mdarchivo en GitHub.

-f, --format ion|table

Formato de salida de los resultados de la consulta. El valor predeterminado es ion.

-p,--profile PERFIL DE

Ubicación deAWSPerfil de credenciales que se va a utilizar para la autenticación.

Si no se proporciona, el shell utiliza el valor predeterminadoAWSperfil, que se encuentra en~/.aws/credentials.

-r,--region REGION_CODE

LaAWSCódigo de región del libro mayor QLDB al que se va a conectar. Por ejemplo: us-east-1.

Si no se proporciona, el shell se conecta a la configuración predeterminadaAWSRegión tal como se especifica en suAWSperfil.

-s,--qldb-session-endpoint QLDB_SESSION_ENDPOINT

Laqldb-sessionPunto de enlace de API al que desea conectarse.

Para obtener una lista completa de las regiones y los puntos de enlace de QLDB disponibles, consulteCuotas y puntos de enlace de Amazon QLDBen laAWSReferencia general de.

Referencia de comandos

Después de invocar unqldbsession, el shell admite las siguientes claves y comandos de base de datos:

Teclas del shell
Clave Descripción de la función
Enter Ejecuta la declaración.

Escape+Enter(macOS, Linux)

Shift+Enter(Windows)

Inicia una nueva línea para introducir una sentencia que abarca varias líneas. También puede copiar el texto de entrada con varias líneas y pegarlo en el shell.

Para obtener instrucciones acerca de cómo configurarOptionen lugar deEscapecomo clave meta en macOS, consulte laOS X Diariamentesitio:.

Ctrl+C Cancela el comando actual.
Ctrl+D Señala el fin del archivo y sale del nivel actual del shell. Si no se encuentra en una transacción activa, sale del shell. En una transacción activa, anula la transacción.
Comandos base de datos
Comando Descripción de la función
help Muestra la información de ayuda.
begin Inicia una transacción.
start transaction
commit Confirma la transacción en el diario del libro mayor.
abort Detiene la transacción y rechaza los cambios que ha realizado.
exit Sale de la carcasa.
quit
nota

Todos los comandos del shell de QLDB no distinguen entre mayúsculas y min

Ejecución de declaraciones individuales

Excepto los comandos de base de datos y los meta comandos de shell enumerados enLéame.md, el shell interpreta cada comando que introduzca como una instrucción PartiQL independiente. De forma predeterminada, el shell habilitaauto-commitmodo. Este modo se puede configurar.

En el navegadorauto-commit, el shell ejecuta implícitamente cada declaración en su propia transacción y la confirma automáticamente si no se encuentra ningún error. Esto quiere decir que no tiene que correr.start transaction(obegin) ycommitmanualmente cada vez que ejecuta una sentencia.

Administración de transacciones

Alternativamente, el shell QLDB le permite controlar manualmente las transacciones. Puede ejecutar varias sentencias dentro de una transacción de forma interactiva o no interactiva mediante la agrupación de comandos y sentencias secuencialmente.

Operaciones interactivas

Para ejecutar una transacción interactiva, siga los pasos que se indican a continuación.

  1. Para iniciar una transacción, introduzca labegincomando.

    qldb> begin

    Después de iniciar una transacción, el shell muestra el siguiente símbolo del sistema.

    qldb *>
  2. A continuación, cada declaración que introduzca se ejecuta en la misma transacción.

    • Por ejemplo, puede ejecutar una sola instrucción de la siguiente manera.

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

      Después de pulsarEnter, el shell muestra los resultados de la instrucción.

    • También puede introducir varias sentencias o comandos separados por un punto y coma (;) delimitador de la siguiente manera.

      qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; commit
  3. Para finalizar la transacción, ingrese uno de los siguientes comandos.

    • Escriba lacommitpara confirmar la transacción en el diario del libro mayor.

      qldb *> commit
    • Escriba laabortpara detener la transacción y rechazar los cambios que ha realizado.

      qldb *> abort transaction was aborted

Límite de timeout de transacciones

Una transacción interactiva se adhiere a laslímite de tiempo de espera de transacciones. Si no confirma una transacción dentro30 segundosde iniciarlo, QLDB caduca automáticamente la transacción y rechaza cualquier cambio realizado durante la transacción.

A continuación, en lugar de mostrar los resultados de la instrucción, el shell muestra un mensaje de error de caducidad y vuelve al símbolo del sistema normal. Para volver a intentarlo, debe introducir elbeginde nuevo para iniciar una nueva transacción.

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

Transacciones no interactivas

Puede ejecutar una transacción completa con varias sentencias mediante la agrupación de comandos y sentencias secuencialmente de la siguiente manera.

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

Debe separar cada comando y sentencia con un punto y coma (;) Delimitador. Si alguna declaración de la transacción no es válida, el shell rechaza automáticamente la transacción. El shell no procede con ninguna instrucción posterior que haya introducido.

También puede configurar varias transacciones.

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

Al igual que en el ejemplo anterior, si falla una transacción, el shell no procede con ninguna transacción o extracto posterior que haya introducido.

Si no finaliza una transacción, el shell cambia al modo interactivo y le solicita el siguiente comando o instrucción.

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

Salida del shell

Para salir del actualqldbsesión de shell, introduzca laexitoquito utilice el método abreviado de tecladoCtrl+Dcuando el shell no está en una transacción.

qldb> exit $
qldb> quit $

Ejemplo

Para obtener información sobre cómo escribir declaraciones de PartiQL en QLDB, consulte laReferencia de Amazon QLDB PartiQL.

En el siguiente ejemplo se muestra una secuencia común de comandos básicos.

nota

El shell QLDB ejecuta cada instrucción PartiQL de este ejemplo en su propia transacción.

Este ejemplo asume que el libro mayortest-ledgerya existe y está activo.

$ 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