DynamoDB is AWS's serverless key/value store — structured
records looked up by partition (and optional sort) key, with no
capacity to manage. In Alchemy it's the Table resource plus a
binding per operation: GetItem, PutItem, UpdateItem,
DeleteItem, Query, Scan, and the batch/transact variants.
Each binding attaches a least-privilege IAM statement scoped to
the table's ARN. Tables are also an event source: enable
DynamoDB Streams and consume change records in a Lambda with
DynamoDB.consumeTableChanges (see the
DynamoDB Streams guide).
The walkthrough below builds on the Lambda and
S3 pages: it adds a Table and binds GetItem +
PutItem to the function — same pattern as S3, different
storage.
Define the table
DynamoDB tables need a partition key (and optionally a sort key)
declared up-front. Yield the Table resource in the function's
constructor, mirroring how you added the bucket:
// src/api.ts
import * as AWS from "@alchemy.run/aws";
+import * as DynamoDB from "@alchemy.run/aws/DynamoDB";
import * as S3 from "@alchemy.run/aws/S3";
import { Stack } from "alchemy/Stack";
import * as Effect from "effect/Effect";
// ...
Effect.gen(function* () {
const bucket = yield* S3.Bucket("Blobs");
+ const table = yield* DynamoDB.Table("Items", {
+ partitionKey: "id",
+ attributes: {
+ id: "S",
+ },
+ });
// ... existing bindings + handler ...
}); attributes only needs to list the attributes used by keys (and
secondary indexes) — DynamoDB itself is schemaless on the rest of
the row. "S" is the AWS shorthand for "string"; "N" is number
and "B" is binary.
Bind GetItem and PutItem
Same shape as the S3 bindings — PutItem(table) returns a callable
Effect and quietly attaches a least-privilege IAM policy scoped to
this table's ARN:
Effect.gen(function* () {
const bucket = yield* S3.Bucket("Blobs");
const table = yield* DynamoDB.Table("Items", { /* ... */ });
const putObject = yield* S3.PutObject(bucket);
const getObject = yield* S3.GetObject(bucket);
+ const putItem = yield* DynamoDB.PutItem(table);
+ const getItem = yield* DynamoDB.GetItem(table);
return { fetch: /* ... */ };
}); Write items with PUT /items/:id
Add a branch to fetch that writes a row keyed by the URL
segment. DynamoDB takes attribute values in their native typed
form — { S: "..." } for strings, { N: "42" } for numbers —
and Alchemy bindings deliberately don't auto-marshal so you
stay on the raw SDK shape:
fetch: Effect.gen(function* () {
const request = yield* HttpServerRequest;
const url = new URL(request.url);
const path = url.pathname;
+ if (path.startsWith("/items/") && request.method === "PUT") {
+ const id = path.slice("/items/".length);
+ const content = yield* request.text;
+ yield* putItem({
+ Item: {
+ id: { S: id },
+ content: { S: content },
+ },
+ });
+ return HttpServerResponse.empty({ status: 204 });
+ }
// ... existing /:key blob routes ...
}).pipe(Effect.orDie), Skipping marshalling keeps the binding tiny and avoids a
debate over which marshalling layer to use. If you want a
typed-object API across your codebase, build it as a thin
wrapper around putItem — the binding won't fight you.
Read items with GET /items/:id
The read path uses getItem with the same { S: id } key
shape:
if (path.startsWith("/items/") && request.method === "PUT") {
// ... unchanged ...
}
+if (path.startsWith("/items/") && request.method === "GET") {
+ const id = path.slice("/items/".length);
+ const result = yield* getItem({ Key: { id: { S: id } } });
+ if (!result.Item) {
+ return HttpServerResponse.text("Not found", { status: 404 });
+ }
+ return yield* HttpServerResponse.json({
+ id: result.Item.id?.S,
+ content: result.Item.content?.S,
+ });
+} getItem returns result.Item as undefined when the row
doesn't exist — no need for a typed catchTag like S3's
NoSuchKey. Map the AWS attribute-value shape back to a plain
object at the response boundary.
Provide the runtime layers
Add the DynamoDB lives next to the S3 ones:
}).pipe(
Effect.provide(
Layer.mergeAll(
AWS.Lambda.BucketEventSource,
+ DynamoDB.GetItemHttp,
+ DynamoDB.PutItemHttp,
S3.PutObjectHttp,
S3.GetObjectHttp,
),
),
), Deploy and verify
bun alchemy deploy Add a round-trip test that exercises the new routes:
// test/integ.test.ts
test(
"DynamoDB round-trip",
Effect.gen(function* () {
const { url } = yield* stack;
yield* HttpClient.put(`${url}/items/abc`, {
body: HttpBody.text("hello dynamo"),
});
const get = yield* HttpClient.get(`${url}/items/abc`);
expect(yield* get.json).toEqual({ id: "abc", content: "hello dynamo" });
}),
); bun test test/integ.test.ts The IAM policy attached to your function role now includes
dynamodb:GetItem and dynamodb:PutItem — both scoped to this
specific table — alongside the S3 grants.
Where next
- Process DynamoDB Streams —
fan table changes out into a Lambda-side
Streamyou can react to. - SQS — a general-purpose queue for background work, fed from the same Lambda.
Tablereference — every prop and attribute, including secondary indexes, TTL, and point-in-time recovery.