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.

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, GetItemDeleteItemCreateTable, 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.

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.

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 navigation icon 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:

  1. On the More actions drop-down list, select Manage tags.

    This shows the Add Tags page.

  2. Provide the following values to assign tags to Autonomous AI Database.
    • Namespace: To add a free-from tag, leave the value blank.

    • Key: adb$feature

    • Value: {"name":"DYNAMODBAPI","enable":true}

    Click Add to add the tag.

    After you click Add, the Lifecycle state field shows Updating and Autonomous AI Database generates an Update Autonomous Database Tags work request. To view the request, on the details page, select the Work requests tab.

    It may take up to ten (10) minutes for Autonomous AI Database API for DynamoDB to be enabled.

    After enabling the Oracle Database API for DynamoDB on your Autonomous AI database, you use the https://dataaccess.adb.{oci-region_name}.oraclecloudapps.com/adb/keyvaluestore/v1/{database-ocid} REST endpoint to perform DynamoDB operations. To access the Oracle Autonomous DynamoDB API, you need a valid access key ID, secret access key, and the necessary privileges for your operations, for example, the CREATE_TABLE privilege is required to create a DynamoDB table.

    The URI for the Oracle Autonomous DynamoDB API operations is:

    https://dataaccess.adb.{oci-region_name}.oraclecloudapps.com/adb/keyvaluestore/v1/{database-ocid}

    For example:

    https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/keyvaluestore/v1/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE

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.

Use REST endpoint 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

CREATE_TABLE

Access to perform table creation

READ_ANY

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.

READ_WRITE_ANY

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.

ADMIN_ANY

Access to perform any operations including create table, backup, restore, import and export all DynamoDB compatible tables associated with the Autonomous AI Database.

READ <Table(s)>

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.

READ_WRITE on <Table(s)>

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.

ADMIN on <Table(s)>

Access to perform any operations including backup, restore, import and export on specific DynamoDB compatible table associated with the Autonomous AI Database.

<operation name> on <Table(s)> For example, GetItem on <Table(s)>

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.
}
Path Parameters (provide proper authentication and replace placeholders with your actual OCI region and database OCID):
  • 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"
            ]
        }
    ]
}

Request Parameters:
  • 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.

Response Parameters:
  • 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 (application or json; 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 (application or json; 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 (application or json; 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").

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

Navigate to your AWS credentials file at ~/.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 new DynamoDbClient.Builder instance. 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 new DynamoDbClient instance 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++.

See the DynamoDB SDK references by language:

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()
        );
    }
}

Usage notes

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 navigation icon 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:

  1. On the More actions drop-down list, select Manage tags.

    This shows the Add Tags page.

  2. Provide the following values to assign tags to Autonomous AI Database.
    • Namespace: To add a free-from tag, leave the value blank.

    • Key: adb$feature

    • Value: {"name":"DYNAMODBAPI","enable": false}

    Click Add to add the tag.

    After you click Add, the Lifecycle state field shows Updating and Autonomous AI Database generates an Update Autonomous Database Tags work request. To view the request, on the details page, select the Work requests tab.

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.