How to Integrate Retool with Amazon DynamoDB

In the AWS Console, navigate to IAM → Users → Create User. Create a dedicated IAM user named retool-dynamodb with access type 'Programmatic access' (Access Key). Rather than granting AdministratorAccess or DatabaseAdministrator, attach a custom inline policy granting only the DynamoDB actions Retool needs. The minimum policy requires read and write operations on your specific DynamoDB tables. Restrict the Resource field to the specific table ARNs and their indexes rather than using wildcards — for example, arn:aws:dynamodb:us-east-1:123456789:table/customers and arn:aws:dynamodb:us-east-1:123456789:table/customers/index/* for all indexes on that table. After creating the user, go to the Security Credentials tab and create an Access Key. Select 'Application running outside AWS'. Copy the Access Key ID and Secret Access Key. The secret is shown only once — store it in a password manager immediately. For self-hosted Retool running on EC2 or ECS: attach an IAM role to the compute instance with the DynamoDB policy. In the Retool DynamoDB resource, select 'AWS IAM Role' authentication and provide the role ARN instead of access keys. This is the more secure pattern because credentials rotate automatically. For Retool Cloud: you must use access key authentication (role assumption requires self-hosted Retool running in the same AWS account). Retool Cloud proxies all DynamoDB requests through its servers, so your DynamoDB table does not need to be publicly accessible — AWS IAM authentication handles authorization at the API level.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": [
7        "dynamodb:ListTables"
8      ],
9      "Resource": "*"
10    },
11    {
12      "Effect": "Allow",
13      "Action": [
14        "dynamodb:Query",
15        "dynamodb:Scan",
16        "dynamodb:GetItem",
17        "dynamodb:PutItem",
18        "dynamodb:UpdateItem",
19        "dynamodb:DeleteItem",
20        "dynamodb:DescribeTable",
21        "dynamodb:BatchWriteItem",
22        "dynamodb:BatchGetItem"
23      ],
24      "Resource": [
25        "arn:aws:dynamodb:us-east-1:YOUR_ACCOUNT_ID:table/your-table-name",
26        "arn:aws:dynamodb:us-east-1:YOUR_ACCOUNT_ID:table/your-table-name/index/*"
27      ]
28    }
29  ]
30}

Open your Retool instance and navigate to the Resources tab in the left sidebar. Click Add Resource. In the resource type list, find 'Amazon DynamoDB' under the Database category or search for 'DynamoDB'. Enter a descriptive name for the resource: 'DynamoDB Production us-east-1' or 'Customer Data DynamoDB' works well. In the Authentication section, select 'AWS Access Key'. Enter the Access Key ID and Secret Access Key from the IAM user you created. In the Region dropdown, select the AWS region where your DynamoDB tables reside — this is critical and must match exactly. For role-based authentication on self-hosted Retool: select 'AWS IAM Role' and enter the role ARN (arn:aws:iam::ACCOUNT_ID:role/RoleName). If Retool is running on EC2/ECS with an instance profile, select 'Use Instance Role' and no credentials are needed. Click Save Changes. Retool tests the connection by attempting to call the DynamoDB ListTables API. A green success message confirms the connection. If you see an error, double-check the region setting — mismatched region is the most common cause of DynamoDB connection failures. Note: unlike Retool's database resources (PostgreSQL, MySQL), DynamoDB does not require a host, port, or connection string. Authentication is entirely through AWS IAM, and the DynamoDB endpoint is automatically determined from the configured AWS region.

Open a Retool app and create a new query. Select your DynamoDB resource. The DynamoDB query editor shows a Table Name field and an Action dropdown with the available DynamoDB operations: Query, Scan, GetItem, PutItem, UpdateItem, DeleteItem, DescribeTable, and ListTables. Understanding the difference between Query and Scan is essential for DynamoDB performance: - Query: retrieves items using the partition key (required) and optionally the sort key. Fast and efficient — reads only the items that match the key. Use this for customer lookups, order history, and any access pattern aligned with your table's key schema. - Scan: reads every item in the table and applies a filter. Expensive for large tables (reads and charges all items even if only a few match). Use for admin exploration and small tables — never for high-frequency production queries. For a Query operation: set Action to Query, enter the Table Name. In the Key Condition Expression field, enter the condition using DynamoDB expression syntax: customer_id = :pk. In the Expression Attribute Values section, define the value for :pk using {{ }} to reference a Retool component: { ":pk": { "S": "{{ customerIdInput.value }}" } }. Note that DynamoDB requires explicit type definitions — { "S": value } for strings, { "N": "123" } for numbers (as strings), { "BOOL": true } for booleans. For a Scan with filter: set Action to Scan. In the Filter Expression field, enter status = :status AND created_at > :since. In Expression Attribute Values, define each placeholder. Create a JavaScript transformer to flatten and format the DynamoDB response. DynamoDB wraps every attribute value in a type descriptor, so { customer_id: { S: 'abc123' }, amount: { N: '99.99' } } needs to be unwrapped into { customer_id: 'abc123', amount: 99.99 } for display in Retool tables.

1// DynamoDB response transformer — unwrap DynamoDB type descriptors
2// Input: data (array of raw DynamoDB items from Query or Scan)
3
4const items = data || [];
5
6// Helper function to unwrap DynamoDB typed values
7function unwrapDynamoDBValue(val) {
8  if (val.S !== undefined) return val.S;
9  if (val.N !== undefined) return parseFloat(val.N);
10  if (val.BOOL !== undefined) return val.BOOL;
11  if (val.NULL !== undefined) return null;
12  if (val.L !== undefined) return val.L.map(unwrapDynamoDBValue);
13  if (val.M !== undefined) {
14    return Object.entries(val.M).reduce((obj, [k, v]) => {
15      obj[k] = unwrapDynamoDBValue(v);
16      return obj;
17    }, {});
18  }
19  if (val.SS !== undefined) return val.SS;
20  if (val.NS !== undefined) return val.NS.map(parseFloat);
21  return val;
22}
23
24return items.map(item =>
25  Object.entries(item).reduce((obj, [key, value]) => {
26    obj[key] = unwrapDynamoDBValue(value);
27    return obj;
28  }, {})
29);

DynamoDB's write operations in Retool use the PutItem, UpdateItem, and DeleteItem actions. Understanding when to use each is important: - PutItem: creates a new item or completely replaces an existing item with the same primary key. Use for creating new records. - UpdateItem: modifies specific attributes of an existing item without replacing the whole item. Use for targeted updates. - DeleteItem: removes an item by its primary key. For an Update operation: create a query named updateItem. Set Action to UpdateItem. Set Table Name and the partition key value: { "customer_id": { "S": "{{ table1.selectedRow.data.customer_id }}" } }. For tables with a sort key, include it here too. In the Update Expression field, enter: SET status = :newStatus, updated_at = :now. In Expression Attribute Values: { ":newStatus": { "S": "{{ statusSelect.value }}" }, ":now": { "S": "{{ new Date().toISOString() }}" } }. For creating a new item: set Action to PutItem. In the Item field, provide the full item as a typed JSON object. Reference form component values for each attribute. For conditional updates (updating only if the item hasn't been modified by another process): add a Condition Expression such as attribute_exists(customer_id) AND version = :expectedVersion. DynamoDB returns a ConditionalCheckFailedException if the condition fails, which you can catch in Retool's error handlers. Chain write operations with data refresh: in each write query's Event Handlers section, add an On Success handler that triggers your listData query to refresh the table. Add an On Failure handler to show a notification with the error message using {{ queryName.error.message }}.

1// UpdateItem query configuration
2// Action: UpdateItem
3// Table Name: customers
4// Key:
5{
6  "customer_id": { "S": "{{ table1.selectedRow.data.customer_id }}" }
7}
8
9// Update Expression:
10// SET #status = :newStatus, updated_at = :now, notes = :notes
11
12// Expression Attribute Names (for reserved words like 'status'):
13{
14  "#status": "status"
15}
16
17// Expression Attribute Values:
18{
19  ":newStatus": { "S": "{{ statusDropdown.value }}" },
20  ":now": { "S": "{{ new Date().toISOString() }}" },
21  ":notes": { "S": "{{ notesInput.value }}" }
22}
23
24// Condition Expression (optional — ensure item exists):
25// attribute_exists(customer_id)

DynamoDB Query and Scan operations return a maximum of 1 MB of data per request. For tables with large items or many results, Retool's DynamoDB connector returns a LastEvaluatedKey in the response when more items are available. Implement pagination by storing this key and passing it as ExclusiveStartKey in subsequent queries. For Global Secondary Indexes (GSIs): in the Query action, set the Index Name field to your GSI name (e.g., status-created_at-index). The Key Condition Expression must reference the GSI's partition key, not the table's partition key. For example, if your GSI has status as its partition key, use status = :s instead of customer_id = :id. For begins_with queries on sort keys (common for time-range filtering with ISO date prefixes): use the sort key condition BETWEEN :start AND :end or begins_with(created_at, :prefix) in the Key Condition Expression. For complex admin exploration where you need to inspect all items in a table: build a Scan-based explorer with configurable filter expressions. Use a TextInput component for the Filter Expression, another for Expression Attribute Values (as a JSON string parsed with JSON.parse({{ filterValuesInput.value }})), and bind results to a Table. This gives engineers a direct DynamoDB query interface from within Retool. For complex multi-table DynamoDB dashboards with batch operations, Retool Workflows, and sophisticated data transformation pipelines, RapidDev's team can help architect and build your complete Retool solution.

1// GSI Query configuration example
2// Table: orders
3// Index Name: status-created_at-index
4// Action: Query
5// Key Condition Expression:
6// #status = :s AND created_at BETWEEN :start AND :end
7
8// Expression Attribute Names:
9{
10  "#status": "status"
11}
12
13// Expression Attribute Values:
14{
15  ":s": { "S": "{{ statusFilter.value }}" },
16  ":start": { "S": "{{ moment(dateRange.startDate).toISOString() }}" },
17  ":end": { "S": "{{ moment(dateRange.endDate).endOf('day').toISOString() }}" }
18}
19
20// Scan Limit: 100
21// Filter Expression (additional non-key filter):
22// amount > :minAmount
23// Expression Attribute Values (add to above):
24// ":minAmount": { "N": "{{ minAmountInput.value || '0' }}" }