Add support for S3 #3141

KodaiD · 2025-11-12T00:49:23Z

Description

This PR adds S3 support to the Object Storage adapter.

Related issues and/or PRs

Changes made

Added an ObjectStorageWrapper implementation for S3.
Added unit tests.
Added a GitHub workflow for integration tests.

Checklist

I have commented my code, particularly in hard-to-understand areas.
I have updated the documentation to reflect the changes.
I have considered whether similar issues could occur in other products, components, or modules if this PR is for bug fixes.
Any remaining open issues linked to this PR are documented and up-to-date (Jira, GitHub, etc.).
Tests (unit, integration, etc.) have been added for the changes.
My changes generate no new warnings.
Any dependent changes in other PRs have been merged and published.

Additional notes (optional)

N/A

Release notes

Added Amazon S3 adapter.

KodaiD · 2025-11-12T00:49:35Z

/gemini review

KodaiD · 2025-11-12T00:52:38Z

.github/workflows/object-storage-adapter-check.yaml

@@ -0,0 +1,93 @@
+name: Test Object Storage Adapter
+


Since AWS does not provide an S3 emulator, and other S3-compatible storage services do not support conditional deletes, we will need to run integration tests when releasing a new ScalarDB version.

gemini-code-assist

Code Review

This pull request introduces S3 support for the Object Storage adapter, which is a significant feature addition. The implementation is comprehensive, leveraging the AWS CRT-based S3 client for better performance and includes new configuration options, exception types, and both unit and integration tests. My review has identified a critical issue in the delete method's logic that needs to be addressed. Additionally, I've pointed out several areas for improvement regarding code duplication, potential memory inefficiencies when handling large numbers of objects, and making exception handling more robust. Overall, this is a solid contribution, and addressing these points will enhance its correctness and maintainability.

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Wrapper.java

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Config.java

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Wrapper.java

KodaiD · 2025-11-12T00:54:05Z

core/src/main/java/com/scalar/db/storage/objectstorage/blobstorage/BlobStorageConfig.java

    } else {
      throw new IllegalArgumentException(
-          "Invalid contact points format. Expected: BLOB_URI/BUCKET_NAME");
+          "Invalid contact points format. Expected: BLOB_URI/CONTAINER_NAME");


In Blob Storage, a bucket is called a container.

KodaiD · 2025-11-12T01:01:35Z

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Config.java

+import com.scalar.db.storage.objectstorage.ObjectStorageConfig;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+


The performance-related parameters may be integrated into ObjectStorageConfig if GCS has similar options.

KodaiD · 2025-11-12T02:17:07Z

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Wrapper.java

+            .httpClientBuilder(
+                AwsCrtAsyncHttpClient.builder()
+                    .maxConcurrency(config.getParallelUploadMaxParallelism()))


The CRT-based client is used for performance.
https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/crt-based-s3-client.html

Copilot

Pull Request Overview

This PR adds Amazon S3 support to the Object Storage adapter, enabling ScalarDB to use S3 as a backend storage option alongside the existing Azure Blob Storage adapter.

Implemented S3Wrapper class that provides S3-specific operations (get, insert, update, delete, etc.)
Added configuration, provider, and error handling classes for S3
Refactored shared exception constructors and interface methods to support both storage types

Reviewed Changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
S3Wrapper.java	Core S3 implementation with async client operations and error handling
S3Config.java	Configuration parser for S3-specific settings (region, bucket, parallelism, etc.)
S3Provider.java	Service provider for S3 storage
S3ErrorCode.java	Enum for S3 HTTP status codes
S3WrapperTest.java	Comprehensive unit tests for S3Wrapper
S3ConfigTest.java	Unit tests for S3Config
ObjectStorageWrapperFactory.java	Added S3 instantiation logic
ObjectStorageUtils.java	Added S3 config factory logic
ObjectStorageConfig.java	Removed `getEndpoint()` method (S3-specific)
BlobStorageConfig.java	Moved `getEndpoint()` from interface to implementation, fixed error message
PreconditionFailedException.java	Removed unused single-argument constructor
ObjectStorageWrapperException.java	Removed unused single-argument constructor
ConflictOccurredException.java	New exception class for conflict errors
ObjectStorageWrapperIntegrationTest.java	Fixed test signature and improved test cleanup
ObjectStorageEnv.java	Added storage type configuration support
core/build.gradle	Added AWS S3 SDK dependencies
DistributedStorageProvider	Registered S3Provider service
object-storage-adapter-check.yaml	New GitHub workflow for S3 integration tests

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

.github/workflows/object-storage-adapter-check.yaml

KodaiD · 2025-11-13T05:27:59Z

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Wrapper.java

+
+  public S3Wrapper(S3Config config) {
+    this.client =
+        S3AsyncClient.builder()


S3 async client is used because it supports automatic parallel transfers.
http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/s3-async-client-multipart.html

core/src/integration-test/java/com/scalar/db/storage/objectstorage/ObjectStorageEnv.java

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Config.java

komamitsu · 2025-11-13T06:25:57Z

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Wrapper.java

+      if (cause instanceof S3Exception) {
+        Optional<S3Exception> s3Exception = findS3Exception(e);
+        if (s3Exception.isPresent()) {
+          if (s3Exception.get().statusCode() == S3ErrorCode.CONFLICT.get()) {


This could happen without version?

I think so. For example, for If-None-Match, the official document said as follows:

If-None-Match - Uploads the object only if the object key name does not already exist in the specified bucket. Otherwise, Amazon S3 returns a 412 Precondition Failed error. If a conflicting operation occurs during the upload, S3 returns a 409 ConditionalRequestConflict response. On a 409 failure, retry the upload.

https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Client.html#putObject(software.amazon.awssdk.services.s3.model.PutObjectRequest,software.amazon.awssdk.core.sync.RequestBody)

But it doesn't have a similar description for if-Match header and a situation without a header. The catch block is put just in case.

brfrn169

Left several comments. PTAL!

.github/workflows/object-storage-adapter-check.yaml

...ation-test/java/com/scalar/db/storage/objectstorage/ObjectStorageWrapperIntegrationTest.java

core/src/main/java/com/scalar/db/storage/objectstorage/ObjectStorageUtils.java

core/src/main/java/com/scalar/db/storage/objectstorage/ObjectStorageWrapperFactory.java

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Wrapper.java

komamitsu

LGTM! 👍

brfrn169

LGTM! Thank you!

Torch3333

LGTM, thank you!

feeblefakie

Overall, looking good!
Left some suggestions. PTAL!

feeblefakie · 2025-11-14T02:47:23Z

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Config.java

+  public static final long DEFAULT_PARALLEL_UPLOAD_BLOCK_SIZE_IN_BYTES = 8 * 1024 * 1024; // 8MB
+  public static final int DEFAULT_PARALLEL_UPLOAD_MAX_PARALLELISM = 50;
+  public static final long DEFAULT_PARALLEL_UPLOAD_THRESHOLD_IN_BYTES = 8 * 1024 * 1024; // 8MB


Is there any recommended practice for the values depending on workloads?
Or, are they just set randomly?
If there is one, it would be helpful to note it here.

Sorry for the lack of reference.

8MB is the default value for minimumPartSizeInBytes and thresholdInBytes.
Ref: https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/multipart/MultipartConfiguration.Builder.html

For maxConcurrency, it seems that the following default value is used:
https://github.com/aws/aws-sdk-java-v2/blob/e3b5e0a44bcfe2779757610179e8fb00014a8bed/http-client-spi/src/main/java/software/amazon/awssdk/http/SdkHttpConfigurationOption.java#L151

For the Blob Storage's parallel upload options, I couldn't find the default value. So, I set the random value in the previous PR. Should we set the same default values on the Blob Storage side? I want to hear your opinion.

feeblefakie · 2025-11-14T02:50:19Z

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Wrapper.java

+import software.amazon.awssdk.services.s3.model.S3Exception;
+import software.amazon.awssdk.services.s3.multipart.MultipartConfiguration;
+
+public class S3Wrapper implements ObjectStorageWrapper {


S3AsyncClient seems to be thread-safe, so should this be marked @ThreadSafe?

BTW, the implementation of ObjectStorageWrapper must be thread-safe, right?

BTW, the implementation of ObjectStorageWrapper must be thread-safe, right?

Yes. Because each statement handler must be thread-safe, ObjectStorageWrapper must also be thread-safe. Let me mark it as thread-safe. Thank you for pointing it out!

I've applied it in b7825fb.

feeblefakie · 2025-11-14T05:06:56Z

core/src/main/java/com/scalar/db/storage/objectstorage/s3/S3Wrapper.java

+          }
+          if (s3Exception.get().statusCode() == S3ErrorCode.NOT_FOUND.get()
+              || s3Exception.get().statusCode() == S3ErrorCode.PRECONDITION_FAILED.get()) {
+            throw new PreconditionFailedException(


Is there a particular reason for defining Object Storage adapter-specific exceptions?
Can we just throw RetriableExecutionException here and throw ExecutionException instead of ObjectStorageWrapperException, which is simpler and more consistent with the other adapters?

I think the decision to throw a RetriableExecutionException should be made within the class that uses ObjectStorageWrapper, such as MutateStatementHandler or ObjectStorageAdmin. In the current implementation, if a PreconditionFailedException is caught, a RetriableExecutionException is thrown, but this depends on how the update method is used. Therefore, it would be better to distinguish between PreconditionFailedException and ConflictOccurredException, and ExecutionException alone is not sufficient. Also, since ObjectStorageWrapper is an abstraction layer, I don't think it's unnatural for it to have its own defined exceptions. For example, JDBC databases basically throw SQLException.

Add support for S3

001d495

KodaiD self-assigned this Nov 12, 2025

KodaiD added the enhancement New feature or request label Nov 12, 2025

KodaiD commented Nov 12, 2025

View reviewed changes

gemini-code-assist bot reviewed Nov 12, 2025

View reviewed changes

KodaiD commented Nov 12, 2025

View reviewed changes

Apply suggestions

aec6f6d

KodaiD marked this pull request as ready for review November 12, 2025 02:14

Copilot AI review requested due to automatic review settings November 12, 2025 02:14

KodaiD commented Nov 12, 2025

View reviewed changes

KodaiD requested review from a team, Torch3333, brfrn169, feeblefakie and komamitsu and removed request for a team November 12, 2025 02:17

Copilot AI reviewed Nov 12, 2025

View reviewed changes

.github/workflows/object-storage-adapter-check.yaml Show resolved Hide resolved

.github/workflows/object-storage-adapter-check.yaml Show resolved Hide resolved

KodaiD added 2 commits November 12, 2025 11:27

Fix based on review

d21120d

Add a newline at the EOF

32136f6

KodaiD closed this Nov 13, 2025

KodaiD reopened this Nov 13, 2025

KodaiD commented Nov 13, 2025

View reviewed changes

komamitsu reviewed Nov 13, 2025

View reviewed changes

KodaiD requested a review from komamitsu November 13, 2025 07:59

brfrn169 reviewed Nov 13, 2025

View reviewed changes

Apply suggestions

d64cf16

KodaiD added 2 commits November 14, 2025 09:37

Merge remote-tracking branch 'origin/master' into add-s3-support

aa226c4

Handle ConflictOccurredException exception

4f6801f

KodaiD requested a review from brfrn169 November 14, 2025 00:43

komamitsu approved these changes Nov 14, 2025

View reviewed changes

Fix unit tests

ca9fe4b

brfrn169 approved these changes Nov 14, 2025

View reviewed changes

Torch3333 approved these changes Nov 14, 2025

View reviewed changes

feeblefakie reviewed Nov 14, 2025

View reviewed changes

Fix based on review

b7825fb

KodaiD requested a review from feeblefakie November 14, 2025 09:06

Add support for S3 #3141

Are you sure you want to change the base?

Add support for S3 #3141

Uh oh!

Conversation

KodaiD commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues and/or PRs

Changes made

Checklist

Additional notes (optional)

Release notes

Uh oh!

KodaiD commented Nov 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KodaiD Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brfrn169 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

komamitsu left a comment

Choose a reason for hiding this comment

Uh oh!

brfrn169 left a comment

Choose a reason for hiding this comment

Uh oh!

Torch3333 left a comment

Choose a reason for hiding this comment

Uh oh!

feeblefakie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KodaiD Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

feeblefakie Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

KodaiD commented Nov 12, 2025 •

edited

Loading

KodaiD Nov 13, 2025 •

edited

Loading

KodaiD Nov 14, 2025 •

edited

Loading

feeblefakie Nov 14, 2025 •

edited

Loading