DynamoDbModule groups the DynamoDB tasks under AWS Emulator - DynamoDB. Each task selects a managed or development runtime.
For declarative JSON item imports and clearing items while preserving a table, see DynamoDB data fixtures. ExportDynamoDbItemsTask exports all items as a portable typed JSON array for PutDynamoDbItemsTask; see export and replay. These tasks complement the Java initializer described here.
Tasks And Runtime Selection
| Task type | Registration | Behavior |
|---|---|---|
|
Register a named task in your build |
Create a table or verify its configuration before reuse, wait for |
|
|
List all table names, following every response page. |
|
|
Delete one explicitly named table and its items; wait for deletion to complete. |
The two registered commands default to EmulatorMode.DEVELOPMENT. Custom task instances inherit awsEmulator.defaultMode, initially EmulatorMode.MANAGED, sharing the instance used by awsEmulator.useWith(…) when their modes match. All three accept --mode=MANAGED or --mode=DEVELOPMENT.
./gradlew listDynamoDbTables
./gradlew deleteDynamoDbTable --tableName=catalog.products
Each command starts or reuses its selected emulator on demand. Listing an empty emulator succeeds. Deleting a missing table fails with a clear error by default, matching the LocalStack task’s behavior. Set DeleteDynamoDbTableTask.ignoreMissing to true for repeatable cleanup; only a missing-table error is ignored. Other SDK errors remain build failures.
Create A Table Before Tests
import io.github.gregwhitaker.awsemulator.aws.dynamodb.CreateDynamoDbTableTask
import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition
import software.amazon.awssdk.services.dynamodb.model.KeySchemaElement
import software.amazon.awssdk.services.dynamodb.model.KeyType
import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType
plugins {
java
id("io.github.gregwhitaker.aws-emulator") version "0.3.0"
}
val createProducts = tasks.register<CreateDynamoDbTableTask>("createProducts") {
tableName.set("catalog.products")
keySchema.add(KeySchemaElement.builder().attributeName("id").keyType(KeyType.HASH).build())
attributeDefinitions.add(AttributeDefinition.builder().attributeName("id").attributeType(ScalarAttributeType.S).build())
}
val tests = tasks.named<Test>("test") { dependsOn(createProducts) }
awsEmulator {
useWith(tests)
}
For a development session, set mode to EmulatorMode.DEVELOPMENT or run your creation task with --mode=DEVELOPMENT. A managed creation task invoked alone creates a table that disappears when the build finishes.
Creation Properties
The schema properties accept immutable AWS SDK for Java v2 model objects using Gradle’s lazy property API.
| Property | Type | Default or requirement |
|---|---|---|
|
|
Required; 3–255 letters, numbers, underscores, hyphens, or periods. |
|
|
Required; one |
|
|
Required; scalar |
|
|
Empty. Each configured GSI needs a key schema, projection, and provisioned throughput. |
|
|
Empty. LSIs require a composite table key and share the table’s partition key. |
|
|
100 read and 100 write capacity units, matching the LocalStack task. |
|
|
|
|
|
Unset, meaning streams disabled. Enabled streams require a |
|
|
Unset; fully qualified class name on the build classpath. |
|
|
60; positive SDK waiter timeout for creation and deletion. |
|
|
30; positive timeout for each SDK operation, including retries. |
|
|
|
These are provisioned-capacity tables. Set each GSI’s throughput separately. The task passes encryption and stream settings to the emulator; it does not provision a KMS key or a stream consumer.
Configuration Drift
An existing table is reused only when its configuration matches the task definition. The task waits for a table in transition to become ACTIVE, then compares the final description. The same check applies when another task creates the table concurrently. It runs on every invocation, including configuration-cache reuse.
| Setting | Comparison |
|---|---|
Primary key and attribute definitions |
Partition/sort key roles and attribute names; scalar types for every table and index key attribute. |
Global and local secondary indexes |
The complete set of index names, key schemas, projection types, and projected non-key attributes. Missing and extra indexes fail, including when the task’s index list is empty. |
Capacity |
Provisioned billing mode, table read/write capacity, and each GSI’s read/write capacity. The table defaults of 100/100 are checked even when not explicitly configured. An omitted billing-mode summary is treated as provisioned. |
Encryption |
AWS owned versus KMS encryption, KMS encryption type, and the resolved key ARN. Omitted KMS type/key settings with |
Streams |
Enabled/disabled state and, when enabled, the stream view type. An unset stream property requires disabled streams; a disabled stream’s previous view type is ignored. |
List order does not affect comparison: key schemas are compared by role, attributes and indexes by name, and projected attributes as a set. Generated ARNs (except the encryption key), timestamps, item counts, sizes, and throughput history are ignored. The task compares configuration exposed by its creation properties; it does not audit items, TTL, tags, or other table settings.
KMS key IDs, alias names, and alias ARNs are resolved with DescribeKey through the selected emulator’s authenticated KMS client. Explicit key ARNs are compared directly. This accepts different identifiers for the same key and detects an alias retargeted to another key. An unresolved key fails with the table name, key identifier, and original cause; it is never assumed to match. Reuse with key IDs or aliases therefore also needs access to the emulator’s KMS DescribeKey operation.
Mismatches are reported together with their property paths and requested/existing values, for example:
DynamoDB table 'catalog.products' configuration mismatch:
- provisionedThroughput.readCapacityUnits: requested 100, existing 5
- streamSpecification.streamEnabled: requested false, existing true
The existing table and its items were not changed. Align the task definition with the table, or explicitly delete and recreate it (or use a fresh managed runtime).
The task never updates or deletes an existing table to resolve drift and never reruns its initializer. Align the task definition with the existing table to preserve it. To replace a development table, explicitly delete it with deleteDynamoDbTable --tableName=<name> and rerun creation; deletion discards its items. A fresh managed runtime starts without previous tables, but creation tasks sharing that runtime must still agree on each table’s definition. Managed cleanup runs even when drift fails the build.
Table Initializers
The initializer contract follows the LocalStack plugin, updated for SDK v2:
-
A public, concrete class available on the build classpath.
-
A public constructor accepting one
DynamoDbClient. -
A public instance
void run()method with no arguments.
The plugin passes its authenticated emulator client and owns the client’s lifetime. The initializer runs only when this task creates the table, after the table becomes ACTIVE. Reusing a table, including after another task creates it concurrently, does not rerun initialization.
An initializer failure fails the build with the original cause. Managed cleanup still runs. A development table remains available for inspection; retrying creation reuses that table and does not retry initialization. Delete and recreate it to rerun its initializer.
Share The Build Classpath
When using buildSrc, depend on both the plugin and the SDK there. This places the task classes, initializer, and SDK types on the same build classpath and avoids loading separate copies of SDK model classes.
For a plugin release from the Gradle Plugin Portal, declare the Portal as a dependency repository in buildSrc/build.gradle.kts:
plugins { java }
repositories {
mavenCentral()
gradlePluginPortal()
}
dependencies {
implementation("io.github.gregwhitaker:gradle-aws-emulator:0.3.0")
implementation("software.amazon.awssdk:dynamodb:2.39.6")
}
The main build applies the plugin without a version because buildSrc supplies it. Application and test code still declare their own SDK dependencies.
The repository’s runnable example instead uses a composite build in buildSrc/settings.gradle.kts to exercise the plugin from this checkout:
/*
* Copyright 2026 Greg Whitaker
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
rootProject.name = "buildSrc"
includeBuild("../../..") {
dependencySubstitution {
substitute(module("io.github.gregwhitaker:gradle-aws-emulator")).using(project(":plugin"))
}
}
Its buildSrc/build.gradle.kts declares the dependencies:
/*
* Copyright 2026 Greg Whitaker
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
plugins { java }
repositories { mavenCentral() }
dependencies {
// Keep the plugin and initializer on the same SDK classpath.
implementation("io.github.gregwhitaker:gradle-aws-emulator:0.3.0")
implementation("software.amazon.awssdk:dynamodb:2.39.6")
}
tasks.withType<JavaCompile>().configureEach { options.release.set(17) }
Initializer Implementation
/*
* Copyright 2026 Greg Whitaker
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package example.buildsrc.dynamodb;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import java.util.Map;
/** Seeds the newly created table using the plugin's authenticated emulator client. */
public class ProductTableInitializer {
private final DynamoDbClient client;
public ProductTableInitializer(DynamoDbClient client) { this.client = client; }
public void run() {
client.putItem(request -> request.tableName("example-products").item(Map.of(
"id", AttributeValue.builder().s("product-1").build(),
"name", AttributeValue.builder().s("Example widget").build(),
"category", AttributeValue.builder().s("widgets").build())));
}
}
Run The Complete Example
From the plugin repository root:
./gradlew -p examples/dynamodb integrationTest --configuration-cache
The example creates and initializes a table with a global secondary index and stream settings, then verifies item reads and index queries over authenticated HTTPS. Run it again to verify configuration-cache reuse with fresh managed state.
View the Kotlin build script
/*
* Copyright 2026 Greg Whitaker
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import io.github.gregwhitaker.awsemulator.aws.dynamodb.CreateDynamoDbTableTask
import software.amazon.awssdk.services.dynamodb.model.*
plugins {
java
id("io.github.gregwhitaker.aws-emulator")
}
repositories { mavenCentral() }
val integrationSourceSet = sourceSets.create("integration")
dependencies {
"integrationImplementation"(platform("software.amazon.awssdk:bom:2.39.6"))
"integrationImplementation"("software.amazon.awssdk:dynamodb")
"integrationImplementation"("software.amazon.awssdk:url-connection-client")
"integrationImplementation"(platform("org.junit:junit-bom:5.11.4"))
"integrationImplementation"("org.junit.jupiter:junit-jupiter")
"integrationRuntimeOnly"("org.junit.platform:junit-platform-launcher")
}
val createProducts = tasks.register<CreateDynamoDbTableTask>("createProducts") {
tableName.set("example-products")
provisionedThroughput.set(providers.gradleProperty("productReadCapacity").map {
ProvisionedThroughput.builder().readCapacityUnits(it.toLong()).writeCapacityUnits(100L).build()
}.orElse(ProvisionedThroughput.builder().readCapacityUnits(100L).writeCapacityUnits(100L).build()))
keySchema.add(KeySchemaElement.builder().attributeName("id").keyType(KeyType.HASH).build())
attributeDefinitions.set(listOf("id", "category").map {
AttributeDefinition.builder().attributeName(it).attributeType(ScalarAttributeType.S).build()
})
globalSecondaryIndexes.add(GlobalSecondaryIndex.builder()
.indexName("by-category")
.keySchema(KeySchemaElement.builder().attributeName("category").keyType(KeyType.HASH).build())
.projection(Projection.builder().projectionType(ProjectionType.ALL).build())
.provisionedThroughput(ProvisionedThroughput.builder().readCapacityUnits(5L).writeCapacityUnits(5L).build())
.build())
streamSpecification.set(StreamSpecification.builder().streamEnabled(true).streamViewType(StreamViewType.NEW_IMAGE).build())
initializer.set("example.buildsrc.dynamodb.ProductTableInitializer")
}
val integrationTest = tasks.register<Test>("integrationTest") {
description = "Reads initialized DynamoDB items and queries a secondary index."
group = "verification"
dependsOn(createProducts)
testClassesDirs = integrationSourceSet.output.classesDirs
classpath = integrationSourceSet.runtimeClasspath
useJUnitPlatform()
}
awsEmulator {
useWith(integrationTest)
}
For the development runtime:
./gradlew -p examples/dynamodb createProducts --mode=DEVELOPMENT
./gradlew -p examples/dynamodb listDynamoDbTables
./gradlew -p examples/dynamodb deleteDynamoDbTable --tableName=example-products
./gradlew -p examples/dynamodb stopAwsEmulator
The example accepts -PproductReadCapacity=<units>. To demonstrate drift, create the development table with its default capacity and then request a different value:
./gradlew -p examples/dynamodb createProducts --mode=DEVELOPMENT
# Expected failure: requested 5 read units, existing 100. The table and seeded items remain intact.
./gradlew -p examples/dynamodb createProducts --mode=DEVELOPMENT -PproductReadCapacity=5
# Matching settings reuse the original table without rerunning the initializer.
./gradlew -p examples/dynamodb createProducts --mode=DEVELOPMENT
./gradlew -p examples/dynamodb stopAwsEmulator