Acessando a Amazon QLDB usando o QLDB shell (APIsomente dados)

Importante

Aviso de fim do suporte: os clientes existentes poderão usar a Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte Migrar um Amazon QLDB Ledger para o Amazon Aurora Postgre. SQL

QLDBA Amazon fornece um shell de linha de comando para interação com os dados transacionais. API Com o QLDB shell, você pode executar instruções partiQL em dados contábeis.

A versão mais recente desse shell é escrita em Rust e é de código aberto no GitHub repositório amazon-qldb-shellawslabs/ na ramificação padrão. main A versão do Python (v1) também ainda está disponível para uso no mesmo repositório na ramificação master.

nota

O QLDB shell da Amazon suporta apenas os qldb-session dados transacionais. API Isso API é usado somente para executar instruções partiQL em um QLDB livro contábil.

Para interagir com as API operações qldb de gerenciamento usando uma interface de linha de comando, consulteAcessando a Amazon QLDB usando o AWS CLI (APIsomente gerenciamento).

Essa ferramenta não se destina a ser incorporada a um aplicativo ou adotada para fins de produção. O objetivo dessa ferramenta é permitir que você experimente rapidamente com o QLDB PartiQL.

As seções a seguir descrevem como começar a usar o QLDB shell.

Pré-requisitos

Antes de começar a usar o QLDB shell, você deve fazer o seguinte:

1. Siga as instruções AWS de configuração emAcessando a Amazon QLDB. Essa transmissão inclui o seguinte:

   1. Inscreva-se em AWS.

   2. Crie um usuário com as QLDB permissões apropriadas.

   3. Conceda acesso programático para desenvolvimento.

2. Configure suas AWS credenciais e seu padrão Região da AWS. Para obter instruções, consulte Configuração rápida no Guia do usuário AWS Command Line Interface .

   Para obter uma lista completa das regiões disponíveis, consulte QLDBendpoints e cotas da Amazon no. Referência geral da AWS

3. Para qualquer livro contábil no modo de STANDARD permissões, crie IAM políticas que concedam permissões para executar instruções partiQL nas tabelas apropriadas. Para saber como criar essas políticas, consulte Introdução ao modo de permissões padrão na Amazon QLDB.

Instalar o shell

Para instalar a versão mais recente do QLDB shell, consulte o READMEarquivo.md em GitHub. QLDBfornece arquivos binários pré-criados para Linux, macOS e Windows na seção Versões do repositório. GitHub

Para macOS, o shell se integra ao aws/tap Homebrew tap. Para instalar o shell no macOS usando Homebrew, execute os comandos a seguir.

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

Configuração

Após a instalação, o shell carrega o arquivo de configuração padrão localizado em $XDG_CONFIG_HOME/qldbshell/config.ion durante a inicialização. No Linux e macOS, esse arquivo está normalmente em ~/.config/qldbshell/config.ion. Se esse arquivo não existir, o shell será executado com as configurações padrão.

Você pode criar um arquivo config.ion manualmente após a instalação. Esse arquivo de configuração usa o formato de dados Amazon Ion. Este é um exemplo de um arquivo mínimo config.ion.

{
  default_ledger: "my-example-ledger"
}

Se default_ledger não estiver definido no seu arquivo de configuração, o parâmetro --ledger será necessário quando você invocar o shell. Para obter uma lista completa das opções de configuração, consulte o READMEarquivo.md em GitHub.

Invocar o shell

Para invocar o QLDB shell em seu terminal de linha de comando para um livro contábil específico, execute o comando a seguir. Substituir my-example-ledger com o nome do seu livro contábil.

$ qldb --ledger my-example-ledger

Esse comando se conecta ao seu padrão Região da AWS. Para especificar explicitamente a Região, você pode executar o comando com o parâmetro --region ou --qldb-session-endpoint, conforme descrito na seção a seguir.

Depois de invocar uma sessão de shell qldb, você pode inserir os seguintes tipos de entrada:

• Comandos do Shell

• Instruções partiQL únicas em transações separadas

• Várias instruções partiQL em uma transação

Parâmetros do shell

Para obter uma lista completa dos sinalizadores e opções disponíveis para invocar um shell, execute o comando qldb com o sinalizador --help, da seguinte maneira.

$ qldb --help

Veja a seguir alguns sinalizadores principais e opções para o comando qldb. Você pode adicionar esses parâmetros opcionais para substituir o perfil de credenciais Região da AWS, o endpoint, o formato dos resultados e outras opções de configuração.

Uso

$ qldb [FLAGS] [OPTIONS]

FLAGS

-h, --help

Imprime informações de ajuda.

-v, --verbose

Configura a verbosidade do log. Por padrão, o shell registra somente erros. Para aumentar o nível de verbosidade, repita esse argumento (por exemplo,-vv). O nível mais alto é -vvv, o que corresponde à verbosidade trace.

-V, --version

Imprime as informações da versão.

OPTIONS

-l, --ledger LEDGER_NAME

É o nome do ledger ao qual se conectar. Esse é um parâmetro de shell obrigatório se default_ledger não estiver definido em seu arquivo config.ion. Nesse arquivo, você pode definir opções adicionais, como a Região.

-c, --config CONFIG_FILE

O arquivo em que você pode definir qualquer opção de configuração do shell. Para obter detalhes de formatação e uma lista completa das opções de configuração, consulte o READMEarquivo.md em. GitHub

-f, --format ion|table

O formato de saída dos resultados da sua consulta. O padrão é ion.

-p, --profile PROFILE

A localização do seu perfil de AWS credenciais a ser usado para autenticação.

Se não for fornecido, o shell usa seu AWS perfil padrão, localizado em~/.aws/credentials.

-r, --region REGION_CODE

O Região da AWS código do QLDB livro contábil ao qual se conectar. Por exemplo: us-east-1.

Se não for fornecido, o shell se conectará ao seu padrão Região da AWS conforme especificado em seu AWS perfil.

-s, --qldb-session-endpoint QLDB_SESSION_ENDPOINT

O qldb-session API endpoint ao qual se conectar.

Para obter uma lista completa das QLDB regiões e endpoints disponíveis, consulte os QLDBendpoints e cotas da Amazon no. Referência geral da AWS

Referência de comando

Depois de invocar uma sessão qldb, o shell oferece suporte às seguintes chaves e comandos de banco de dados:

Chaves Shell
Chave	Descrição da função
Enter	Executa a instrução.
Escape+Enter (macOS, Linux) Shift+Enter (Windows)	Inicia uma nova linha para inserir uma declaração que abrange várias linhas. Você também pode copiar o texto de entrada com várias linhas e colá-lo no shell. Para obter instruções sobre como configurar Option em vez de Escape como chave meta no macOS, consulte o site do OS X Daily.
Ctrl+C	Cancela o comando atual.
Ctrl+D	Sinaliza o fim do arquivo (EOF) e sai do nível atual do shell. Se não estiver em uma transação ativa, sai do shell. Em uma transação ativa, aborta a transação.

Comandos do banco de dados do shell
Comando	Descrição da função
help	Exibe as informações de ajuda.
begin	Inicia uma transação.
start transaction
commit	Confirma sua transação no diário do ledger.
abort	Interrompe sua transação e rejeita todas as alterações que você fez.
exit	Sai do shell.
quit

nota

Todos os comandos QLDB do shell não diferenciam maiúsculas de minúsculas.

Executar instruções individuais

Com exceção dos comandos do banco de dados e dos meta-comandos do shell listados em README.md, o shell interpreta cada comando inserido como uma instrução partiQL separada. Por padrão, o shell ativa o modo auto-commit. Esse modo é configurável.

No modo auto-commit, o shell executa implicitamente cada instrução em sua própria transação e confirma automaticamente a transação se nenhum erro for encontrado. Isso significa que você não precisa executar start transaction (ou begin) e commit manualmente toda vez que executar uma instrução.

Gerenciamento de transações

Como alternativa, o QLDB shell permite que você controle manualmente as transações. Você pode executar várias instruções em uma transação de forma interativa ou não interativa, agrupando comandos e instruções em lote sequencialmente.

Transações interativas

Para executar uma transação interativa, execute as etapas a seguir.

1. Para iniciar uma transação, digite o comando begin.

   qldb> begin

   Depois de iniciar uma transação, o shell exibirá o seguinte prompt de comando.

   qldb *>  

2. Em seguida, cada instrução inserida é executada na mesma transação.

   • Por exemplo, é possível executar uma única instrução da seguinte forma.

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

     Depois de pressionar Enter, o shell exibe os resultados da instrução.

   • Você também pode inserir várias instruções ou comandos separados por um delimitador de ponto e vírgula (;) da seguinte forma.

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

3. Para finalizar a transação, insira um dos seguintes comandos.

   • Insira o comando commit para confirmar sua transação no diário do ledger.

     qldb *> commit

   • Digite o comando abort para interromper sua transação e rejeitar as alterações feitas.

     qldb *> abort
     transaction was aborted

Tempo limite de transação

Uma transação interativa segue o limite de tempo limite QLDB da transação. Se você não confirmar uma transação dentro de 30 segundos após iniciá-la, a transação QLDB expirará automaticamente e rejeitará todas as alterações feitas durante a transação.

Então, em vez de exibir os resultados da instrução, o shell exibe uma mensagem de erro de expiração e retorna ao prompt de comando normal. Para tentar novamente, você deve digitar o comando begin novamente para iniciar uma nova transação.

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

Transações não-interativas

Você pode executar uma transação completa com várias instruções agrupando comandos em lotes e instruções sequencialmente da seguinte maneira.

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

Você deve separar cada comando e instrução com um delimitador de ponto e vírgula (;). Se alguma instrução na transação não for válida, o shell rejeitará automaticamente a transação. O shell não prossegue com nenhuma instrução subsequente que você inseriu.

Também é possível configurar várias transações.

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

Semelhante ao exemplo anterior, se uma transação falhar, o shell não prosseguirá com nenhuma transação ou instrução subsequente que você inseriu.

Se você não finalizar uma transação, o shell mudará para o modo interativo e solicitará o próximo comando ou instrução.

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

Sair do shell

Para sair da sessão atual do shell qldb, digite o comando exit ou quit ou use o atalho de teclado Ctrl + D quando o shell não estiver em uma transação.

qldb> exit
$ 

qldb> quit
$ 

Exemplo

Para obter informações sobre como escrever instruções partiQL emQLDB, consulte o. Referência do Amazon QLDB PartiQL

O exemplo a seguir exibe uma sequência comum de comandos básicos.

nota

O QLDB shell executa cada instrução partiQL neste exemplo em sua própria transação.

Este exemplo pressupõe que o ledger test-ledger já exista e esteja ativo.

$ 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