Acceso a Amazon QLDB mediante el QLDB shell (APIsolo datos)

importante

Aviso de fin de soporte: los clientes actuales podrán usar Amazon QLDB hasta que finalice el soporte, el 31 de julio de 2025. Para obtener más información, consulte Migración de un Amazon QLDB Ledger a Amazon Aurora SQL Postgre.

Amazon QLDB proporciona un shell de línea de comandos para interactuar con los datos API transaccionales. Con el QLDB shell, puede ejecutar sentencias PartiQL en datos del libro mayor.

La última versión de este shell está escrita en Rust y es de código abierto en el GitHub repositorio awslabs/ amazon-qldb-shell de la rama predeterminada. main La versión de Python (v1) también está disponible para su uso en el mismo repositorio de la rama master.

nota

El QLDB shell de Amazon solo admite los datos qldb-session API transaccionales. Esto API se usa solo para ejecutar declaraciones PartiQL en un QLDB libro mayor.

Para interactuar con las API operaciones qldb de administración mediante una interfaz de línea de comandos, consulte. Acceder a Amazon QLDB mediante AWS CLI (APIsolo la administración)

Esta herramienta no está destinada a incorporarse a una aplicación ni a adoptarse con fines de producción. El objetivo de esta herramienta es permitirte experimentar rápidamente con QLDB PartiQL.

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

Requisitos previos

Antes de empezar con el QLDB shell, debe hacer lo siguiente:

1. Siga las instrucciones de AWS configuración que se indican enAcceder a Amazon QLDB. Esta incluye lo siguiente:

   1. Inscríbase en AWS.

   2. Cree un usuario con los QLDB permisos adecuados.

   3. Conceda acceso programático de desarrollo.

2. Configure sus AWS credenciales y las predeterminadas Región de AWS. Para obtener instrucciones, consulte Configuración rápida en la Guía del usuario de AWS Command Line Interface .

   Para obtener una lista completa de las regiones disponibles, consulta los QLDBpuntos de conexión y las cuotas de Amazon en. Referencia general de AWS

3. Para cualquier libro mayor en el modo de STANDARD permisos, crea IAM políticas que te concedan permisos para ejecutar sentencias PartiQL en las tablas correspondientes. Para obtener información sobre cómo crear estas políticas, consulte Cómo empezar con el modo de permisos estándar en Amazon QLDB.

Instalación del intérprete de comandos

Para instalar la versión más reciente del QLDB shell, consulte el READMEarchivo.md en. GitHub QLDBproporciona archivos binarios prediseñados para Linux, macOS y Windows en la sección de versiones del GitHub repositorio.

Para macOS, el intérprete de comandos se integra con el tap de Homebrew aws/tap. Para instalar el intérprete de comandos en macOS con 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 intérprete de comandos carga el archivo de configuración predeterminado que se encuentra en $XDG_CONFIG_HOME/qldbshell/config.ion durante la inicialización. En Linux y macOS, este archivo suele aparecer como ~/.config/qldbshell/config.ion. Si dicho archivo no existe, el intérprete de comandos se ejecuta con la configuración predeterminada.

Puede crear un archivo config.ion manualmente después de la instalación. Este archivo de configuración utiliza el formato de datos de Amazon Ion. A continuación se presenta un ejemplo de un archivo config.ion.

{
  default_ledger: "my-example-ledger"
}

Si default_ledger no está establecido en el archivo de configuración, el parámetro --ledger es obligatorio para invocar el intérprete de comandos. Para obtener una lista completa de las opciones de configuración, consulte el READMEarchivo.md en. GitHub

Invocar el intérprete de comandos

Para invocar el QLDB shell en su terminal de línea de comandos para un libro mayor específico, ejecute el siguiente comando. Reemplazar my-example-ledger con el nombre de tu libro mayor.

$ qldb --ledger my-example-ledger

Este comando se conecta a su configuración predeterminada Región de AWS. Para especificar la región de forma explícita, puede ejecutar el comando con el parámetro --region o --qldb-session-endpoint, tal y como se describe en la siguiente sección.

Tras invocar una sesión de intérprete de comandos qldb, puede introducir los siguientes tipos de entrada:

• Comandos de intérprete de comandos

• Instrucciones PartiQL únicas en transacciones separadas

• Instrucciones PartiQL múltiples dentro de una transacción

Parámetros de intérprete de comandos

Para obtener una lista completa de los marcadores y opciones disponibles para invocar un intérprete de comandos, ejecute el comando qldb con el indicador --help, de la siguiente manera.

$ qldb --help

A continuación se enumeran opciones y marcadores clave del comando qldb. Puede añadir estos parámetros opcionales para anular las credenciales Región de AWS, el perfil, el punto final, el formato de los resultados y otras opciones de configuración.

Uso

$ qldb [FLAGS] [OPTIONS]

FLAGS

-h, --help

Imprime información de ayuda.

-v, --verbose

Configura el nivel de detalle del registro. De forma predeterminada, el intérprete de comandos solo registra los errores. Para aumentar el nivel de detalle, repita este argumento (por ejemplo, -vv). El nivel más alto es -vvv, que corresponde al nivel de detalle trace.

-V, --version

Imprime la información de la versión.

OPTIONS

-l, --ledger LEDGER_NAME

Nombre del libro mayor al que se va a conectar. Se trata de un parámetro de intérprete de comandos obligatorio si default_ledger no está establecido en el archivo config.ion. 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 intérprete de comandos. Para obtener detalles sobre el formato y una lista completa de las opciones de configuración, consulte el READMEarchivo.md en. GitHub

-f, --format ion|table

El formato de salida de los resultados de su consulta. El valor predeterminado es ion.

-p, --profile PROFILE

La ubicación del perfil de AWS credenciales que se utilizará para la autenticación.

Si no se proporciona, el shell utilizará su AWS perfil predeterminado, que se encuentra en~/.aws/credentials.

-r, --region REGION_CODE

El Región de AWS código del QLDB libro mayor al que conectarse. Por ejemplo: us-east-1.

Si no se proporciona, el shell se conecta a su configuración predeterminada, tal y Región de AWS como se especifica en su AWS perfil.

-s, --qldb-session-endpoint QLDB_SESSION_ENDPOINT

El qldb-session API punto final al que conectarse.

Para obtener una lista completa de QLDB las regiones y puntos de enlace disponibles, consulte los puntos de QLDBenlace y las cuotas de Amazon en. Referencia general de AWS

Referencia de los comandos

Tras invocar una sesión qldb, el intérprete de comandos admite las siguientes claves y comandos de base de datos:

Claves de intérprete de comandos
Clave	Descripción de función
Enter	Ejecute la instrucción.
Escape+Enter (macOS, Linux) Shift+Enter (Windows)	Inicia una nueva línea para introducir una instrucción que abarque varias líneas. También puede copiar el texto introducido con varias líneas y pegarlo en el intérprete de comandos. Para obtener instrucciones sobre cómo configurar Option en lugar de Escape como una clave meta en macOS, consulte el sitio de OS X Daily.
Ctrl+C	Cancela el comando actual.
Ctrl+D	Señala el final del archivo (EOF) y sale del nivel actual del shell. Si no está en una transacción activa, sale del intérprete de comandos. En una transacción activa, anula la transacción.

Comandos de la base de datos del intérprete de comandos
Comando	Descripción de 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 cualquier cambio que haya realizado.
exit	Sale del intérprete de comandos.
quit

nota

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

Ejecutar instrucciones individuales

A excepción de los comandos de la base de datos y los metacomandos del shell que aparecen en README.md, el shell interpreta cada comando que se introduce como una sentencia PartiQL independiente. De forma predeterminada, el intérprete de comandos habilita el modo auto-commit. Este modo es configurable.

En el modo auto-commit, el intérprete de comandos ejecuta implícitamente cada instrucción en su propia transacción y la confirma automáticamente si no se encuentra ningún error. Esto significa que no tiene que ejecutar start transaction (ni begin) y commit manualmente cada vez que ejecute una instrucción.

Administración de transacciones

Como alternativa, el QLDB shell te permite controlar las transacciones manualmente. Puede ejecutar varias instrucciones dentro de una transacción de forma interactiva o no interactiva agrupando comandos e instrucciones por lotes de forma secuencial.

Transacciones activas

Para ejecutar una transacción interactiva, realice los siguientes pasos.

1. Para iniciar una transacción, introduzca el comando begin.

   qldb> begin

   Tras iniciar una transacción, el intérprete de comandos muestra la siguiente línea de comandos.

   qldb *>  

2. A continuación, todas las instrucciones que introduzca se ejecutarán en la misma transacción.

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

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

     Tras pulsar Enter, el intérprete de comandos muestra los resultados de la instrucción.

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

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

3. Para finalizar la transacción, inserte uno de los siguientes comandos.

   • Introduzca el comando commit para confirmar la transacción en el diario del libro mayor.

     qldb *> commit

   • Introduzca el comando abort para detener la transacción y rechazar cualquier cambio que haya realizado.

     qldb *> abort
     transaction was aborted

Límite de tiempo de espera de transacción

Una transacción interactiva cumple con el límite de tiempo QLDB de espera de la transacción. Si no confirmas una transacción en un plazo de 30 segundos desde su inicio, la transacción vence QLDB automáticamente y rechaza cualquier cambio realizado durante la transacción.

A continuación, en lugar de mostrar los resultados de la instrucción, el intérprete de comandos muestra un mensaje de error de caducidad y vuelve a la línea de comandos normal. Para volver a intentarlo, debe volver a introducir el comando begin 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 instrucciones agrupando los comandos y las declaraciones de forma secuencial 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 cada instrucción con un delimitador de punto y coma (;). Si alguna de las instrucciones de la transacción no es válida, el intérprete de comandos la rechaza automáticamente. El intérprete de comandos no procederá con ningún extracto 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 se produce un error en una transacción, el intérprete de comandos no procederá con ninguna transacción o instrucción posterior que haya introducido.

Si no finaliza una transacción, el intérprete de comandos pasa al modo interactivo y le pide el siguiente comando o instrucción.

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

Salir del intérprete de comandos

Para salir de la sesión de intérprete de comandos qldb actual, introduzca el comando exit o quit, o utilice la combinación de teclas Ctrl+D cuando el intérprete de comandos no esté incluido en una transacción.

qldb> exit
$ 

qldb> quit
$ 

Ejemplo

Para obtener información sobre cómo escribir sentencias PartiQL enQLDB, consulte. Referencia de Amazon QLDB PartiQL

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

nota

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

En este ejemplo se supone que el libro mayor test-ledger ya 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