Basic operations for Amazon QLDB ledgers - Amazon Quantum Ledger Database (Amazon QLDB)
Creating a ledgerDescribing a ledgerUpdating a ledgerUpdating a ledger permissions modeDeleting a ledgerListing ledgers

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 topics provide short code examples that show common steps for ledger operations using the AWS SDK for Java and the AWS CLI.

For code examples that demonstrate these operations in a complete sample application, see the following Getting started with the driver tutorials and GitHub repositories:

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.

    Naming constraints for ledger names are defined in Quotas and limits in Amazon QLDB.

  • Permissions mode – The permissions mode to assign to the ledger. Choose one of the following options:

    • Allow all – A legacy permissions mode that enables access control with API-level granularity for ledgers.

      This mode allows users who have the SendCommand API permission for this ledger to run all PartiQL commands (hence, ALLOW_ALL) on any tables in the specified ledger. This mode disregards any table-level or command-level IAM permissions policies that you create for the ledger.

    • Standard – (Recommended) A permissions mode that enables access control with finer granularity for ledgers, tables, and PartiQL commands. We strongly recommend using this permissions mode to maximize the security of your ledger data.

      By default, this mode denies all requests to run any PartiQL commands on any tables in this ledger. To allow PartiQL commands, you must create IAM permissions policies for specific table resources and PartiQL actions, in addition to the SendCommand API permission for the ledger. For information, see Getting started with the standard permissions mode in Amazon QLDB.

  • Deletion protection – (Optional) The flag that prevents a ledger from being deleted by any user. If you don't specify it during 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. You can disable it by using the UpdateLedger operation to set the flag to false.

  • AWS KMS key – (Optional) The key in AWS Key Management Service (AWS KMS) to use for encryption of data at rest. Choose one of the following types of AWS KMS keys:

    • AWS owned KMS key – Use a KMS key that is owned and managed by AWS on your behalf.

      If you don't define this parameter during ledger creation, the ledger uses this type of key by default. You can also use the string AWS_OWNED_KMS_KEY to specify this key type. This option requires no additional setup.

    • Customer managed KMS key – Use a symmetric encryption KMS key in your account that you create, own, and manage. QLDB doesn't support asymmetric keys.

      This option requires you to create a KMS key or use an existing key in your account. For instructions on creating a customer managed key, see Creating symmetric encryption KMS keys in the AWS Key Management Service Developer Guide.

      You can specify a customer managed KMS key by using an ID, alias, or Amazon Resource Name (ARN). To learn more, see Key identifiers (KeyId) in the AWS Key Management Service Developer Guide.

      Note

      Cross-Region keys are not supported. The specified KMS key must be in the same AWS Region as your ledger.

    For more information, see Encryption at rest in Amazon QLDB.

  • 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 isn't 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. Run 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 – Use default configuration settings
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
CreateLedgerRequest request = new CreateLedgerRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD);
CreateLedgerResult result = client.createLedger(request);
Note

The ledger uses the following default settings if you don't specify them:

  • Deletion protection – Enabled (true).

  • KMS key – AWS owned KMS key.

Example – Disable deletion protection, use a customer managed KMS key, and attach 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.STANDARD)
        .withDeletionProtection(false)
        .withKmsKey("arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
        .withTags(tags);
CreateLedgerResult result = client.createLedger(request);

Create a new ledger named vehicle-registration using default configuration settings.

Example 
aws qldb create-ledger --name vehicle-registration --permissions-mode STANDARD
Note

The ledger uses the following default settings if you don't specify them:

  • Deletion protection – Enabled (true).

  • KMS key – AWS owned KMS key.

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

Example 
aws qldb create-ledger \
    --name vehicle-registration \
    --no-deletion-protection \
    --permissions-mode STANDARD \
    --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --tags IsTest=true,Domain=Test

You can also use an AWS CloudFormation template to create ledgers. For more information, see the AWS::QLDB::Ledger resource in the AWS CloudFormation User Guide.

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

    • DELETED

  • Permissions mode – The permissions mode that is assigned to the ledger. This can be one of the following values:

    • ALLOW_ALL – A legacy permissions mode that enables access control with API-level granularity for ledgers.

    • STANDARD – A permissions mode that enables access control with finer granularity for ledgers, tables, and PartiQL commands.

  • Encryption description – Information about the encryption of data at rest in the ledger. This includes the following items:

    • AWS KMS key ARN – The ARN of the customer managed KMS key that the ledger uses for encryption at rest. If this is undefined, the ledger uses an AWS owned KMS key for encryption.

    • Encryption status – The current status of encryption at rest for the ledger. This can be one of the following values:

      • ENABLED – Encryption is fully enabled using the specified key.

      • UPDATING – The specified key change is actively being processed.

        Key changes in QLDB are asynchronous. The ledger is fully accessible without any performance impact while the key change is being processed. The amount of time it takes to update a key varies depending on the ledger size.

      • KMS_KEY_INACCESSIBLE – The specified customer managed KMS key is not accessible, and the ledger is impaired. Either the key was disabled or deleted, or the grants on the key were revoked. When a ledger is impaired, it's not accessible and doesn't accept any read or write requests.

        An impaired ledger automatically returns to an active state after you restore the grants on the key, or after you reenable the key that was disabled. However, deleting a customer managed KMS key is irreversible. After a key is deleted, you can no longer access the ledgers that are protected with that key, and the data becomes unrecoverable permanently.

    • Inaccessible AWS KMS key – The date and time, in epoch time format, when the KMS key first became inaccessible, in the case of an error.

      This is undefined if the KMS key is accessible.

    For more information, see Encryption at rest in Amazon QLDB.

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. Run 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
                   \t PermissionsMode: %s \t EncryptionDescription: %s",
        result.getName(),
        result.getArn(),
        result.getState(),
        result.getCreationDateTime(),
        result.getDeletionProtection(),
        result.getPermissionsMode(),
        result.getEncryptionDescription());

Describe the vehicle-registration ledger that you just created.

Example 
aws qldb describe-ledger --name vehicle-registration

Updating a ledger

The UpdateLedger operation currently lets you change the following configuration settings for an existing ledger:

  • Deletion protection – The flag that prevents a ledger from being deleted by any user. If this feature is enabled, you must first disable it by setting the flag to false before you can delete the ledger.

    If you don't define this parameter, no changes are made to the deletion protection setting of the ledger.

  • AWS KMS key – The key in AWS Key Management Service (AWS KMS) to use for encryption of data at rest. If you don't define this parameter, no changes are made to the KMS key of the ledger.

    Note

    Amazon QLDB launched support for customer managed AWS KMS keys on July 22, 2021. Any ledgers that were created before the launch are protected by AWS owned keys by default, but are currently not eligible for encryption at rest using customer managed keys.

    You can view the creation time of your ledger on the QLDB console.

    Use one of the following options:

    • AWS owned KMS key – Use a KMS key that is owned and managed by AWS on your behalf. To use this type of key, specify the string AWS_OWNED_KMS_KEY for this parameter. This option requires no additional setup.

    • Customer managed KMS key – Use a symmetric encryption KMS key in your account that you create, own, and manage. QLDB doesn't support asymmetric keys.

      This option requires you to create a KMS key or use an existing key in your account. For instructions on creating a customer managed key, see Creating symmetric encryption KMS keys in the AWS Key Management Service Developer Guide.

      You can specify a customer managed KMS key by using an ID, alias, or Amazon Resource Name (ARN). To learn more, see Key identifiers (KeyId) in the AWS Key Management Service Developer Guide.

      Note

      Cross-Region keys are not supported. The specified KMS key must be in the same AWS Region as your ledger.

    Key changes in QLDB are asynchronous. The ledger is fully accessible without any performance impact while the key change is being processed.

    You can switch keys as often as necessary, but the amount of time it takes to update a key varies depending on the ledger size. You can use the DescribeLedger operation to check the encryption at rest status.

    For more information, see Encryption at rest in Amazon QLDB.

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 along with a new Boolean value for deletion protection or a new string value for the KMS key.

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

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

Example – Disable deletion protection
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withDeletionProtection(false);
UpdateLedgerResult result = client.updateLedger(request);
Example – Use a customer managed KMS key
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withKmsKey("arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
UpdateLedgerResult result = client.updateLedger(request);
Example – Use an AWS owned KMS key
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withKmsKey("AWS_OWNED_KMS_KEY")
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

You can also change the ledger's encryption at rest settings to use a customer managed KMS key.

Example 
aws qldb update-ledger --name vehicle-registration --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

Or, you can change the encryption at rest settings to use an AWS owned KMS key.

Example 
aws qldb update-ledger --name vehicle-registration --kms-key AWS_OWNED_KMS_KEY

Updating a ledger permissions mode

The UpdateLedgerPermissionsMode operation lets you change the permissions mode of an existing ledger. Choose one of the following options:

  • Allow all – A legacy permissions mode that enables access control with API-level granularity for ledgers.

    This mode allows users who have the SendCommand API permission for this ledger to run all PartiQL commands (hence, ALLOW_ALL) on any tables in the specified ledger. This mode disregards any table-level or command-level IAM permissions policies that you create for the ledger.

  • Standard – (Recommended) A permissions mode that enables access control with finer granularity for ledgers, tables, and PartiQL commands. We strongly recommend using this permissions mode to maximize the security of your ledger data.

    By default, this mode denies all requests to run any PartiQL commands on any tables in this ledger. To allow PartiQL commands, you must create IAM permissions policies for specific table resources and PartiQL actions, in addition to the SendCommand API permission for the ledger. For information, see Getting started with the standard permissions mode in Amazon QLDB.

Important

Before switching to the STANDARD permissions mode, you must first create all required IAM policies and table tags to avoid disruption to your users. To learn more, proceed to Migrating to the standard permissions mode.

To update a ledger permissions mode using the AWS SDK for Java

  1. Create an instance of the AmazonQLDB class.

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

    You must provide the ledger name along with a new string value for the permissions mode.

  3. Run the updateLedgerPermissionsMode method by providing the request object as a parameter.

The following code examples demonstrate the preceding steps. The updateLedgerPermissionsMode request returns an UpdateLedgerPermissionsModeResult object that has updated information about the ledger.

Example – Assign the standard permissions mode
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerPermissionsModeRequest request = new UpdateLedgerPermissionsModeRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD);
UpdateLedgerPermissionsModeResult result = client.updateLedgerPermissionsMode(request);

Assign the STANDARD permissions mode to your vehicle-registration ledger.

Example 
aws qldb update-ledger-permissions-mode --name vehicle-registration --permissions-mode STANDARD

Migrating to the standard permissions mode

To migrate to the STANDARD permissions mode, we recommend analyzing your QLDB access patterns and adding IAM policies that grant your users the appropriate permissions to access their resources.

Before switching to the STANDARD permissions mode, you must first create all required IAM policies and table tags. Otherwise, switching the permissions mode can disrupt users until you either create the correct IAM policies, or revert the permissions mode back to ALLOW_ALL. For information about creating these policies, see Getting started with the standard permissions mode in Amazon QLDB.

You can also use an AWS managed policy to grant full access to all QLDB resources. The AmazonQLDBFullAccess and AmazonQLDBConsoleFullAccess managed policies include all QLDB actions, including all PartiQL actions. Attaching one of these policies to a principal is equivalent to the ALLOW_ALL permissions mode for that principal. For more information, see AWS managed policies for Amazon QLDB.

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.

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. Run 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 to get the next page of results.

  3. Run 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