Use Autonomous AI Database API for DynamoDB
Autonomous AI Database API for DynamoDB make it possible to store, manage and retrieve data in an Autonomous AI Database using a key-value format.
Topics
- About using Autonomous AI Database API for DynamoDB
Oracle Autonomous AI Database offers the Autonomous AI Database API for DynamoDB, with Oracle's fully managed Autonomous AI Database, enabling you to use existing DynamoDB tools and SDKs to work seamlessly with Autonomous AI Database. - Prerequisites
Lists the prerequisites to use Autonomous AI Database API for DynamoDB with your Autonomous AI Database. - Enable Autonomous AI Database API for DynamoDB on Autonomous AI Database
Describes the steps generate access key and secret key to invoke DynamoDB API from your Autonomous AI Database instance. - Configure Access to Invoke DynamoDB APIs
This section provides the steps to create and manage access keys required to authenticate and use DynamoDB-compatible APIs after you enabled your Autonomous AI Database. - Steps to Invoke DynamoDB-Compatible API
After enabling DynamoDB API and creating an access key, you can use the DynamoDB Client SDK to invoke Oracle Database API for DynamoDB. - Disable Autonomous AI Database API for DynamoDB on Autonomous AI Database
Shows the steps to disable the DynamoDB API for your Autonomous AI Database. - Notes and Limitations for using Oracle Database API for DynamoDB on Autonomous AI Database
Lists notes and limitations for using Oracle Database API for DynamoDB on Autonomous AI Database.
Parent topic: Develop
About using Autonomous AI Database API for DynamoDB
Oracle Autonomous AI Database offers the Autonomous AI Database API for DynamoDB, with Oracle's fully managed Autonomous AI Database, enabling you to use existing DynamoDB tools and SDKs to work seamlessly with Autonomous AI Database.
Using the Oracle Autonomous AI Database API for DynamoDB compatibility API, you can continue to use your existing DynamoDB clients and make minimal changes to your applications to work with Autonomous AI Database. You can use standard DynamoDB SDKs to integrate your existing DynamoDB applications with Autonomous AI Database. The APIs offer familiar DynamoDB operations such as, GetItem, DeleteItem, CreateTable, and DeleteTable, enabling you to migrate DynamoDB applications to Autonomous AI Database.
By using Autonomous AI Database API for DynamoDB, you can take advantage of Autonomous AI Database features while maintaining DynamoDB compatibility.
See Amazon DynamoDB for more information.
Parent topic: Use Autonomous AI Database API for DynamoDB
Prerequisites
Lists the prerequisites to use Autonomous AI Database API for DynamoDB with your Autonomous AI Database.
Before you enable Autonomous AI Database API for DynamoDB for your database, note the following:
-
Autonomous AI Database API for DynamoDB is only supported for Autonomous AI Database with the workload type Transaction Processing.
-
Your Autonomous AI Database instance must not be a part of an elastic pool. If you attempt to enable Autonomous AI Database API for DynamoDB on an Autonomous AI Database that is part of an elastic group, or try to add a database with these APIs enabled to an elastic group, you receive an error. Autonomous AI Databases with Autonomous AI Database API for DynamoDB enabled are not allowed to be members of any elastic group.
Parent topic: Use Autonomous AI Database API for DynamoDB
Enable Autonomous AI Database API for DynamoDB on Autonomous AI Database
Describes the steps generate access key and secret key to invoke DynamoDB API from your Autonomous AI Database instance.
Perform the following prerequisite steps as necessary:
-
Open the Oracle Cloud Infrastructure Console by clicking the
next to Cloud.
-
From the Oracle Cloud Infrastructure left navigation menu click Oracle Database and then click Autonomous AI Database.
-
On the Autonomous AI Database page, select your Autonomous AI Database from the links under the Display name column.
Follow these steps to enable DynamoDB APIs on an Autonomous AI Database instance:
Parent topic: Use Autonomous AI Database API for DynamoDB
Configure Access to Invoke DynamoDB APIs
This section provides the steps to create and manage access keys required to authenticate and use DynamoDB-compatible APIs after you enabled your Autonomous AI Database.
https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys to manage the access to DynamoDB tables. To do this, provide your database username and credentials; the specified user must have the PDB_DBA role granted. These access keys are required for authenticating API calls to the Autonomous AI Database for DynamoDB.
You must ensure that the access key is assigned the necessary permissions to perform DynamoDB-compatible operations. You can specify these permissions when creating the access key or modify an existing key to assign the required permissions.
The following is a list of permissions for access keys:
| Permission | Description |
|---|---|
|
|
Access to perform table creation |
|
|
Access to perform table and items read operations on all DynamoDB compatible key tables associated with the Autonomous AI Database. It does not include backup, restore, import and export operations. |
|
|
Access to perform table and items read and write operations on all DynamoDB compatible tables associated with the Autonomous AI Database. It does not include backup, restore, import and export operations. |
|
|
Access to perform any operations including create table, backup, restore, import and export all DynamoDB compatible tables associated with the Autonomous AI Database. |
|
|
Access to perform table and items read operations on specific DynamoDB compatible table associated with the Autonomous AI Database. It does not include backup, restore, import and export operations. |
|
|
Access to perform table and items read and write operations on specific DynamoDB compatible table associated with the Autonomous AI Database. It does not include backup, restore, import and export operations. |
|
|
Access to perform any operations including backup, restore, import and export on specific DynamoDB compatible table associated with the Autonomous AI Database. |
|
|
Access to perform specific operation on specific DynamoDB compatible table associated with Autonomous AI Database. |
Create an access key
To create an Access Key and Secret Key in your database, you must be logged in as the ADMIN user or have been granted the PDB_DBA role.
Syntax and a sample request for creating an access key in your database:
Use the POST https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys REST endpoint API request to generate the Access Key and Secret Key:
Syntax
POST "https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys"
{
"name" : "{<access_key_name>}", // Required. The name you assign to the access key.
"description" : "{<access_key_description>}", // Optional. A description for the access key.
"permissions" : [ // Optional. Array of permission objects.
{
"actions" : [<List of permissions>], // Required. List of permitted actions (e.g., "read", "write").
"resources" : [<List of Tables>] // Optional. Only applicable for permissions that get applied on Table.
}
// ... additional permission objects as needed
],
"expiration_minutes": 120 // Optional. The key's expiration time in minutes.
}-
name:String: Access key name -
description:String: Description for the access key -
permissions:Array: (Optional) Each object in this array defines what operations (actions) are allowed and (optionally) which tables (resources) those actions are limited to.-
actions:Array of Strings(Required: lists the specific operations that the key can perform. For example, "CREATE_TABLE", "READ_WRITE", "ADMIN".) -
resources:Array of Strings(Optional: Specifies which tables the actions apply to. If you list table names in this array, such as "resources": ["customers", "orders"], the actions will be restricted to only those tables. If omitted, the actions will apply to all tables in the database.)
-
-
expiration_minutes:Number: (Optional) Expiration duration in minutes
Sample response format
{
"name": "<access_key_name>",
"description": "<access_key_description>",
"access_key_id": "<access_key_id>",
"secret_access_key": "<generated secret>",
"expiration_timestamp": "<access_key_expiration_timestamp>",
"permissions": [
{
"actions" : [<permissions list>],
"resources": [<optional DynamoDb table list>]
}
// ...more permission objects
]
}
Example: This example demonstrates how to send a POST request to the Oracle Autonomous AI Database REST API to create a new access key with administrative permissions. The request specifies the key name and required permissions, and the response includes the newly generated access key ID, secret, expiration time, and permissions.
# Request
curl -X POST 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys'\
--user "AdminUser:TestPass#" \
--header 'Request-Id: 8g89mz8qnet9ufxg4dwrus8m' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "adminkey",
"permissions": [
{
"actions": [
"ADMIN_ANY"
]
}
],
"expiration_minutes": 120
}'
# Sample Response
{
"access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
"secret_access_key": "NzYwZDE5M2E4NDVjZ.....FmMzBiNQ>>",
"expiration_time": "2025-12-07T03:35:12Z",
"permissions": [
{
"actions": [
"ADMIN_ANY"
]
}
]
}-
database-ocid: The OCID of the database for which the access key is being created. -
AdminUser: The database username used for authentication. -
TestPass#: The database user’s password. -
Request-Id: Unique identifier for the API request, useful for tracking or troubleshooting. -
Content-Type: Specifies the format of the request payload as JSON (application or json). -
name: The name to assign to the new access key. -
permissions: An array specifying the permissions to assign to the new key.-
actions: An array of allowed actions for the access key (e.g., "ADMIN_ANY" for administrative privileges)
-
-
expiration_minutes: Specifies the duration in minutes before the access key expires.
-
access_key_id: The unique identifier for the newly created access key. -
secret_access_key: The secret value associated with the access key. This is required for authenticating future API requests. -
expiration_time: The timestamp indicating when the access key will expire. -
The array of permission objects assigned to the access key (as given in the request).
-
actions: The allowed actions for the access key (e.g., "ADMIN_ANY" for administrative privileges)
-
Retrieve Access Key Information
After you created an access key, use the GET /accesskeys REST API request to look up its details, such as its name, associated permissions, expiration time, and other relevant metadata. This enables you to programmatically confirm access rights, audit credentials, or show access key information.
Syntax and example to retrieve access key details:
Syntax:
GET https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
Authorization: Basic <Base64-encoded
database username and password>request-id: <optional request-id>
Example: The following call retrieves detailed information about the specified access key. This allows you to confirm the attributes and permissions associated with the access key:
# Request
curl -X GET 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xcz5efdb7rfrbsfkkwwl7d38' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
# Sample Response
{
"access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
"expiration_timestamp": "2025-12-07T03:35:12.751Z",
"permissions": [
{
"actions": [
"ADMIN_ANY"
]
}
]
}
Request Parameters:
-
database-ocid: The unique Oracle Cloud Identifier (OCID) of the Autonomous Database being queried. -
access-key-id: The unique identifier of the specific access key whose details are requested. -
AdminUser: The database username used for authentication. -
TestPass#: The database user’s password. -
Request-Id: Unique identifier for this API request.,useful for logging or troubleshooting. -
Content-Type: Specifies the expected format of the response (applicationorjson; set in the header). -
Accept: Specifies the response format.
Update an access key
After you have created and retrieved your access key, you use the PUT /accesskeys REST API to update the attributes of an existing access key.
Syntax and example to update an access key:
Syntax
PUT https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
Authorization: Basic <Base64-encoded database username and password>
request-id: <optional request-id>
Content-Type: application/json
{
"permissions": [<permissions array>],
"extend_expiration_minutes_by": <integer>
}
Example: The following request updates the access key to extend the expiration time by 120 minutes.
# Request
curl -X PUT 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xzpqvei6e7x52ri94odpv0a4' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"extend_expiration_minutes_by" : 120
}'
# Sample Response
{
"access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
"expiration_timestamp": "2025-12-07T05:35:12.751Z",
"permissions": [
{
"actions": [
"ADMIN_ANY"
]
}
],
"message": "Expiration extended by 120 min"
}
Request parameters:
-
database-ocid: The unique Oracle Cloud Identifier (OCID) of the Autonomous Database being queried. -
access-key-id: The unique identifier of the specific access key whose details are requested. -
AdminUser: The database username used for authentication. -
TestPass#: The database user’s password. -
Request-Id: Unique identifier for this API request.,useful for logging or troubleshooting. -
Content-Type: Specifies the expected format of the response (applicationorjson; set in the header). -
Accept: Specifies the response format. -
extend_expiration_minutes_by: (Body) Number of minutes to extend the access key's expiration.
Response parameters:
-
access_key_id: The unique identifier for the updated access key. -
expiration_timestamp: The new expiration timestamp for the access key. -
permissions: Array describing the permissions associated with the access key.-
actions: List of actions allowed (example: "ADMIN_ANY").
-
-
message: Confirmation message indicating the action performed.
Delete an access key
You can delete an existing access key when it is no longer required. You use the DELETE /accesskeys REST API to remove an access key from your database.
Syntax and example to remove an access key from your database:
Syntax:
DELETE https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
Authorization: Basic <Base64-encoded database username and password>
request-id: <optional request-id>
Example: The following request removes the specified access key from your Autonomous AI Database. Once deleted, the key can no longer be used for authentication or database access. A successful deletion returns an HTTP status code of 204 No Content or 200 OK, with no response body.
# Request
curl -X DELETE 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xzpqvei6e7x52ri94odpv0a4' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
# Sample Response
{
"message": "Access key deleted successfully.",
"access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
"status": "DELETED"
}
Request parameters:
-
database-ocid: The unique Oracle Cloud Identifier (OCID) of the Autonomous Database being queried. -
access-key-id: The unique identifier of the specific access key whose details are requested. -
AdminUser: The database username used for authentication. -
TestPass#: The database user’s password. -
Request-Id: Unique identifier for this API request.,useful for logging or troubleshooting. -
Content-Type: Specifies the expected format of the response (applicationorjson; set in the header).
Response parameters:
-
message: Confirmation message indicating the result of the delete operation. -
access_key_id: The unique identifier for the updated access key. -
status: The final status of the access key after deletion (e.g., "DELETED").
Parent topic: Use Autonomous AI Database API for DynamoDB
Steps to Invoke DynamoDB-Compatible API
After enabling DynamoDB API and creating an access key, you can use the DynamoDB Client SDK to invoke Oracle Database API for DynamoDB.
Follow these steps to configure your DynamoDB client to invoke Autonomous AI Database API for DynamoDB.
Configure DynamoDbClient with Autonomous AI Database DynamoDB-Compatible Endpoint
Update AWS Credentials File
~/.aws/credentials, if the file does not exist, create it. Update the credentials file with the Access Key ID and Secret Access Key generated for Autonomous AI Database DynamoDB Compatible APIs. For example:aws_access_key_id=<Your ADB-S DynamoDB Compatible APIs Access Key ID>
aws_secret_access_key=<Your ADB-S DynamoDB Compatible APIs Secret Access Key>Update DynamoDB client code to use Autonomous AI Database endpoint.
For example, the following code configures the DynamoDB client using the Java SDK to point to your Autonomous AI Database endpoint:
import java.net.URI;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
// Set the appropriate region and endpoint.
//Region name is optional and will be overridden by the region value specified in the REST API endpoint.
Region region = Region.US_EAST_1;
String endpoint = "https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/keyvaluestore/v1/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE";
// Build the DynamoDB client using a custom endpoint
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.endpointOverride(URI.create(endpoint))
.build();This example overrides the default endpoint so the client points to the Autonomous AI Database DynamoDB Compatible REST endpoint.
Code elements:
-
DynamoDbClient.builder(): Initializes a newDynamoDbClient.Builderinstance. This builder is part of the AWS SDK for Java and is used for constructing DynamoDB client instances. -
region(Region region): Specifies the AWS region in which the client operates. Note that this region name is optional and will be overridden by the region value specified in the REST API endpoint. -
endpointOverride(URI endpoint): Configures the client to communicate with a specified DynamoDB-compatible HTTP endpoint, instead of the default AWS service endpoint. -
build(): Finalizes the builder configuration and creates a newDynamoDbClientinstance with the specified settings.
You can also configure or override the DynamoDB client endpoint using other programming languages and their respective AWS SDKs, such as Python (with Boto3), C++.
-
Python: DynamoDB
-
Java: AWS SDK for Java
-
C++: AWS SDK for C++
Invoke DynamoDB-Compatible API on your Autonomous AI Database
The following code demonstrates how to create a DynamoDB-compatible table movie and perform basic operations: describe, list, insert, update, and delete items using the Java AWS SDK v2 with a custom endpoint.
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import java.net.URI;
import java.util.Map;
public class DynamoDBMovieExample {
public static void main(String[] args) {
// Set the region and endpoint
//Region name is optional and will be overridden by the region value specified in the REST API endpoint.
Region region = Region.US_WEST_1;
String endpoint = "https://region.us-phoenix-1.adb.oraclecloud.com";
// Build the DynamoDB client using a custom endpoint
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.endpointOverride(URI.create(endpoint))
.build();
// Create table
CreateTableRequest createTableRequest = CreateTableRequest.builder()
.tableName("movie")
.keySchema(
KeySchemaElement.builder().attributeName("PK").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("SK").keyType(KeyType.RANGE).build()
)
.attributeDefinitions(
AttributeDefinition.builder().attributeName("PK").attributeType(ScalarAttributeType.S).build(),
AttributeDefinition.builder().attributeName("SK").attributeType(ScalarAttributeType.S).build()
)
.provisionedThroughput(
ProvisionedThroughput.builder().readCapacityUnits(5L).writeCapacityUnits(5L).build()
)
.build();
ddb.createTable(createTableRequest);
// Describe the table
DescribeTableRequest descRequest = DescribeTableRequest.builder().tableName("movie").build();
DescribeTableResponse descResponse = ddb.describeTable(descRequest);
// List all tables
ListTablesRequest listRequest = ListTablesRequest.builder().build();
ListTablesResponse listResponse = ddb.listTables(listRequest);
// Insert (PutItem)
ddb.putItem(PutItemRequest.builder()
.tableName("movie")
.item(Map.of(
"PK", AttributeValue.builder().s("001").build(),
"SK", AttributeValue.builder().s("MOVIE").build(),
"Title", AttributeValue.builder().s("Inception").build()))
.build()
);
// Update (UpdateItem)
ddb.updateItem(UpdateItemRequest.builder()
.tableName("movie")
.key(Map.of(
"PK", AttributeValue.builder().s("001").build(),
"SK", AttributeValue.builder().s("MOVIE").build()))
.updateExpression("SET #T = :t")
.expressionAttributeNames(Map.of("#T", "Title"))
.expressionAttributeValues(Map.of(":t", AttributeValue.builder().s("Inception (2010)").build()))
.build()
);
// Delete (DeleteItem)
ddb.deleteItem(DeleteItemRequest.builder()
.tableName("movie")
.key(Map.of(
"PK", AttributeValue.builder().s("001").build(),
"SK", AttributeValue.builder().s("MOVIE").build()))
.build()
);
}
}
-
For a complete list of available DynamoDB operations, refer to the DynamoDB API Reference: List of Operations .
-
To run
ImportTableandExportTableoperations with Object Store, ensure that you enable a resource principal to access Oracle Cloud Infrastructure resources and set the required OCI policies. See Use Resource Principal to Access Oracle Cloud Infrastructure Resources for more information. -
Setting the read capacity units (RCU) and write capacity units (WCU) for your DynamoDB-compatible table may impact your billing, as you are charged based on the provisioned throughput. For detailed information on how these settings affect billing. See Oracle Autonomous Database Serverless Features Billing for more information.
Parent topic: Use Autonomous AI Database API for DynamoDB
Disable Autonomous AI Database API for DynamoDB on Autonomous AI Database
Shows the steps to disable the DynamoDB API for your Autonomous AI Database.
Perform the following prerequisite steps as necessary:
-
Open the Oracle Cloud Infrastructure Console by clicking the
next to Cloud.
-
From the Oracle Cloud Infrastructure left navigation menu click Oracle Database and then click Autonomous AI Database.
-
On the Autonomous AI Database page, select your Autonomous AI Database from the links under the Display name column.
Follow these steps to disable DynamoDB APIs on an Autonomous AI Database instance:
Parent topic: Use Autonomous AI Database API for DynamoDB
Notes and Limitations for using Oracle Database API for DynamoDB on Autonomous AI Database
Lists notes and limitations for using Oracle Database API for DynamoDB on Autonomous AI Database.
Note the following when using Oracle Database API for DynamoDB on Autonomous AI Database:
Usage notes
-
If an Autonomous AI Database with Oracle Database API for DynamoDB enabled is deleted, all associated DynamoDB-compatible tables are also dropped and billing stops.
-
If the Autonomous AI Database with Database API for DynamoDB enabled is stopped, all associated DynamoDB-compatible tables are excluded from billing during the stopped period.
-
All associated DynamoDB-compatible tables are affected by the delete or stop operations as described above.
Limitations
-
A maximum of 2 DynamoDB-compatible tables are allowed for each Free Autonomous AI Database and Autonomous AI Database for Developers.
-
A maximum of 4 ECPUs per DynamoDB-compatible table are allowed for each Free Autonomous AI Database and Autonomous AI Database for Developers.
-
Table names must be between 3 and 255 characters in length.
-
Global Table APIs and PartiQL APIs are not supported.
Parent topic: Use Autonomous AI Database API for DynamoDB