DynamoDB (Bring Your Own Table)

If your organization already uses AWS DynamoDB, you can connect your Vulcan app to an existing table. This is a good fit when:

• Your data already lives in DynamoDB and you don't want to duplicate it
• You need to build a UI on top of records that another system writes to DynamoDB
• You have an existing IAM role with the right permissions

This is not platform-provisioned storage. Unlike KV, SQL, and file storage, DynamoDB tables are not created by Vulcan. You supply your own table and AWS credentials.

---

What you need

Before you start, have these ready:

• Table name — the DynamoDB table you want to connect to
• Table region — e.g. us-east-1
• Partition key name — the attribute used as the primary key (e.g. userId, id, pk)
• Sort key name — if your table has one (many don't)
• AWS credentials — an IAM user or role with at least these permissions on the table:
  • dynamodb:GetItem
  • dynamodb:PutItem
  • dynamodb:DeleteItem
  • dynamodb:Query
  • dynamodb:Scan

---

How to set it up

Tell the AI what you want to build and mention that it should use DynamoDB:

"Build a UI for my DynamoDB table. The table is called shipments in us-east-1. The partition key is shipmentId."

The AI will:

1. Add the aws-role-assumption and aws-dynamodb components to your app
2. Prompt you to set three secrets: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_ROLE_ARN
3. Wire up the routes automatically

---

Setting your secrets

When prompted, set each secret in the chat. Your credentials are stored encrypted and are never exposed to the browser — all DynamoDB calls happen in the Worker backend.

→ How secrets work

---

What gets generated

The AI adds four backend routes to your Worker:

Route	What it does
GET /api/dynamo	Scan up to 100 items, or query by ?pk=
GET /api/dynamo/:pk	Get item(s) by partition key; add ?sk= for sort key lookup
POST /api/dynamo	Upsert an item (full replacement; body must include partition key)
DELETE /api/dynamo/:pk	Delete by partition key; add ?sk= for sort key tables

The DocumentClient is used throughout — you send and receive plain JavaScript objects, not raw DynamoDB AttributeValue maps.

---

Partial updates

The default POST /api/dynamo route replaces the full item. If you need to update a single field without overwriting the rest, ask the AI:

"Add a route to update just the status field on a shipment without replacing the whole record."

It will add an UpdateCommand route using DynamoDB's UpdateExpression syntax.

---

Limitations

• One table per component instance. Each aws-dynamodb component connects to a single table. Ask the AI to add another instance if you need a second table.
• Scan is not free. GET /api/dynamo does a full table scan when no pk is provided. For large tables, use ?pk= to query by partition key instead.
• Preview and production share the same table. Unlike KV/SQL/file storage, DynamoDB doesn't have separate preview/production environments — both point to the same AWS table. Be careful when testing writes.

---

Troubleshooting

"The build succeeded but I'm getting 500 errors when fetching data"

• Check that all three secrets (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ROLE_ARN) are set. A missing secret causes auth failures at runtime, not at build time.
• Verify the IAM role has permissions on the specific table (not just DynamoDB in general).

"I'm getting an 'Item must include partition key' error on POST"

• Your request body is missing the partition key attribute. Make sure the field name in your request matches DYNAMO_PK in the Worker code.

"Scan returns nothing but I know the table has data"

• Confirm the table name and region are correct. A wrong region silently connects to a different (possibly empty) table.