Accessing Amazon QLDB using the QLDB shell (data API only)

Amazon QLDB provides a command line shell for interaction with the transactional data API. With the QLDB shell, you can run PartiQL statements on ledger data.

The latest version of this shell is written in Rust and is open source in the GitHub repository awslabs/amazon-qldb-shell on the default main branch. The Python version (v1) is also still available for use in the same repository on the master branch.

This tool isn't intended to be incorporated into an application or adopted for production purposes. The objective of this tool is to let you rapidly experiment with QLDB and PartiQL.

The following sections describe how to get started with the QLDB shell.

Prerequisites

Before you get started with the QLDB shell, you must do the following:

Installing the shell

To install the latest version of the QLDB shell, see the README.md file on GitHub. QLDB provides pre-built binary files for Linux, macOS, and Windows in the Releases section of the GitHub repository.

For macOS, the shell integrates with the aws/tap Homebrew tap. To install the shell on macOS using Homebrew, run the following commands.

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

Configuration

After installation, the shell loads the default configuration file that is located at $XDG_CONFIG_HOME/qldbshell/config.ion during initialization. On Linux and macOS, this file is typically at ~/.config/qldbshell/config.ion. If such a file doesn't exist, the shell runs with default settings.

You can create a config.ion file manually after installation. This configuration file uses the Amazon Ion data format. The following is an example of a minimal config.ion file.

{
  default_ledger: "my-example-ledger"
}

If default_ledger isn't set in your configuration file, the --ledger parameter is required when you invoke the shell. For a full list of configuration options, see the README.md file on GitHub.

Invoking the shell

To invoke the QLDB shell on your command line terminal for a specific ledger, run the following command. Replace my-example-ledger with your ledger name.

$ qldb --ledger my-example-ledger

This command connects to your default AWS Region. To explicitly specify the Region, you can run the command with the --region or --qldb-session-endpoint parameter, as described in the following section.

After invoking a qldb shell session, you can enter the following types of input:

Shell parameters

For a full list of available flags and options for invoking a shell, run the qldb command with the --help flag, as follows.

$ qldb --help

The following are some key flags and options for the qldb command. You can add these optional parameters to override the AWS Region, credentials profile, endpoint, results format, and other configuration options.

Usage

$ qldb [FLAGS] [OPTIONS]

Command reference

After you invoke a qldb session, the shell supports the following keys and database commands:

Running individual statements

Except for the database commands and shell meta commands listed in README.md, the shell interprets each command that you enter as a separate PartiQL statement. By default, the shell enables auto-commit mode. This mode is configurable.

In the auto-commit mode, the shell implicitly runs each statement in its own transaction and automatically commits the transaction if no errors are found. This means that you don't have to run start transaction (or begin) and commit manually each time you run a statement.

Managing transactions

Alternatively, the QLDB shell lets you manually control transactions. You can run multiple statements within a transaction interactively, or non-interactively by batching commands and statements sequentially.

Interactive transactions

To run an interactive transaction, do the following steps.

Transaction timeout limit

An interactive transaction adheres to QLDB's transaction timeout limit. If you don't commit a transaction within 30 seconds of starting it, QLDB automatically expires the transaction and rejects any changes made during the transaction.

Then, instead of displaying the statement results, the shell displays an expiration error message and returns to the normal command prompt. To retry, you must enter the begin command again to begin a new transaction.

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

Non-interactive transactions

You can run a complete transaction with multiple statements by batching commands and statements sequentially as follows.

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

You must separate each command and statement with a semicolon (;) delimiter. If any statement in the transaction isn't valid, the shell automatically rejects the transaction. The shell doesn't proceed with any subsequent statements that you entered.

You can also set up multiple transactions.

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

Similar to the previous example, if a transaction fails, the shell doesn't proceed with any subsequent transactions or statements that you entered.

If you don't end a transaction, the shell switches to interactive mode and prompts you for the next command or statement.

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

Exiting the shell

To exit the current qldb shell session, enter the exit or quit command, or use the keyboard shortcut Ctrl+D when the shell isn't in a transaction.

qldb> exit
$ 

qldb> quit
$ 

Example

For information about writing PartiQL statements in QLDB, see the Amazon QLDB PartiQL reference.

$ 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