QLDB Interactive Shell

This tool provides an interface to send PartiQL statements to Amazon Quantum Ledger Database (QLDB). This tool is not intended to be incorporated into an application or adopted for production purposes. The objective of the tool is to give developers, devops, database administrators, and anyone else interested the opportunity for rapid experimentation with QLDB and PartiQL.

Prerequisites

This readme assumes you have an AWS account, an environment configured with AWS credentials, as well as IAM users/roles with appropriate access to QLDB. This readme focuses on shell configuration and commands. For a guide about prerequisites and general use of the shell, please see the Developer Guide: Using the Amazon QLDB Shell

QLDB Core Concepts

• QLDB ensures that transactions are consistent upon commit by using optimistic currency control (OCC).
• In QLDB, every statement (including every SELECT query) must run in a transaction.
• By default, the shell enables auto-commit mode. In this mode, the shell interprets each command that you enter as a separate PartiQL statement, meaning that you don't have to run start transaction and commit manually each time. This is configurable (see below).
• 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, the shell displays an error message and returns to the normal command prompt. To retry, you must enter the begin or start transaction command again to begin a new transaction.
  • Consider reading more in our guide for optimizing query performance.
• QLDB supports a subset of the PartiQL query language. When you use the QLDB shell to query data in Amazon QLDB, you write statements in PartiQL, but results are shown in Amazon Ion (this is configurable). PartiQL is intended to be SQL-compatible, whereas Ion is an extension of JSON. This leads to syntactic differences with how you notate data in your queries, compared to how the QLDB console presents your query results. Further details are available in the Developer Guide: Querying Ion with PartiQL.
• This QLDB shell is used for the data plane only. To interact with the control plane, use the AWS CLI

Installation

In general, see releases for the latest and greatest. We provide prebuilt binaries for Linux, Windows and macOS. Find your platform, download, extract and run!

If your platform is not supported, feel free to open an issue!

macOS

On macOS, we integrate with the aws/tap Homebrew tap:

xcode-select --install # required to use Homebrew
brew tap aws/tap # Add AWS as a Homebrew tap
brew install qldbshell
qldb --ledger <your-ledger>

Configuration

After installation, the Shell will load default config file located at $XDG_CONFIG_HOME/qldbshell/config.ion during initialization. On Linux and Macos, this will typically be at ~/.config/qldbshell/config.ion. If such a file doesn't exist, the shell will run with default settings.

You can create a config.ion config file manually after installation. The config file uses Ion. If you're new to Ion, you can consider the file to be JSON with support for comments and you'll be just fine!

{
  default_ledger: "my-ledger",

  ui: {
    // Determines whether each statement will be executed as a transaction or not.
    // By default this is on, meaning that statements are all executed as individual transactions.
    auto_commit: true, // the default; can be set to false

    // Set your prompt to your desired value. The following values can be interpolated:
    //   - $REGION: the name of the AWS region
    //   - $LEDGER: the name of the ledger
    //   - $ACTIVE_TRANSACTION: the string " \*" if a transaction is open
    prompt: "your-prompt-syntax", // default: "qldb$ACTIVE_TRANSACTION> "

    // format = [ion|table]
    //   ion: Prints the objects from the database as ION documents in text.
    //   table: Tabulates the data and prints out the data as rows.
    format: "table", // or ion default: ion

    edit_mode: "Emacs", // or Vi default: Emacs

    // Can be toggled to suppress some messaging when runnning in interactive mode
    display_welcome: true, // the default; can be set to false
    display_ctrl_signals: true,

    // Determines whether or not metrics will be emitted after the results of a query are shown.
    display_query_metrics: true,

    // Set terminator_required to true indicates that pressing the enter key at the end of a line of input will not execute the command by itself.
    // Alternately, if you end your statement with a semi-colon (`;`) you will execute the statement.
    terminator_required: true
  }
}

An example minimal config.ion config file:

{
  default_ledger: "my-ledger"
}

If default_ledger is not set, then --ledger becomes a required CLI parameter.

Building from source

See HACKING.md for further instructions

Command interface

Shell Keys

• Enter
  • Runs the statement
• Escape+Enter (macOS, *nix) or 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
  • EOF / exits the current level of the shell. If not in a transaction, exits the shell. If in a transaction, aborts the transaction.

Database commands

• start transaction or begin
  • Manually starts a transaction. You can run multiple statements within a transaction interactively, or non-interactively by batching commands and statements sequentially. Transactions that are not committed within 30 seconds will time out, and QLDB will reject any changes made during the transaction. For more details and examples, see the QLDB Developer Guide.
• commit
  • Commits a transaction. If there is no transaction in progress, the shell reports an error saying that there is no active transaction.
• abort
  • Aborts a transaction. If there is no transaction in progress, the shell reports an error saying that there is no active transaction.
• help
  • Prints the lists of database and meta commands.
• quit or exit
  • Quits the shell.

Shell Meta Commands

All commands to the shell itself will be prefixed with a backslash \, e.g:

• \use -l LEDGER_NAME [-p PROFILE] [-r REGION_CODE] [-s QLDB_SESSION_ENDPOINT]
  • Switch to a different ledger (or: region, endpoint, AWS profile) without restarting the shell.
• \set
  • \set edit-mode [emacs|vi] Toggle between Emacs/Vi keybindings.
  • \set terminator-required [true|false] Toggle terminator_required.
• \show tables
  • Display a list of active tables in the current ledger.
• \status
  • Prints out your current region, ledger and Shell version.
• \env
  • Prints out your current environment settings including where they were set from.

License

This project is licensed under the Apache-2.0 License.