Accessing Amazon QLDB Using the QLDB Shell (Data Plane Only) - Amazon Quantum Ledger Database (Amazon QLDB)

Accessing Amazon QLDB Using the QLDB Shell (Data Plane Only)

Amazon QLDB provides a command line shell for interaction with the transactional data plane. The QLDB Shell enables you to execute PartiQL statements on ledger data. This shell is written in Python and is open-sourced in the GitHub repository awslabs/amazon-qldb-shell.

Note

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

To interact with the qldb control plane API actions using a command line interface, see Accessing Amazon QLDB Using the AWS CLI (Control Plane Only).

This tool is not intended to be incorporated into an application or adopted for production purposes. The objective of this tool is to give developers, DevOps, database administrators, and others who are interested the opportunity to 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 Amazon QLDB Shell, you must do the following:

  1. Follow the AWS setup instructions in Accessing Amazon QLDB. This includes signing up for AWS and getting an AWS access key for development.

  2. Install Python version 3.4 or later from the Python downloads site.

  3. Set up your AWS credentials and your default AWS Region. For instructions, see Quickstart in the AWS SDK for Python (Boto3) documentation.

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

Setting Up the Shell

To install the QLDB Shell from PyPI using pip3 (a package manager for Python 3), run the following at your command line terminal.

$ pip3 install qldbshell

Installing the shell also installs the following required package dependencies:

  • pyqldb – Requires version 2.0.2 or earlier.

  • amazon.ion

  • argparse

  • boto3

The shell is not compatible with the latest version (3.x) of the QLDB Driver for Python (pyqldb). If you have the latest version installed, see Resolving the Driver Dependency for additional setup instructions.

Invoking the Shell

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

$ qldbshell --ledger test-ledger

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

Each successive line that you enter in your qldbshell session is treated as a separate PartiQL statement. In the current version of the QLDB Shell, a PartiQL statement cannot span more than one line.

Connection Parameters

To see a list of available input arguments, run the following command before you invoke a qldbshell session.

$ qldbshell --help

The following connection parameters are available for the qldbshell command. You can add the optional arguments to override the AWS Region, credentials profile, and endpoint that the shell uses.

Usage syntax:

$ qldbshell -l LEDGER_NAME [-v] [-p PROFILE] [-r REGION_CODE] [-s QLDB_SESSION_ENDPOINT]

Required arguments

-l LEDGER_NAME
--ledger LEDGER_NAME

Specifies the name of the ledger that the shell connects to. The ledger name must already exist and must be active.

Optional arguments

-v
--verbose

Increases output verbosity in your shell session.

-p PROFILE
--profile PROFILE

Specifies the location of your AWS credentials profile that the shell uses for authentication.

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

-r REGION_CODE
--r region REGION_CODE

Specifies the AWS Region code of the QLDB ledger that the shell connects 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 QLDB_SESSION_ENDPOINT

Specifies the qldb-session API endpoint that the shell connects to.

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

Parameter File

As an alternative to passing arguments on the command line, you can also save input parameters in a file. Put each parameter on a separate line. Then, pass the file name to the qldbshell as follows.

$ qldbshell @params.conf

Exiting the Shell

To exit the current qldbshell session and close the current ledger database connection, run the exit command.

qldbshell > exit

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 executes each PartiQL statement in this example in its own transaction.

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

$ qldbshell --ledger test-ledger --region us-east-1 qldbshell > CREATE TABLE TestTable qldbshell > INSERT INTO TestTable `{"Name": "John Doe"}` qldbshell > SELECT * FROM TestTable qldbshell > DROP TABLE TestTable qldbshell > exit

Common Errors

This section provides instructions to resolve common errors that you might encounter while using the QLDB Shell.

Resolving the Driver Dependency

The QLDB Shell requires version 2.0.2 or earlier of the QLDB Driver for Python. If you have an incompatible version of the driver installed, you might see one of the following error messages.

ModuleNotFoundError: No module named 'pyqldb.driver.pooled_qldb_driver'
ERROR: pyqldb 3.0.0rc1 has requirement amazon.ion<0.6,>=0.5.0, but you'll have amazon-ion 0.6.0 which is incompatible.

To resolve this driver dependency issue, you can downgrade to an earlier version. Or, you can run the shell in a virtual environment, which installs an older version of the driver.

To downgrade the driver to version 2.x

  1. Uninstall the current version of the driver.

    $ pip3 uninstall pyqldb
  2. Install version 2.0.2 of the driver.

    $ pip3 install pyqldb==2.0.2

To run the shell in a virtual environment

  1. Install virtualenv.

    $ pip3 install virtualenv
  2. Create your virtual environment. You can replace venv with your own environment name.

    $ virtualenv venv
  3. Activate your virtual environment. Replace venv with the environment name that you created in the previous step.

    $ source venv/bin/activate
  4. Install the QLDB Shell.

    $ pip3 install qldbshell
  5. Proceed to Invoking the Shell to run the shell in your virtual environment.

  6. After you finish using the shell, you can deactivate the virtual environment.

    $ deactivate