PolarDB:Quick start: Connect using the DynamoDB API

Prerequisites

Before you use this feature, make sure your cluster meets the following version requirements:

• Kernel version: PostgreSQL 14, and the revision version must be 2.0.14.17.35.0 or later.

• Database proxy version: 2.3.59 or later.

• The DynamoDB compatibility feature is not supported by PolarDB for PostgreSQL Distributed Edition or serverless clusters.

Enable the DynamoDB-compatible feature

You can enable the DynamoDB-compatible feature for your cluster in one of the following two ways.

Configure a DynamoDB endpoint

After you enable the DynamoDB-compatible feature, the system automatically creates a default DynamoDB endpoint. You can also create a custom endpoint to meet specific needs.

• On the Basic Information page of the cluster, find the default DynamoDB Endpoint created by the system in the Database Connections section.

  

• (Optional) Click Create Custom Cluster Endpoint and set Endpoint Type to DynamoDB Endpoint. You can then specify the nodes to attach and preset the data consistency level for this endpoint.

  Note

  After the consistency level is set on a custom endpoint, all read requests to this endpoint use this setting. You cannot override the preset consistency level using the ConsistentRead=true parameter in a single API request.

  

Create a dedicated DynamoDB account

You must create a dedicated DynamoDB account to obtain an AccessKey for API access.

1. On the Settings and Management > Accounts page of the cluster, click Create Account.

2. Set Account Type to DynamoDB Account, and then set the account name and password.

   Note

   The password that you set is used only to manage the account in the console and is not used for API access.

   

3. After the account is created, find it in the account list. The account name is the Access Key ID. Click View in the Key column to obtain the SecretAccess Key.

Configure network access

Choose the appropriate network connection method based on the location of your server or client.

• Private connection (Recommended) If your application is deployed on Alibaba Cloud ECS, make sure that the ECS instance and the PolarDB cluster are in the same VPC. You must also add the IP address or security group of the ECS instance to the cluster's whitelist.

• Internet connection If you want to develop and test in a local environment, or if your ECS instance and the PolarDB cluster are not in the same VPC, you can request an Internet endpoint for the DynamoDB Endpoint in the Database Connections section on the Basic Information page of the cluster.

  Note

  Accessing the cluster over the Internet poses security risks. We recommend that you use an Internet endpoint only for temporary development and testing. Release the Internet endpoint promptly when you are finished.

  

Connect and verify

Use the following Python sample code with the Boto3 software development kit (SDK) to verify that your configuration is correct. This example uses an ECS instance that runs the Alibaba Cloud Linux 3.2104 LTS 64-bit operating system.

1. Navigate to your project directory. This example uses /home/testDynamoDB.

   mkdir /home/testDynamoDB
   cd /home/testDynamoDB

2. In the /home/testDynamoDB directory, create a virtual environment (venv) to isolate project dependencies and avoid affecting the global environment.

   python3 -m venv myenv

3. Activate the virtual environment.

   source myenv/bin/activate

4. Install the required Python dependency library.

   pip3 install boto3

5. Create a Python file and copy the following code into it. Replace endpoint_url, aws_access_key_id, and aws_secret_access_key with the endpoint and DynamoDB account details of your PolarDB cluster.

   vim main.py

   import boto3
   from botocore.exceptions import ClientError
   
   # 1. Configure your connection details
   # The endpoint URL for your PolarDB cluster
   endpoint_url = "http://<your-polardb-ddb-endpoint>:<port>"
   # The Access Key ID for your DynamoDB account
   aws_access_key_id = "<your-access-key-id>"
   # The Secret Access Key for your DynamoDB account
   aws_secret_access_key = "<your-secret-access-key>"
   # For the DynamoDB-compatible feature of PolarDB, region_name must be an empty string.
   region_name = ""
   
   # 2. Create a DynamoDB resource client
   dynamodb = boto3.resource(
       'dynamodb',
       endpoint_url=endpoint_url,
       aws_access_key_id=aws_access_key_id,
       aws_secret_access_key=aws_secret_access_key,
       region_name=region_name,
   )
   
   table_name = 'usertable'
   
   # 3. Define functions for database operations
   def create_table():
       """Creates the table, or gets it if it already exists."""
       try:
           table = dynamodb.create_table(
               TableName=table_name,
               KeySchema=[{'AttributeName': 'userid', 'KeyType': 'HASH'}], # Partition key
               AttributeDefinitions=[{'AttributeName': 'userid', 'AttributeType': 'S'}]
               # ProvisionedThroughput is optional and ignored by PolarDB
           )
           print("Creating table... Waiting for it to become active.")
           table.meta.client.get_waiter('table_exists').wait(TableName=table_name)
           print("Table is active!")
           return table
       except ClientError as e:
           if e.response['Error']['Code'] == 'ResourceInUseException':
               print("Table already exists.")
               return dynamodb.Table(table_name)
           else:
               raise
   
   def put_items(table):
       """Puts a few items into the table."""
       users = [
           {'userid': 'user01', 'name': 'Alice', 'age': 24},
           {'userid': 'user02', 'name': 'Bob', 'age': 30},
           {'userid': 'user03', 'name': 'Charlie', 'age': 28}
       ]
       for user in users:
           table.put_item(Item=user)
       print("Inserted 3 items.")
   
   def scan_table(table):
       """Scans and prints all items in the table."""
       response = table.scan()
       items = response.get('Items', [])
       print(f"Scanned {len(items)} items:")
       for item in items:
           print(item)
   
   def delete_table(table):
       """Deletes the table."""
       table.delete()
       print("Deleting table... Waiting for it to be removed.")
       table.meta.client.get_waiter('table_not_exists').wait(TableName=table_name)
       print("Table deleted successfully.")
   
   # 4. Run the verification process
   if __name__ == '__main__':
       try:
           user_table = create_table()
           put_items(user_table)
           scan_table(user_table)
       finally:
           # Ensure the table is cleaned up even if errors occur
           if 'user_table' in locals():
               delete_table(user_table)

6. After you run the script, the output is similar to the following:

   python3 main.py

   Creating table... Waiting for it to become active.
   Table is active!
   Inserted 3 items.
   Scanned 3 items:
   {'age': Decimal('24'), 'name': 'Alice', 'userid': 'user01'}
   {'age': Decimal('30'), 'name': 'Bob', 'userid': 'user02'}
   {'age': Decimal('28'), 'name': 'Charlie', 'userid': 'user03'}
   Deleting table... Waiting for it to be removed.
   Table deleted successfully.

   This output indicates that you have successfully connected to the database and performed operations, and that all configurations are effective.