Basic Operations for Amazon QLDB Ledgers - Amazon Quantum Ledger Database (Amazon QLDB)

Basic Operations for Amazon QLDB Ledgers

You can use the QLDB API or the AWS Command Line Interface (AWS CLI) to create, update, and delete ledgers in Amazon QLDB. You can also list all the ledgers in your account, or get information about a specific ledger.

The following are the common steps for ledger operations using the AWS SDK for Java and the AWS CLI. For full Java code examples that demonstrate these operations, see Installing the Amazon QLDB Java Sample Application to download the complete QLDB sample application. Or, follow the step-by-step instructions in the Getting Started with the Amazon QLDB Driver tutorial for Java.

Creating a Ledger

Use the CreateLedger operation to create a ledger in your AWS account. You must provide the following information:

  • Ledger name — The name of the ledger that you want to create in your account. The name must be unique among all of your ledgers in the current AWS Region.

  • Permissions mode — The permissions mode to assign to the ledger. The only permissions mode that is currently supported for a ledger is ALLOW_ALL.

  • Deletion protection — (Optional) The flag that prevents a ledger from being deleted by any user. If not provided on ledger creation, this feature is enabled (true) by default.

    If deletion protection is enabled, you must first disable it before you can delete the ledger using the QLDB API or the AWS CLI. You can disable it by using the UpdateLedger operation to set the flag to false.

  • Tags — (Optional) Add metadata to the ledger by attaching tags as key-value pairs. You can add tags to your ledger to help organize and identify them. For more information, see Tagging Amazon QLDB Resources.

The ledger is not ready for use until QLDB creates it and sets its status to ACTIVE.

To create a ledger using the AWS SDK for Java

  1. Create an instance of the AmazonQLDB class.

  2. Create an instance of the CreateLedgerRequest class to provide the request information.

    You must provide the ledger name and a permissions mode.

  3. Execute the createLedger method by providing the request object as a parameter.

The createLedger request returns a CreateLedgerResult object that has information about the ledger. See the next section for an example of using the DescribeLedger operation to check your ledger's status after you create it.

The following examples demonstrate the preceding steps.

Example

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); CreateLedgerRequest request = new CreateLedgerRequest() .withName(ledgerName) .withPermissionsMode(PermissionsMode.ALLOW_ALL); CreateLedgerResult result = client.createLedger(request);
Note

Deletion protection is enabled by default if you don't specify it.

Example — Disable deletion protection and attach specified tags

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); Map<String, String> tags = new HashMap<>(); tags.put("IsTest", "true"); tags.put("Domain", "Test"); CreateLedgerRequest request = new CreateLedgerRequest() .withName(ledgerName) .withPermissionsMode(PermissionsMode.ALLOW_ALL) .withDeletionProtection(false) .withTags(tags); CreateLedgerResult result = client.createLedger(request);

Create a new ledger named vehicle-registration.

Example

aws qldb create-ledger --name vehicle-registration --permissions-mode ALLOW_ALL
Note

Deletion protection is enabled by default if you don't specify it.

Or, create a new ledger named vehicle-registration with deletion protection disabled and with specified tags.

Example

aws qldb create-ledger --name vehicle-registration --no-deletion-protection --permissions-mode ALLOW_ALL --tags IsTest=true,Domain=Test

Describing a Ledger

Use the DescribeLedger operation to view details about a ledger. You must provide the ledger name. The output from DescribeLedger is in the same format as that from CreateLedger. It includes the following information:

  • Ledger name — The name of the ledger that you want to describe.

  • ARN — The Amazon Resource Name (ARN) for the ledger in the following format.

    arn:aws::qldb:aws-region:account-id:ledger/ledger-name
  • Deletion protection — The flag that indicates whether the deletion protection feature is enabled.

  • Creation date and time — The date and time, in epoch time format, when the ledger was created.

  • State — The current status of the ledger. This can be one of the following values:

    • CREATING

    • ACTIVE

    • DELETING

Note

After you create a QLDB ledger, it becomes ready for use when its status changes from CREATING to ACTIVE.

To describe a ledger using the AWS SDK for Java

  1. Create an instance of the AmazonQLDB class. Or, you can use the same instance of the AmazonQLDB client that you instantiated for the CreateLedger request.

  2. Create an instance of the DescribeLedgerRequest class and provide the ledger name that you want to describe.

  3. Execute the describeLedger method by providing the request object as a parameter.

  4. The describeLedger request returns a DescribeLedgerResult object that has current information about the ledger.

The following code example demonstrates the preceding steps. You can call the describeLedger method of the client to get ledger information at any time.

Example

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); DescribeLedgerRequest request = new DescribeLedgerRequest().withName(ledgerName); DescribeLedgerResult result = client.describeLedger(request); System.out.printf("%s: ARN: %s \t State: %s \t CreationDateTime: %s \t DeletionProtection: %s", result.getName(), result.getArn(), result.getState(), result.getCreationDateTime(), result.getDeletionProtection());

Describe the vehicle-registration ledger that you just created.

Example

aws qldb describe-ledger --name vehicle-registration

Updating a Ledger

The UpdateLedger operation currently enables you to change the DeletionProtection flag only for an existing ledger. The output from UpdateLedger is in the same format as that from CreateLedger.

To update a ledger using the AWS SDK for Java

  1. Create an instance of the AmazonQLDB class.

  2. Create an instance of the UpdateLedgerRequest class to provide the request information.

    You must provide the ledger name and a new Boolean value for deletion protection.

  3. Execute the updateLedger method by providing the request object as a parameter.

The following code example demonstrates the preceding steps. The updateLedger request returns an UpdateLedgerResult object that has updated information about the ledger.

Example

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); UpdateLedgerRequest request = new UpdateLedgerRequest() .withName(ledgerName) .withDeletionProtection(false); UpdateLedgerResult result = client.updateLedger(request);

If your vehicle-registration ledger has deletion protection enabled, you must first disable it before you can delete it.

Example

aws qldb update-ledger --name vehicle-registration --no-deletion-protection

Deleting a Ledger

Use the DeleteLedger operation to delete a ledger and all of its contents. Deleting a ledger is an unrecoverable operation.

If deletion protection is enabled for your ledger, you must first disable it before you can delete the ledger using the QLDB API or the AWS CLI. When you use the QLDB console to delete a ledger, the console disables deletion protection for you.

When you issue a DeleteLedger request, the ledger's state changes from ACTIVE to DELETING. It might take a while to delete the ledger, depending on the amount of storage it uses. When the DeleteLedger operation concludes, the ledger no longer exists in QLDB.

To delete a ledger using the AWS SDK for Java

  1. Create an instance of the AmazonQLDB class.

  2. Create an instance of the DeleteLedgerRequest class and provide the ledger name that you want to delete.

  3. Execute the deleteLedger method by providing the request object as a parameter.

The following code example demonstrates the preceding steps.

Example

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); DeleteLedgerRequest request = new DeleteLedgerRequest().withName(ledgerName); DeleteLedgerResult result = client.deleteLedger(request);

Delete your vehicle-registration ledger.

Example

aws qldb delete-ledger --name vehicle-registration

Listing Ledgers

The ListLedgers operation returns summary information of all QLDB ledgers for the current AWS account and Region.

To list ledgers in your account using the AWS SDK for Java

  1. Create an instance of the AmazonQLDB class.

  2. Create an instance of the ListLedgersRequest class.

    If you received a value for NextToken in the response from a previous ListLedgers call, you must provide that value in this request. This enables you to get the next page of results.

  3. Execute the listLedgers method by providing the request object as a parameter.

  4. The listLedgers request returns a ListLedgersResult object. This object has a list of LedgerSummary objects and a pagination token that indicates whether there are more results available:

    • If NextToken is empty, the last page of results has been processed and there are no more results.

    • If NextToken is not empty, there are more results available. To retrieve the next page of results, use the value of NextToken in a subsequent ListLedgers call.

The following code example demonstrates the preceding steps.

Example

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); List<LedgerSummary> ledgerSummaries = new ArrayList<>(); String nextToken = null; do { ListLedgersRequest request = new ListLedgersRequest().withNextToken(nextToken); ListLedgersResult result = client.listLedgers(request); ledgerSummaries.addAll(result.getLedgers()); nextToken = result.getNextToken(); } while (nextToken != null);

List all ledgers in the current AWS account and Region.

Example

aws qldb list-ledgers