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.

Note

The Amazon QLDB shell only supports the qldb-session transactional data API. This API is used only for running PartiQL statements on a QLDB ledger.

To interact with the qldb management API operations using a command line interface, see Accessing Amazon QLDB using the AWS CLI (management API only).

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:

1. Follow the AWS setup instructions in Accessing Amazon QLDB. This includes the following:

   1. Sign up for AWS.

   2. Create a user with the appropriate QLDB permissions.

   3. Grant programmatic access for development.

2. Set up your AWS credentials and your default AWS Region. For instructions, see Configuration basics in the AWS Command Line Interface User Guide.

   For a complete list of available Regions, see Amazon QLDB endpoints and quotas in the AWS General Reference.

3. For any ledgers in the STANDARD permissions mode, create IAM policies that grant you permissions to run PartiQL statements on the appropriate tables. To learn how to create these policies, see Getting started with the standard permissions mode in Amazon QLDB.

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 commands

• Single PartiQL statements in separate transactions

• Multiple PartiQL statements within a transaction

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]

FLAGS

-h, --help

Prints help information.

-v, --verbose

Configures the logging verbosity. By default, the shell logs errors only. To increase the verbosity level, repeat this argument (for example, -vv). The highest level is -vvv which corresponds to trace verbosity.

-V, --version

Prints version information.

OPTIONS

-l, --ledger LEDGER_NAME

The name of the ledger to connect to. This is a required shell parameter if default_ledger isn't set in your config.ion file. In this file, you can set additional options, such as the Region.

-c, --config CONFIG_FILE

The file where you can define any shell configuration options. For formatting details and a full list of configuration options, see the README.md file on GitHub.

-f, --format ion|table

The output format of your query results. The default is ion.

-p, --profile PROFILE

The location of your AWS credentials profile to use for authentication.

If not provided, the shell uses your default AWS profile, which is located at ~/.aws/credentials.

-r, --region REGION_CODE

The AWS Region code of the QLDB ledger to connect to. For example: us-east-1.

If not provided, the shell connects to your default AWS Region as specified in your AWS profile.

-s, --qldb-session-endpoint QLDB_SESSION_ENDPOINT

The qldb-session API endpoint to connect to.

For a complete list of available QLDB Regions and endpoints, see Amazon QLDB endpoints and quotas in the AWS General Reference.

Command reference

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

Shell keys
Key	Function description
Enter	Runs the statement.
Escape+Enter (macOS, Linux) Shift+Enter (Windows)	Starts a new line to enter a statement that spans multiple lines. You can also copy input text with multiple lines and paste it into the shell. For instructions on setting up Option instead of Escape as a Meta key in macOS, see the OS X Daily site.
Ctrl+C	Cancels the current command.
Ctrl+D	Signals end of file (EOF) and exits the current level of the shell. If not in an active transaction, exits the shell. In an active transaction, aborts the transaction.

Shell database commands
Command	Function description
help	Displays the help information.
begin	Begins a transaction.
start transaction
commit	Commits your transaction to the ledger's journal.
abort	Stops your transaction and rejects any changes that you made.
exit	Exits the shell.
quit

Note

All QLDB shell commands are case insensitive.

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.

1. To begin a transaction, enter the begin command.

   qldb> begin

   After you begin a transaction, the shell displays the following command prompt.

   qldb *>  

2. Then, each statement that you enter runs in the same transaction.

   • For example, you can run a single statement as follows.

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

     After you press Enter, the shell displays the results of the statement.

   • You can also enter multiple statements or commands separated by a semicolon (;) delimiter as follows.

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

3. To end the transaction, enter one of the following commands.

   • Enter the commit command to commit your transaction to the ledger's journal.

     qldb *> commit

   • Enter the abort command to stop your transaction and reject any changes that you made.

     qldb *> abort
     transaction was aborted

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.

The following example shows a common sequence of basic commands.

Note

The QLDB shell runs each PartiQL statement in this example in its own transaction.

This example assumes that the ledger test-ledger already exists and is active.

$ 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