Amazon DynamoDB Client

DynamoDB is a scalable AWS managed NoSQL database. It supports both key-value and document data models, that enables to have a flexible schema for your data. This extension provides functionality that allows the client to communicate with the service when running in Quarkus. You can find more information about DynamoDB at the Amazon DynamoDB website.

The DynamoDB extension is based on AWS Java SDK 2.x. It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async).

The Quarkus extension supports the traditional DynamoDB client as well as the enhanced client.

It supports two programming models:

  • Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client

  • Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client

In this guide, we see how you can get your REST services to use the DynamoDB locally and on AWS.

Prerequisites

To complete this guide, you need:

  • JDK 17+ installed with JAVA_HOME configured appropriately

  • an IDE

  • Apache Maven 3.8.1+

  • An AWS Account to access the DynamoDB service

  • Optionally, Docker for your system to run DynamoDB locally for testing purposes

Provision DynamoDB locally via Dev Services

The easiest way to start working with DynamoDB is to run a local instance using Dev Services.

Provision DynamoDB locally manually

You can also set up a local version of DynamoDB manually, first start a local instance as a container:

docker run --publish 4566:8000 amazon/dynamodb-local:1.19.0 -jar DynamoDBLocal.jar -inMemory -sharedDb

This starts a DynamoDB instance that is accessible on port 4566. You can check if it’s working with aws dynamodb list-tables --endpoint-url http://localhost:4566.

{
    "TableNames": []
}

You should see the output above in your terminal. That’s it, DynamoDB runs locally.

Have a look at the Setting Up DynamoDB Local guide for other options to run DynamoDB.

Set up Dynamodb on AWS

Before you can use the AWS SDKs with DynamoDB, you must get an AWS access key ID and secret access key. For more information, see Setting Up DynamoDB (Web Service).

We recommend to use the AWS CLI to provision the table:

Create the QuarkusFruits Table

aws dynamodb create-table --table-name QuarkusFruits \
                          --attribute-definitions AttributeName=fruitName,AttributeType=S \
                          --key-schema AttributeName=fruitName,KeyType=HASH \
                          --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1

Solution

The application built here allows to manage elements (fruits) stored in Amazon DynamoDB.

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the amazon-dynamodb-quickstart directory.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus.platform:quarkus-maven-plugin:3.15.0:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=amazon-dynamodb-quickstart \
    -DclassName="org.acme.dynamodb.FruitResource" \
    -Dpath="/fruits" \
    -Dextensions="resteasy-reactive-jackson,amazon-dynamodb"
cd amazon-dynamodb-quickstart

This command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and DynamoDB Client extensions. After this, the amazon-dynamodb extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.

Creating JSON REST service

In this example, we will create an application to manage a list of fruits. The example application will demonstrate the two programming models supported by the extension.

First, let’s create the Fruit bean as follows:

package org.acme.dynamodb;

import java.util.Map;
import java.util.Objects;

import io.quarkus.runtime.annotations.RegisterForReflection;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;

@RegisterForReflection
public class Fruit {

    private String name;
    private String description;

    public Fruit() {
    }

    public static Fruit from(Map<String, AttributeValue> item) {
        Fruit fruit = new Fruit();
        if (item != null && !item.isEmpty()) {
            fruit.setName(item.get(AbstractService.FRUIT_NAME_COL).s());
            fruit.setDescription(item.get(AbstractService.FRUIT_DESC_COL).s());
        }
        return fruit;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof Fruit)) {
            return false;
        }

        Fruit other = (Fruit) obj;

        return Objects.equals(other.name, this.name);
    }

    @Override
    public int hashCode() {
        return Objects.hash(this.name);
    }
}
The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.

Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the Map object provided by the DynamoDB client response.

Now create a org.acme.dynamodb.AbstractService that will consist of helper methods that prepare DynamoDB request objects for reading and adding items to the table.

package org.acme.dynamodb;

import java.util.HashMap;
import java.util.Map;

import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
import software.amazon.awssdk.services.dynamodb.model.ScanRequest;

public abstract class AbstractService {

    public final static String FRUIT_NAME_COL = "fruitName";
    public final static String FRUIT_DESC_COL = "fruitDescription";
    public final static String FRUIT_TABLE_NAME = "QuarkusFruits";

    protected ScanRequest scanRequest() {
        return ScanRequest.builder().tableName(FRUIT_TABLE_NAME)
                .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL).build();
    }

    protected PutItemRequest putRequest(Fruit fruit) {
        Map<String, AttributeValue> item = new HashMap<>();
        item.put(FRUIT_NAME_COL, AttributeValue.builder().s(fruit.getName()).build());
        item.put(FRUIT_DESC_COL, AttributeValue.builder().s(fruit.getDescription()).build());

        return PutItemRequest.builder()
                .tableName(FRUIT_TABLE_NAME)
                .item(item)
                .build();
    }

    protected GetItemRequest getRequest(String name) {
        Map<String, AttributeValue> key = new HashMap<>();
        key.put(FRUIT_NAME_COL, AttributeValue.builder().s(name).build());

        return GetItemRequest.builder()
                .tableName(FRUIT_TABLE_NAME)
                .key(key)
                .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL)
                .build();
    }
}

Then, create a org.acme.dynamodb.FruitSyncService that will be the business layer of our application and stores/loads the fruits from DynamoDB using the synchronous client.

package org.acme.dynamodb;

import java.util.List;
import java.util.stream.Collectors;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

@ApplicationScoped
public class FruitSyncService extends AbstractService {

    @Inject
    DynamoDbClient dynamoDB;

    public List<Fruit> findAll() {
        return dynamoDB.scanPaginator(scanRequest()).items().stream()
                .map(Fruit::from)
                .collect(Collectors.toList());
    }

    public void add(Fruit fruit) {
        dynamoDB.putItem(putRequest(fruit));
    }

    public Fruit get(String name) {
        return Fruit.from(dynamoDB.getItem(getRequest(name)).item());
    }
}

Now, edit the org.acme.dynamodb.FruitResource class as follows:

package org.acme.dynamodb;

import java.util.List;

import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/fruits")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class FruitResource {

    @Inject
    FruitSyncService service;

    @GET
    public List<Fruit> getAll() {
        return service.findAll();
    }

    @GET
    @Path("{name}")
    public Fruit getSingle(String name) {
        return service.get(name);
    }

    @POST
    public List<Fruit> add(Fruit fruit) {
        service.add(fruit);
        return getAll();
    }
}

The implementation is pretty straightforward and you just need to define your endpoints using the JAX-RS annotations and use the FruitSyncService to list/add new fruits.

Configuring DynamoDB clients

DynamoDB clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory. Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the java.net.URLConnection HTTP client, so you need to add a URL connection client dependency to the pom.xml file:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>url-connection-client</artifactId>
</dependency>

If you want to use the Apache HTTP client instead, configure it as follows:

quarkus.dynamodb.sync-client.type=apache

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>apache-client</artifactId>
</dependency>

If you want to use the AWS CRT-based HTTP client instead, configure it as follows:

quarkus.dynamodb.sync-client.type=aws-crt

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>aws-crt-client</artifactId>
</dependency>

If you’re going to use a local DynamoDB instance, configure it as follows:

quarkus.dynamodb.endpoint-override=http://localhost:4566

quarkus.dynamodb.aws.region=eu-central-1
quarkus.dynamodb.aws.credentials.type=static
quarkus.dynamodb.aws.credentials.static-provider.access-key-id=test-key
quarkus.dynamodb.aws.credentials.static-provider.secret-access-key=test-secret
  • quarkus.dynamodb.aws.region - It’s required by the client, but since you’re using a local DynamoDB instance you can pick any valid AWS region.

  • quarkus.dynamodb.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key

  • quarkus.dynamodb.endpoint-override - Override the DynamoDB client to use a local instance instead of an AWS service

If you want to work with an AWS account, you’d need to set it with:

quarkus.dynamodb.aws.region=<YOUR_REGION>
quarkus.dynamodb.aws.credentials.type=default
  • quarkus.dynamodb.aws.region you should set it to the region where you provisioned the DynamoDB table,

  • quarkus.dynamodb.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:

    • Java System Properties - aws.accessKeyId and aws.secretAccessKey

    • Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

    • Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI

    • Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,

    • Instance profile credentials delivered through the Amazon EC2 metadata service

Next steps

Packaging

Packaging your application is as simple as ./mvnw clean package. It can be run with java -jar target/quarkus-app/quarkus-run.jar.

With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative. Depending on your system, that will take some time.

Going asynchronous

Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.

Create a org.acme.dynamodb.FruitAsyncService that will be similar to our FruitSyncService but using an asynchronous programming model.

package org.acme.dynamodb;

import java.util.List;
import java.util.stream.Collectors;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import io.smallrye.mutiny.Uni;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;

@ApplicationScoped
public class FruitAsyncService extends AbstractService {

    @Inject
    DynamoDbAsyncClient dynamoDB;

    public Uni<List<Fruit>> findAll() {
        return Uni.createFrom().completionStage(() -> dynamoDB.scan(scanRequest()))
                .onItem().transform(res -> res.items().stream().map(Fruit::from).collect(Collectors.toList()));
    }

    public Uni<Void> add(Fruit fruit) {
        return Uni.createFrom().completionStage(() -> dynamoDB.putItem(putRequest(fruit))).replaceWithVoid();
    }

    public Uni<Fruit> get(String name) {
        return Uni.createFrom().completionStage(() -> dynamoDB.getItem(getRequest(name)))
                .onItem().transform(resp -> Fruit.from(resp.item()));
    }
}

In the previous code, we create Uni instances from the CompletionStage objects returned by the asynchronous DynamoDB client, and then transform the emitted item.

Then, create an asynchronous REST resource that consumes this async service:

package org.acme.dynamodb;

import java.util.List;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;

import io.smallrye.mutiny.Uni;

@Path("/async-fruits")
public class FruitAsyncResource {

    @Inject
    FruitAsyncService service;

    @GET
    public Uni<List<Fruit>> getAll() {
        return service.findAll();
    }

    @GET
    @Path("{name}")
    public Uni<Fruit> getSingle(String name) {
        return service.get(name);
    }

    @POST
    public Uni<List<Fruit>> add(Fruit fruit) {
        return service.add(fruit)
                .onItem().ignore().andSwitchTo(this::getAll);
    }
}

And add Netty HTTP client dependency to the pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>netty-nio-client</artifactId>
</dependency>

If you want to use the AWS CRT-based HTTP client instead, configure it as follows:

quarkus.dynamodb.async-client.type=aws-crt

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>aws-crt-client</artifactId>
</dependency>

DynamoDB enhanced client

The DynamoDB enhanced client is part of the AWS SDK for Java version 2 and makes the mapping between DynamoDB Tables and Java beans very easy. The Enhanced Client requires a TableSchema which can be generated from a bean class annotated with DynamoDbBean or DynamoDbImmutable or generated from code. By default, TableSchemas generated from bean classes are registered and cached at startup. You don’t need to explicitely instantiate them at class-load time. It has both a sync and an async variants.

To use the enhanced client, add the quarkus-amazon-dynamodb-enhanced extension to your pom.xml:

<dependency>
    <groupId>io.quarkiverse.amazonservices</groupId>
    <artifactId>quarkus-amazon-dynamodb-enhanced</artifactId>
</dependency>

The Fruit bean would look like this:

package org.acme.dynamodb;

import java.util.Map;
import java.util.Objects;

import io.quarkus.runtime.annotations.RegisterForReflection;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbAttribute;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;

@RegisterForReflection
@DynamoDbBean
public class Fruit {

    private String name;
    private String description;

    public Fruit() {
    }

    @DynamoDbPartitionKey
    @DynamoDbAttribute(AbstractService.FRUIT_NAME_COL)
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @DynamoDbAttribute(AbstractService.FRUIT_DESC_COL)
    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof Fruit)) {
            return false;
        }

        Fruit other = (Fruit) obj;

        return Objects.equals(other.name, this.name);
    }

    @Override
    public int hashCode() {
        return Objects.hash(this.name);
    }
}

Note that you don’t need to add @RegisterForReflection anymore.

The FruitSyncService would need to use the DynamoDbEnhancedClient as well as create a TableSchema:

package org.acme.dynamodb;

import java.util.List;
import java.util.stream.Collectors;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;

@ApplicationScoped
public class FruitSyncService extends AbstractService {

    private DynamoDbTable<Fruit> fruitTable;

    @Inject
    FruitEnhancedSyncService(DynamoDbEnhancedClient dynamoEnhancedClient) {
        fruitTable = dynamoEnhancedClient.table(FRUIT_TABLE_NAME,
            TableSchema.fromClass(Fruit.class));
    }

    public List<Fruit> findAll() {
        return fruitTable.scan().items().stream().collect(Collectors.toList());
    }

    public List<Fruit> add(Fruit fruit) {
        fruitTable.putItem(fruit);
        return findAll();
    }

    public Fruit get(String name) {
        Key partitionKey = Key.builder().partitionValue(name).build();
        return fruitTable.getItem(partitionKey);
    }
}

The same goes for the asynchronous version with DynamoDbEnhanceAsyncdClient:

package org.acme.dynamodb;

import java.util.List;
import java.util.stream.Collectors;

import io.smallrye.mutiny.Multi;
import io.smallrye.mutiny.Uni;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import mutiny.zero.flow.adapters.AdaptersToFlow;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;

@ApplicationScoped
public class FruitAsyncService extends AbstractService {

    private DynamoDbAsyncTable<Fruit> fruitTable;

    @Inject
    FruitEnhancedAsyncService(DynamoDbEnhancedAsyncClient dynamoEnhancedAsyncClient) {
        fruitTable = dynamoEnhancedAsyncClient.table(FRUIT_TABLE_NAME,
            TableSchema.fromClass(Fruit.class));
    }

    public Uni<List<Fruit>> findAll() {
        return Multi.createFrom().publisher(AdaptersToFlow.publisher(fruitTable.scan().items())).collect().asList();
    }

    public Uni<Void> add(Fruit fruit){
        return Uni.createFrom().completionStage(() -> fruitTable.putItem(fruit));
}

    public Uni<Fruit> get(String name) {
        Key partitionKey = Key.builder().partitionValue(name).build();
        return Uni.createFrom().completionStage(() -> fruitTable.getItem(partitionKey));
    }
}

Resource classes remain unchanged.

Alternatively, if you only need to use the DynamoDbTable instance, you can inject it directly with a @NamedDynamoDbTable annotation.

The synchronous version would be :

package org.acme.dynamodb;

import java.util.List;
import java.util.stream.Collectors;

import io.quarkus.amazon.dynamodb.enhanced.runtime.NamedDynamoDbTable;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.Key;

@ApplicationScoped
public class FruitSyncService extends AbstractService {

    @Inject
    @NamedDynamoDbTable(FRUIT_TABLE_NAME)
    DynamoDbTable<Fruit> fruitTable;

    public List<Fruit> findAll() {
        return fruitTable.scan().items().stream().collect(Collectors.toList());
    }

    public List<Fruit> add(Fruit fruit) {
        fruitTable.putItem(fruit);
        return findAll();
    }

    public Fruit get(String name) {
        Key partitionKey = Key.builder().partitionValue(name).build();
        return fruitTable.getItem(partitionKey);
    }
}

And the asynchronous version :

package org.acme.dynamodb;

import java.util.List;

import io.quarkus.amazon.dynamodb.enhanced.runtime.NamedDynamoDbTable;
import io.smallrye.mutiny.Multi;
import io.smallrye.mutiny.Uni;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import mutiny.zero.flow.adapters.AdaptersToFlow;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;

@ApplicationScoped
public class FruitEnhancedAsyncService extends AbstractService {

    @Inject
    @NamedDynamoDbTable(FRUIT_TABLE_NAME)
    private DynamoDbAsyncTable<Fruit> fruitTable;

    public Uni<List<Fruit>> findAll() {
        return Multi.createFrom().publisher(AdaptersToFlow.publisher(fruitTable.scan().items())).collect().asList();
    }

    public Uni<Void> add(Fruit fruit){
        return Uni.createFrom().completionStage(() -> fruitTable.putItem(fruit));
}

    public Uni<Fruit> get(String name) {
        Key partitionKey = Key.builder().partitionValue(name).build();
        return Uni.createFrom().completionStage(() -> fruitTable.getItem(partitionKey));
    }
}

You can find more information about the DynamoDB enhanced client in the AWS documentation:

Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.

The list should consists of class names which implements software.amazon.awssdk.core.interceptor.ExecutionInterceptor interface. Classes will be attempted to be loaded via CDI first, and if no CDI beans are available, then the constructor with no parameters will be invoked to instantiate each class.

Environment variable: QUARKUS_DYNAMODB_INTERCEPTORS

list of string

OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true.

Environment variable: QUARKUS_DYNAMODB_TELEMETRY_ENABLED

boolean

false

Type of the sync HTTP client implementation

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TYPE

url, apache, aws-crt

url

Type of the async HTTP client implementation

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TYPE

netty, aws-crt

netty

If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto

Environment variable: QUARKUS_DYNAMODB_DEVSERVICES_ENABLED

boolean

Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.

The discovery uses the quarkus-dev-service-localstack label. The value is configured using the service-name property.

Sharing is not supported for the Cognito extension.

Environment variable: QUARKUS_DYNAMODB_DEVSERVICES_SHARED

boolean

false

Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the quarkus-dev-service-localstack label will be suffixed by the service name (s3, sqs, …​)

Environment variable: QUARKUS_DYNAMODB_DEVSERVICES_ISOLATED

boolean

true

The value of the quarkus-dev-service-localstack label attached to the started container. In dev mode, when shared is set to true, before starting a container, Dev Services looks for a container with the quarkus-dev-service-localstack label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise it starts a new container with the quarkus-dev-service-localstack label set to the specified value. In test mode, Dev Services will group services with the same service-name value in one container instance.

This property is used when you need multiple shared LocalStack instances.

Environment variable: QUARKUS_DYNAMODB_DEVSERVICES_SERVICE_NAME

string

localstack

Enable DynamoDB service endpoint discovery.

Environment variable: QUARKUS_DYNAMODB_ENABLE_ENDPOINT_DISCOVERY

boolean

false

Generic properties that are pass for additional container configuration.

Environment variable: QUARKUS_DYNAMODB_DEVSERVICES_CONTAINER_PROPERTIES__CONTAINER_PROPERTIES_

String

AWS SDK client configurations

Type

Default

The endpoint URI with which the SDK should communicate.

If not specified, an appropriate endpoint to be used for the given service and region.

Environment variable: QUARKUS_DYNAMODB_ENDPOINT_OVERRIDE

URI

The amount of time to allow the client to complete the execution of an API call.

This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc.

This value should always be positive, if present.

Environment variable: QUARKUS_DYNAMODB_API_CALL_TIMEOUT

Duration

The amount of time to wait for the HTTP request to complete before giving up and timing out.

This value should always be positive, if present.

Environment variable: QUARKUS_DYNAMODB_API_CALL_ATTEMPT_TIMEOUT

Duration

Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task.

When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools.

Environment variable: QUARKUS_DYNAMODB_ADVANCED_USE_QUARKUS_SCHEDULED_EXECUTOR_SERVICE

boolean

true

AWS services configurations

Type

Default

An Amazon Web Services region that hosts the given service.

It overrides region provider chain with static value of region with which the service client should communicate.

If not set, region is retrieved via the default providers chain in the following order:

  • aws.region system property

  • region property from the profile file

  • Instance profile file

See software.amazon.awssdk.regions.Region for available regions.

Environment variable: QUARKUS_DYNAMODB_AWS_REGION

Region

Configure the credentials provider that should be used to authenticate with AWS.

Available values:

  • default - the provider will attempt to identify the credentials automatically using the following checks:

    • Java System Properties - aws.accessKeyId and aws.secretAccessKey

    • Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

    • Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI

    • Credentials delivered through the Amazon EC2 container service if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and security manager has permission to access the variable.

    • Instance profile credentials delivered through the Amazon EC2 metadata service

  • static - the provider that uses the access key and secret access key specified in the static-provider section of the config.

  • system-property - it loads credentials from the aws.accessKeyId, aws.secretAccessKey and aws.sessionToken system properties.

  • env-variable - it loads credentials from the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN environment variables.

  • profile - credentials are based on AWS configuration profiles. This loads credentials from a profile file, allowing you to share multiple sets of AWS security credentials between different tools like the AWS SDK for Java and the AWS CLI.

  • container - It loads credentials from a local metadata service. Containers currently supported by the AWS SDK are Amazon Elastic Container Service (ECS) and AWS Greengrass

  • instance-profile - It loads credentials from the Amazon EC2 Instance Metadata Service.

  • process - Credentials are loaded from an external process. This is used to support the credential_process setting in the profile credentials file. See Sourcing Credentials From External Processes for more information.

  • anonymous - It always returns anonymous AWS credentials. Anonymous AWS credentials result in un-authenticated requests and will fail unless the resource or API’s policy has been configured to specifically allow anonymous access.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_TYPE

default, static, system-property, env-variable, profile, container, instance-profile, process, custom, anonymous

default

Default credentials provider configuration

Type

Default

Whether this provider should fetch credentials asynchronously in the background.

If this is true, threads are less likely to block, but additional resources are used to maintain the provider.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_DEFAULT_PROVIDER_ASYNC_CREDENTIAL_UPDATE_ENABLED

boolean

false

Whether the provider should reuse the last successful credentials provider in the chain.

Reusing the last successful credentials provider will typically return credentials faster than searching through the chain.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_DEFAULT_PROVIDER_REUSE_LAST_PROVIDER_ENABLED

boolean

true

Static credentials provider configuration

Type

Default

AWS Access key id

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_STATIC_PROVIDER_ACCESS_KEY_ID

string

AWS Secret access key

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_STATIC_PROVIDER_SECRET_ACCESS_KEY

string

AWS Session token

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_STATIC_PROVIDER_SESSION_TOKEN

string

AWS Profile credentials provider configuration

Type

Default

The name of the profile that should be used by this credentials provider.

If not specified, the value in AWS_PROFILE environment variable or aws.profile system property is used and defaults to default name.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_PROFILE_PROVIDER_PROFILE_NAME

string

Process credentials provider configuration

Type

Default

Whether the provider should fetch credentials asynchronously in the background.

If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_PROCESS_PROVIDER_ASYNC_CREDENTIAL_UPDATE_ENABLED

boolean

false

The amount of time between when the credentials expire and when the credentials should start to be refreshed.

This allows the credentials to be refreshed *before* they are reported to expire.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_PROCESS_PROVIDER_CREDENTIAL_REFRESH_THRESHOLD

Duration

15S

The maximum size of the output that can be returned by the external process before an exception is raised.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_PROCESS_PROVIDER_PROCESS_OUTPUT_LIMIT

MemorySize

1024

The command that should be executed to retrieve credentials.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_PROCESS_PROVIDER_COMMAND

string

Custom credentials provider configuration

Type

Default

The name of custom AwsCredentialsProvider bean.

Environment variable: QUARKUS_DYNAMODB_AWS_CREDENTIALS_CUSTOM_PROVIDER_NAME

string

Sync HTTP transport configurations

Type

Default

The maximum amount of time to establish a connection before timing out.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_CONNECTION_TIMEOUT

Duration

2S

The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_SOCKET_TIMEOUT

Duration

30S

TLS key managers provider type.

Available providers:

  • none - Use this provider if you don’t want the client to present any certificates to the remote TLS host.

  • system-property - Provider checks the standard javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword, and javax.net.ssl.keyStoreType properties defined by the JSSE.

  • file-store - Provider that loads the key store from a file.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_TYPE

none, system-property, file-store

system-property

Path to the key store.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_PATH

path

Key store type.

See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_TYPE

string

Key store password

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_PASSWORD

string

TLS trust managers provider type.

Available providers:

  • trust-all - Use this provider to disable the validation of servers certificates and therefore trust all server certificates.

  • system-property - Provider checks the standard javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword, and javax.net.ssl.keyStoreType properties defined by the JSSE.

  • file-store - Provider that loads the key store from a file.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_TYPE

trust-all, system-property, file-store

system-property

Path to the key store.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_PATH

path

Key store type.

See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_TYPE

string

Key store password

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_PASSWORD

string

Apache HTTP client specific configurations

Type

Default

The amount of time to wait when acquiring a connection from the pool before giving up and timing out.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_CONNECTION_ACQUISITION_TIMEOUT

Duration

10S

The maximum amount of time that a connection should be allowed to remain open while idle.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_CONNECTION_MAX_IDLE_TIME

Duration

60S

The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_CONNECTION_TIME_TO_LIVE

Duration

The maximum number of connections allowed in the connection pool.

Each built HTTP client has its own private connection pool.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_MAX_CONNECTIONS

int

50

Whether the client should send an HTTP expect-continue handshake before each request.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_EXPECT_CONTINUE_ENABLED

boolean

true

Whether the idle connections in the connection pool should be closed asynchronously.

When enabled, connections left idling for longer than quarkus..sync-client.connection-max-idle-time will be closed. This will not close connections currently in use.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_USE_IDLE_CONNECTION_REAPER

boolean

true

Configure whether to enable or disable TCP KeepAlive.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_TCP_KEEP_ALIVE

boolean

false

Enable HTTP proxy

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_PROXY_ENABLED

boolean

false

The endpoint of the proxy server that the SDK should connect through.

Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_PROXY_ENDPOINT

URI

The username to use when connecting through a proxy.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_PROXY_USERNAME

string

The password to use when connecting through a proxy.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_PROXY_PASSWORD

string

For NTLM proxies - the Windows domain name to use when authenticating with the proxy.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_PROXY_NTLM_DOMAIN

string

For NTLM proxies - the Windows workstation name to use when authenticating with the proxy.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_PROXY_NTLM_WORKSTATION

string

Whether to attempt to authenticate preemptively against the proxy server using basic authentication.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_PROXY_PREEMPTIVE_BASIC_AUTHENTICATION_ENABLED

boolean

The hosts that the client is allowed to access without going through the proxy.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_APACHE_PROXY_NON_PROXY_HOSTS

list of string

AWS CRT-based HTTP client specific configurations

Type

Default

The maximum amount of time that a connection should be allowed to remain open while idle.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_CRT_CONNECTION_MAX_IDLE_TIME

Duration

60S

The maximum number of allowed concurrent requests.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_CRT_MAX_CONCURRENCY

int

50

Enable HTTP proxy

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_CRT_PROXY_ENABLED

boolean

false

The endpoint of the proxy server that the SDK should connect through.

Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_CRT_PROXY_ENDPOINT

URI

The username to use when connecting through a proxy.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_CRT_PROXY_USERNAME

string

The password to use when connecting through a proxy.

Environment variable: QUARKUS_DYNAMODB_SYNC_CLIENT_CRT_PROXY_PASSWORD

string

Async HTTP transport configurations

Type

Default

The maximum number of allowed concurrent requests.

For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_MAX_CONCURRENCY

int

50

The maximum number of pending acquires allowed.

Once this exceeds, acquire tries will be failed.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_MAX_PENDING_CONNECTION_ACQUIRES

int

10000

The amount of time to wait for a read on a socket before an exception is thrown.

Specify 0 to disable.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_READ_TIMEOUT

Duration

30S

The amount of time to wait for a write on a socket before an exception is thrown.

Specify 0 to disable.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_WRITE_TIMEOUT

Duration

30S

The amount of time to wait when initially establishing a connection before giving up and timing out.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_CONNECTION_TIMEOUT

Duration

10S

The amount of time to wait when acquiring a connection from the pool before giving up and timing out.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_CONNECTION_ACQUISITION_TIMEOUT

Duration

2S

The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_CONNECTION_TIME_TO_LIVE

Duration

The maximum amount of time that a connection should be allowed to remain open while idle.

Currently has no effect if quarkus..async-client.use-idle-connection-reaper is false.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_CONNECTION_MAX_IDLE_TIME

Duration

5S

Whether the idle connections in the connection pool should be closed.

When enabled, connections left idling for longer than quarkus..async-client.connection-max-idle-time will be closed. This will not close connections currently in use.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_USE_IDLE_CONNECTION_REAPER

boolean

true

Configure whether to enable or disable TCP KeepAlive.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TCP_KEEP_ALIVE

boolean

false

The HTTP protocol to use.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_PROTOCOL

http1-1, http2

http1-1

The SSL Provider to be used in the Netty client.

Default is OPENSSL if available, JDK otherwise.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_SSL_PROVIDER

jdk, openssl, openssl-refcnt

The maximum number of concurrent streams for an HTTP/2 connection.

This setting is only respected when the HTTP/2 protocol is used.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_HTTP2_MAX_STREAMS

long

4294967295

The initial window size for an HTTP/2 stream.

This setting is only respected when the HTTP/2 protocol is used.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_HTTP2_INITIAL_WINDOW_SIZE

int

1048576

Sets the period that the Netty client will send PING frames to the remote endpoint to check the health of the connection. To disable this feature, set a duration of 0.

This setting is only respected when the HTTP/2 protocol is used.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_HTTP2_HEALTH_CHECK_PING_PERIOD

Duration

5

Enable HTTP proxy.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_PROXY_ENABLED

boolean

false

The endpoint of the proxy server that the SDK should connect through.

Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_PROXY_ENDPOINT

URI

The hosts that the client is allowed to access without going through the proxy.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_PROXY_NON_PROXY_HOSTS

list of string

TLS key managers provider type.

Available providers:

  • none - Use this provider if you don’t want the client to present any certificates to the remote TLS host.

  • system-property - Provider checks the standard javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword, and javax.net.ssl.keyStoreType properties defined by the JSSE.

  • file-store - Provider that loads the key store from a file.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_TYPE

none, system-property, file-store

system-property

Path to the key store.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_PATH

path

Key store type.

See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_TYPE

string

Key store password

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_PASSWORD

string

TLS trust managers provider type.

Available providers:

  • trust-all - Use this provider to disable the validation of servers certificates and therefore trust all server certificates.

  • system-property - Provider checks the standard javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword, and javax.net.ssl.keyStoreType properties defined by the JSSE.

  • file-store - Provider that loads the key store from a file.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_TYPE

trust-all, system-property, file-store

system-property

Path to the key store.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_PATH

path

Key store type.

See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_TYPE

string

Key store password

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_PASSWORD

string

Enable the custom configuration of the Netty event loop group.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_EVENT_LOOP_OVERRIDE

boolean

false

Number of threads to use for the event loop group.

If not set, the default Netty thread count is used (which is double the number of available processors unless the io.netty.eventLoopThreads system property is set.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_EVENT_LOOP_NUMBER_OF_THREADS

int

The thread name prefix for threads created by this thread factory used by event loop group.

The prefix will be appended with a number unique to the thread factory and a number unique to the thread.

If not specified it defaults to aws-java-sdk-NettyEventLoop

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_EVENT_LOOP_THREAD_NAME_PREFIX

string

Whether the default thread pool should be used to complete the futures returned from the HTTP client request.

When disabled, futures will be completed on the Netty event loop thread.

Environment variable: QUARKUS_DYNAMODB_ASYNC_CLIENT_ADVANCED_USE_FUTURE_COMPLETION_THREAD_POOL

boolean

true

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.

About the MemorySize format

A size configuration option recognises string in this format (shown as a regular expression): [0-9]+[KkMmGgTtPpEeZzYy]?. If no suffix is given, assume bytes.

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

List of extensions to load with the enhanced client.

The list should consists of class names which implements software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClientExtension interface.

Environment variable: QUARKUS_DYNAMODBENHANCED_CLIENT_EXTENSIONS

list of string

Whether a TableSchema should be created at start up for DynamoDb mappable entities annotated with DynamoDbBean or DynamoDbImmutable

TableSchema are cached and can be retrieved later with TableSchema.fromClass()

Environment variable: QUARKUS_DYNAMODBENHANCED_CREATE_TABLE_SCHEMAS

boolean

true