Getting Started

Get up and running with effect-dynamodb in five minutes. This guide walks you through setting up a local DynamoDB instance, defining a model, creating a table and entity, and performing basic CRUD operations.

Prerequisites

• Node.js 18+
• Docker installed and running
• Basic familiarity with Effect TS and Effect Schema

Running DynamoDB Local

For local development, use DynamoDB Local — a Docker image that runs a local instance of DynamoDB with no AWS account required.

Start a DynamoDB Local container:

docker run -d -p 8000:8000 --name dynamodb-local amazon/dynamodb-local

This starts DynamoDB Local on port 8000 in the background. The container persists until you stop it:

docker stop dynamodb-local   # stop
docker start dynamodb-local  # restart later
docker rm dynamodb-local     # remove when done

To verify it’s running:

export AWS_ACCESS_KEY_ID=local
export AWS_SECRET_ACCESS_KEY=local
aws dynamodb list-tables --endpoint-url http://localhost:8000 --region us-east-1

Tip

DynamoDB Local doesn’t validate credentials — any values will work. The inline env vars above avoid needing real AWS credentials configured.

Installation

pnpm add effect-dynamodb effect @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb

Quick Start: A Single Entity

1. Define a Model

Models are plain Effect Schema definitions — no DynamoDB concepts. Use Schema.Class for class instances with instanceof support, or Schema.Struct for plain objects.

import { Schema } from "effect"

class Todo extends Schema.Class<Todo>("Todo")({
  todoId: Schema.String,
  title:  Schema.NonEmptyString,
  done:   Schema.Boolean,
}) {}

2. Create a Schema

import { DynamoSchema } from "effect-dynamodb"

const AppSchema = DynamoSchema.make({
  name: "myapp",
  version: 1,
})

3. Define an Entity

The Entity definition connects your model to the table with key composition rules and optional features.

import { Entity } from "effect-dynamodb"

const TodoEntity = Entity.make({
  model: Todo,
  entityType: "Todo",
  primaryKey: {
    pk: { field: "pk", composite: ["todoId"] },
    sk: { field: "sk", composite: [] },
  },
  timestamps: true,
})

This tells effect-dynamodb:

• The partition key is composed from todoId
• The sort key is just the entity type prefix (no additional attributes)
• createdAt and updatedAt are automatically managed

4. Register on a Table

Register your entity on a table definition. The physical DynamoDB table name is not set here — it’s runtime configuration provided via MainTable.layer({ name: "..." }) when you run the program.

import { Table } from "effect-dynamodb"

const MainTable = Table.make({ schema: AppSchema, entities: { TodoEntity } })

5. Use It

Call DynamoClient.make({ entities, tables }) to get a typed client with executable operations. The typed client includes table management methods that derive the physical table definition (primary key, GSIs) from your registered entities — no manual CreateTable calls needed.

DynamoClient.make() resolves DynamoClient and TableConfig from the Effect context — you provide these as Layers when you run the program.

import { Effect, Console, Layer } from "effect"
import { DynamoClient, Entity } from "effect-dynamodb"

const program = Effect.gen(function* () {
  // Required gateway — resolves dependencies, returns executable operations
  const db = yield* DynamoClient.make({
    entities: { TodoEntity },
    tables: { MainTable },
  })

  // Create the table — derived from entity definitions
  yield* db.tables.MainTable.create()

  // Create
  const todo = yield* db.entities.TodoEntity.put({
    todoId: "t-1",
    title: "Learn effect-dynamodb",
    done: false,
  })
  yield* Console.log("Todo", todo)
  // { todoId: "t-1", title: "Learn effect-dynamodb", done: false,
  //   createdAt: DateTime.Utc, updatedAt: DateTime.Utc }

  // Read
  const found = yield* db.entities.TodoEntity.get({ todoId: "t-1" })
  yield* Console.log("Found", found)

  // Update
  yield* db.entities.TodoEntity.update({ todoId: "t-1" }).set({ done: true })

  // Delete
  yield* db.entities.TodoEntity.delete({ todoId: "t-1" })
})

// Run with DynamoDB Local
const main = program.pipe(
  Effect.provide(
    Layer.mergeAll(
      DynamoClient.layer({
        region: "us-east-1",
        endpoint: "http://localhost:8000",
        credentials: { accessKeyId: "local", secretAccessKey: "local" },
      }),
      // Physical DynamoDB table name — required runtime configuration
      MainTable.layer({ name: "quickstart" }),
    )
  )
)

Effect.runPromise(main)

Note

create() uses PAY_PER_REQUEST billing by default, which is ideal for development. For production, configure billing mode via db.tables.MainTable.create({ billingMode: "PROVISIONED" }) or create the table through infrastructure-as-code (CloudFormation, CDK, Terraform).

Save this as quickstart.ts and run it:

npx tsx quickstart.ts

Coming from Effect v3?

Notice that every operation above is called on db.entities.TodoEntity (the bound entity returned from DynamoClient.make(...)), not on the TodoEntity definition directly. That’s deliberate. In Effect v4, TodoEntity.get(...) returns a Yieldable operation descriptor, not an Effect — yield* TodoEntity.get(key) works inside Effect.gen, but TodoEntity.get(key).pipe(Effect.map(...)) does not (this matches v4’s Option-is-not-an-Effect convention).

db.entities.TodoEntity.get(key) auto-wraps the descriptor into a real Effect<A, E, never>, so you get straightforward pipe/Effect.map/Effect.flatMap ergonomics. Use db.entities.X from DynamoClient.make() for day-to-day code. Reach for raw entity descriptors only when you need to compose them into a Transaction/Batch or to swap decode modes — see the Entity reference for details.

What Gets Stored in DynamoDB

For the put call above, effect-dynamodb generates:

Attribute	Value
pk	$myapp#v1#todo#t-1
sk	$myapp#v1#todo
__edd_e__	Todo
todoId	t-1
title	Learn effect-dynamodb
done	false
createdAt	2024-01-15T10:30:00.000Z
updatedAt	2024-01-15T10:30:00.000Z

The key format ($myapp#v1#todo#t-1) is automatically generated from the schema, version, entity type, and composite attributes. You declare which attributes compose the key — the system handles how.

Optional Packages

Language Service Plugin

The TypeScript Language Service Plugin enhances IDE hover tooltips to show the DynamoDB operations that effect-dynamodb will execute. Hover over db.entities.Users.get(...), db.entities.Users.byRole(...), or any entity operation to see the underlying DynamoDB command, key structure, and index being used.

pnpm add -D @effect-dynamodb/language-service

Add the plugin to your tsconfig.json:

{
  "compilerOptions": {
    "plugins": [
      { "name": "@effect-dynamodb/language-service" }
    ]
  }
}

For example, hovering over get in the quick start above shows the underlying DynamoDB command (scroll to the bottom of the tooltip):

  ┌──────────────────────────────────────────────┐
  │ ...                                          │
  │ ...                                          │
  │                                              │
  │ effect-dynamodb — Native DynamoDB operation  │
  │                                              │
  │ GetItemCommand({                             │
  │   TableName: "{TableName}",                  │
  │   Key: {                                     │
  │     pk: "$myapp#v1#todo#t-1",                │
  │     sk: "$myapp#v1#todo",                    │
  │   },                                         │
  │ })                                           │
  └──────────────────────────────────┬──────────-┘
                                     ▼
  const found = yield* db.entities.TodoEntity.get({ todoId: "t-1" })

The plugin detects get, put, create, update, delete, query, and scan operations, resolves entities across imported modules, and shows composed keys and expressions — all directly in your editor’s hover tooltip.

Geospatial Package

For proximity-based queries (e.g., “find all vehicles within 2 km”), the geo package adds H3 hexagonal grid indexing on top of effect-dynamodb entities.

pnpm add @effect-dynamodb/geo

See the Geospatial guide for setup and usage.

What’s Next?

• Modeling — Learn about Schema.Class models, DynamoSchema, Table, Entity, and derived types
• Indexes & Collections — Define access patterns with primary and secondary indexes
• Queries — Use the pipeable Query API for composable, type-safe queries
• Data Integrity — Unique constraints, versioning, and optimistic concurrency
• Lifecycle — Soft delete, restore, purge, and version retention
• Advanced — Rich updates, batch operations, multi-table design
• DynamoDB Streams — Decode stream records into typed domain objects
• Testing — Mock DynamoClient and test patterns