sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ aws/ data/ dynamodb.mdx

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 Stream you can react to.
  • SQS — a general-purpose queue for background work, fed from the same Lambda.
  • Table reference — every prop and attribute, including secondary indexes, TTL, and point-in-time recovery.