DynamoDB ORMs compared: ElectroDB, Toolbox, Dynamoose, OneTable

A DynamoDB ORM is usually a data mapper or query builder that adds schemas, validation and typed operations to DynamoDB. For a new Node.js or TypeScript application, start with ElectroDB for access patterns and composite keys, DynamoDB Toolbox for explicit, typed request building, or Dynamoose for a model-oriented API. OneTable is now archived and no longer maintained, so treat it as an existing-application or migration choice, not a default for new development.

This comparison was checked on October 23, 2026. Each library below implements the same Customer and Order model, including a GSI query and an update that changes the index key. All four examples ran against DynamoDB Local; the output is included.

Do you need a DynamoDB ORM?

DynamoDB does not become a relational database when you add a modeling library. You still choose partition keys, sort keys and indexes around access patterns. A relationship between Customer and Order does not create a server-side join or a foreign-key constraint. Start with the single-table design guide if those choices are still unsettled.

The official SDK's DynamoDBDocumentClient already accepts ordinary JavaScript objects and converts them to DynamoDB's attribute-value representation. It does not define your application's Customer schema, derive an order's index keys or infer a domain-specific response type from a model. See AWS's JavaScript examples and our Node.js guide for that baseline.

Use a library when several parts of your application repeat the same key templates, validation rules and update expressions. Keep the SDK alone when you have a few straightforward operations, an established validation layer, or need direct access to a new API before a wrapper exposes it. A small repository module around SDK commands can be enough.

The SDK layer differs: ElectroDB and Toolbox accept the v3 document client used here; Dynamoose and OneTable use their own conversion paths over the low-level v3 client. Schema validation runs in application code. Another writer using the SDK or console can still store items that violate that schema.

Current versions, licenses and maintenance

These are the npm latest versions, not prereleases or unreleased repository code. Publication dates are UTC. The package links expose npm's version and publication metadata; repository status was checked separately on the same day.

A release date is evidence of publication, not a support guarantee. OneTable's archive notice is more decisive than its release gap: its old feature set remains useful to understand, but a successful local run does not establish future SDK compatibility or security maintenance.

ElectroDB vs DynamoDB Toolbox vs Dynamoose vs OneTable

All four support single-table layouts, SDK v3, batch operations and transactions. The practical difference is how much of the key design and model behavior they represent in the schema.

The API references document ElectroDB's keys, Toolbox entities, Dynamoose models and OneTable's schema and operations. Dynamoose's TypeScript documentation still labels its typings beta; its domain class and runtime schema must be kept in agreement. OneTable's TypeScript guide explains schema-derived models.

Transaction support is documented for ElectroDB, Toolbox, Dynamoose and OneTable. These wrappers do not change DynamoDB's limits: a write transaction supports up to 100 distinct items and 4 MB, while a batch write is not atomic. Use the transaction guide when Customer and Order must be committed together. The examples below deliberately perform independent writes.

Which DynamoDB library should you choose?

ElectroDB vs DynamoDB Toolbox

Choose based on where you want access-pattern knowledge to live. In the ElectroDB example, byStatus is a named query derived from attributes. In Toolbox, the table query names the index and supplies the partition value explicitly. Toolbox can also derive attributes through defaults and links; it is not limited to hand-built keys.

ElectroDB's conventions become helpful when they eliminate repeated key logic across many entities. Toolbox is a good fit when you want to see individual commands and adapt them to an existing schema. Both can generate request parameters for inspection. Neither choice removes the need to inspect the resulting key condition and distinguish it from a filter.

Dynamoose vs ElectroDB

Dynamoose centers the model and its schema. ElectroDB centers the entity's attributes and access patterns. If your main problem is expressing several composite-key queries consistently, start with ElectroDB. If your team wants model methods and accepts maintaining explicit TypeScript classes alongside the schemas, evaluate Dynamoose.

Do not use local request durations to choose a winner. The examples measure correctness, not speed, cold starts, bundle size or production throughput. The broader DynamoDB tools directory covers clients and infrastructure tools outside this comparison.

The same Customer and Order model in every library

Each implementation uses its own table so library-specific entity metadata cannot interfere with another example. The business attributes and physical key values are identical. This is single-table design within each implementation, not four libraries sharing one live data format.

The byStatus GSI has partition key gsi1pk and sort key gsi1sk, with an ALL projection. The order starts with gsi1pk=CUSTOMER#c1#STATUS#PAID and gsi1sk=ORDER#o1. Customer items omit both GSI keys, so they do not appear in that index.

The access patterns are: retrieve a customer, retrieve an order by customer and order IDs, and list one customer's orders with a given status. Including the customer ID in the GSI partition avoids putting every customer's paid orders under one global PAID key. It does not eliminate the possibility of a particularly busy customer becoming a hot key.

Each program writes both items, reads them, queries paid orders, updates the order to shipped, and queries both statuses again. ElectroDB and OneTable derive the changed index key from templates. The Toolbox and Dynamoose examples update it explicitly in the same item request. Updating only status in those explicit implementations would leave the index entry under the old key.

Run the examples against DynamoDB Local

Use an empty working directory and Node.js 24. The tested environment was Node.js 24.18.1, TypeScript 7.0.2, tsx 4.23.15, AWS SDK packages 3.1156.0, and DynamoDB Local 3.3.2. The library versions are pinned below.

npm init -y
npm pkg set type=module
npm install --save-exact electrodb@3.9.3 dynamodb-toolbox@2.11.1 \
  dynamoose@4.2.0 dynamodb-onetable@2.7.7 \
  @aws-sdk/client-dynamodb@3.1156.0 @aws-sdk/lib-dynamodb@3.1156.0 \
  typescript@7.0.2 tsx@4.23.15 @types/node@26.6.5

docker run -d --rm --name dynamodb-local -p 8000:8000 \
  amazon/dynamodb-local:3.3.2 -jar DynamoDBLocal.jar \
  -inMemory -sharedDb -disableTelemetry
npm init -y
npm pkg set type=module
npm install --save-exact electrodb@3.9.3 dynamodb-toolbox@2.11.1 \
  dynamoose@4.2.0 dynamodb-onetable@2.7.7 \
  @aws-sdk/client-dynamodb@3.1156.0 @aws-sdk/lib-dynamodb@3.1156.0 \
  typescript@7.0.2 tsx@4.23.15 @types/node@26.6.5

docker run -d --rm --name dynamodb-local -p 8000:8000 \
  amazon/dynamodb-local:3.3.2 -jar DynamoDBLocal.jar \
  -inMemory -sharedDb -disableTelemetry

Wait for the container to start. All clients below use http://localhost:8000 and dummy credentials. Save the following five TypeScript files together. Their .js import specifiers work with tsx and the NodeNext TypeScript configuration shown later.

The immediate GSI assertions are a local correctness check. AWS documents that DynamoDB Local reads often appear strongly consistent, while GSI updates in AWS propagate asynchronously. An application using the managed service must tolerate index lag; a successful write is not a guarantee that the next GSI query sees it.

Shared setup: shared.ts

This creates one table per example and checks the normalized results. totalCents keeps the sample amount as an integer. The scripts expect fresh table names; to repeat the full exercise, stop and restart the in-memory container.

import assert from "node:assert/strict"
import {
  CreateTableCommand, DynamoDBClient, waitUntilTableExists,
} from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"

export const config = {
  endpoint: "http://localhost:8000",
  region: "us-east-1",
  credentials: { accessKeyId: "fake", secretAccessKey: "fake" },
}
export const client = new DynamoDBClient(config)
export const documentClient = DynamoDBDocumentClient.from(client)

export async function createTable(name: string) {
  await client.send(new CreateTableCommand({
    TableName: name,
    BillingMode: "PAY_PER_REQUEST",
    AttributeDefinitions: ["pk", "sk", "gsi1pk", "gsi1sk"].map(name => ({
      AttributeName: name, AttributeType: "S",
    })),
    KeySchema: [
      { AttributeName: "pk", KeyType: "HASH" },
      { AttributeName: "sk", KeyType: "RANGE" },
    ],
    GlobalSecondaryIndexes: [{
      IndexName: "byStatus",
      KeySchema: [
        { AttributeName: "gsi1pk", KeyType: "HASH" },
        { AttributeName: "gsi1sk", KeyType: "RANGE" },
      ],
      Projection: { ProjectionType: "ALL" },
    }],
  }))
  await waitUntilTableExists({ client, maxWaitTime: 30 }, { TableName: name })
  return name
}

export const customer = { customerId: "c1", name: "Ada" }
export const order = {
  customerId: "c1", orderId: "o1", status: "PAID", totalCents: 4200,
} as const
export const id = { customerId: "c1", orderId: "o1" }

export function report(library: string, result: {
  customer: string | undefined; before: string | undefined
  paid: string[]; after: string | undefined
  shipped: string[]; paidAfter: string[]
}) {
  assert.deepEqual(result, {
    customer: "Ada", before: "PAID", paid: ["o1"],
    after: "SHIPPED", shipped: ["o1"], paidAfter: [],
  })
  console.log(JSON.stringify({ library, ...result }))
}
import assert from "node:assert/strict"
import {
  CreateTableCommand, DynamoDBClient, waitUntilTableExists,
} from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"

export const config = {
  endpoint: "http://localhost:8000",
  region: "us-east-1",
  credentials: { accessKeyId: "fake", secretAccessKey: "fake" },
}
export const client = new DynamoDBClient(config)
export const documentClient = DynamoDBDocumentClient.from(client)

export async function createTable(name: string) {
  await client.send(new CreateTableCommand({
    TableName: name,
    BillingMode: "PAY_PER_REQUEST",
    AttributeDefinitions: ["pk", "sk", "gsi1pk", "gsi1sk"].map(name => ({
      AttributeName: name, AttributeType: "S",
    })),
    KeySchema: [
      { AttributeName: "pk", KeyType: "HASH" },
      { AttributeName: "sk", KeyType: "RANGE" },
    ],
    GlobalSecondaryIndexes: [{
      IndexName: "byStatus",
      KeySchema: [
        { AttributeName: "gsi1pk", KeyType: "HASH" },
        { AttributeName: "gsi1sk", KeyType: "RANGE" },
      ],
      Projection: { ProjectionType: "ALL" },
    }],
  }))
  await waitUntilTableExists({ client, maxWaitTime: 30 }, { TableName: name })
  return name
}

export const customer = { customerId: "c1", name: "Ada" }
export const order = {
  customerId: "c1", orderId: "o1", status: "PAID", totalCents: 4200,
} as const
export const id = { customerId: "c1", orderId: "o1" }

export function report(library: string, result: {
  customer: string | undefined; before: string | undefined
  paid: string[]; after: string | undefined
  shipped: string[]; paidAfter: string[]
}) {
  assert.deepEqual(result, {
    customer: "Ada", before: "PAID", paid: ["o1"],
    after: "SHIPPED", shipped: ["o1"], paidAfter: [],
  })
  console.log(JSON.stringify({ library, ...result }))
}

ElectroDB: electro.ts

The explicit templates preserve the common layout. casing: "none" preserves the key text exactly; ElectroDB's default key casing differs. patch() requires an existing item, and changing status causes ElectroDB to calculate the GSI key from the supplied composite attributes.

import { Entity } from "electrodb"
import { createTable, documentClient, customer, order, id, report } from "./shared.js"

const table = await createTable("OrmElectro")
const options = { table, client: documentClient }
const Customer = new Entity({
  model: { entity: "Customer", service: "shop", version: "1" },
  attributes: {
    customerId: { type: "string", required: true },
    name: { type: "string", required: true },
  },
  indexes: {
    primary: {
      pk: { field: "pk", composite: ["customerId"], template: "CUSTOMER#${customerId}", casing: "none" },
      sk: { field: "sk", composite: [], template: "PROFILE", casing: "none" },
    },
  },
}, options)
const Order = new Entity({
  model: { entity: "Order", service: "shop", version: "1" },
  attributes: {
    customerId: { type: "string", required: true },
    orderId: { type: "string", required: true },
    status: { type: ["PAID", "SHIPPED"] as const, required: true },
    totalCents: { type: "number", required: true },
  },
  indexes: {
    primary: {
      pk: { field: "pk", composite: ["customerId"], template: "CUSTOMER#${customerId}", casing: "none" },
      sk: { field: "sk", composite: ["orderId"], template: "ORDER#${orderId}", casing: "none" },
    },
    byStatus: {
      index: "byStatus",
      pk: { field: "gsi1pk", composite: ["customerId", "status"], template: "CUSTOMER#${customerId}#STATUS#${status}", casing: "none" },
      sk: { field: "gsi1sk", composite: ["orderId"], template: "ORDER#${orderId}", casing: "none" },
    },
  },
}, options)

await Customer.put(customer).go()
await Order.put(order).go()
const savedCustomer = await Customer.get({ customerId: "c1" }).go({ consistent: true })
const before = await Order.get(id).go({ consistent: true })
const paid = await Order.query.byStatus({ customerId: "c1", status: "PAID" }).go()
const after = await Order.patch(id).set({ status: "SHIPPED" }).go({ response: "all_new" })
const shipped = await Order.query.byStatus({ customerId: "c1", status: "SHIPPED" }).go()
const paidAfter = await Order.query.byStatus({ customerId: "c1", status: "PAID" }).go()
report("ElectroDB", {
  customer: savedCustomer.data?.name, before: before.data?.status,
  paid: paid.data.map(item => item.orderId), after: after.data?.status,
  shipped: shipped.data.map(item => item.orderId), paidAfter: paidAfter.data.map(item => item.orderId),
})
import { Entity } from "electrodb"
import { createTable, documentClient, customer, order, id, report } from "./shared.js"

const table = await createTable("OrmElectro")
const options = { table, client: documentClient }
const Customer = new Entity({
  model: { entity: "Customer", service: "shop", version: "1" },
  attributes: {
    customerId: { type: "string", required: true },
    name: { type: "string", required: true },
  },
  indexes: {
    primary: {
      pk: { field: "pk", composite: ["customerId"], template: "CUSTOMER#${customerId}", casing: "none" },
      sk: { field: "sk", composite: [], template: "PROFILE", casing: "none" },
    },
  },
}, options)
const Order = new Entity({
  model: { entity: "Order", service: "shop", version: "1" },
  attributes: {
    customerId: { type: "string", required: true },
    orderId: { type: "string", required: true },
    status: { type: ["PAID", "SHIPPED"] as const, required: true },
    totalCents: { type: "number", required: true },
  },
  indexes: {
    primary: {
      pk: { field: "pk", composite: ["customerId"], template: "CUSTOMER#${customerId}", casing: "none" },
      sk: { field: "sk", composite: ["orderId"], template: "ORDER#${orderId}", casing: "none" },
    },
    byStatus: {
      index: "byStatus",
      pk: { field: "gsi1pk", composite: ["customerId", "status"], template: "CUSTOMER#${customerId}#STATUS#${status}", casing: "none" },
      sk: { field: "gsi1sk", composite: ["orderId"], template: "ORDER#${orderId}", casing: "none" },
    },
  },
}, options)

await Customer.put(customer).go()
await Order.put(order).go()
const savedCustomer = await Customer.get({ customerId: "c1" }).go({ consistent: true })
const before = await Order.get(id).go({ consistent: true })
const paid = await Order.query.byStatus({ customerId: "c1", status: "PAID" }).go()
const after = await Order.patch(id).set({ status: "SHIPPED" }).go({ response: "all_new" })
const shipped = await Order.query.byStatus({ customerId: "c1", status: "SHIPPED" }).go()
const paidAfter = await Order.query.byStatus({ customerId: "c1", status: "PAID" }).go()
report("ElectroDB", {
  customer: savedCustomer.data?.name, before: before.data?.status,
  paid: paid.data.map(item => item.orderId), after: after.data?.status,
  shipped: shipped.data.map(item => item.orderId), paidAfter: paidAfter.data.map(item => item.orderId),
})

DynamoDB Toolbox: toolbox.ts

computeKey derives the primary key from the schema's key attributes. Here the GSI attributes are explicit so the update shows exactly what is sent. If you replace this with schema links, configure update-time behavior too: .link() on a non-key attribute is a put-time shorthand, not an automatic update hook. The update also requires the existing order attribute.

import {
  Table, Entity, item, string, number,
  PutItemCommand, GetItemCommand, QueryCommand, UpdateItemCommand,
} from "dynamodb-toolbox"
import { createTable, documentClient, customer, order, id, report } from "./shared.js"

const table = new Table({
  name: await createTable("OrmToolbox"), documentClient,
  partitionKey: { name: "pk", type: "string" },
  sortKey: { name: "sk", type: "string" },
  indexes: {
    byStatus: {
      type: "global",
      partitionKey: { name: "gsi1pk", type: "string" },
      sortKey: { name: "gsi1sk", type: "string" },
    },
  },
})
const Customer = new Entity({
  name: "Customer", table, timestamps: false,
  schema: item({ customerId: string().key(), name: string() }),
  computeKey: ({ customerId }) => ({ pk: `CUSTOMER#${customerId}`, sk: "PROFILE" }),
})
const Order = new Entity({
  name: "Order", table, timestamps: false,
  schema: item({
    customerId: string().key(), orderId: string().key(),
    status: string().enum("PAID", "SHIPPED"), totalCents: number(),
    gsi1pk: string(), gsi1sk: string(),
  }),
  computeKey: ({ customerId, orderId }) => ({
    pk: `CUSTOMER#${customerId}`, sk: `ORDER#${orderId}`,
  }),
})
const statusKey = (status: string) => `CUSTOMER#c1#STATUS#${status}`
const byStatus = (status: string) => table.build(QueryCommand)
  .entities(Order).query({ index: "byStatus", partition: statusKey(status) }).send()

await Customer.build(PutItemCommand).item(customer).send()
await Order.build(PutItemCommand).item({
  ...order, gsi1pk: statusKey(order.status), gsi1sk: "ORDER#o1",
}).send()
const savedCustomer = await Customer.build(GetItemCommand).key({ customerId: "c1" })
  .options({ consistent: true }).send()
const before = await Order.build(GetItemCommand).key(id).options({ consistent: true }).send()
const paid = await byStatus("PAID")
const after = await Order.build(UpdateItemCommand).item({
  ...id, status: "SHIPPED", gsi1pk: statusKey("SHIPPED"),
}).options({ returnValues: "ALL_NEW", condition: { attr: "orderId", exists: true } }).send()
const shipped = await byStatus("SHIPPED")
const paidAfter = await byStatus("PAID")
report("DynamoDB Toolbox", {
  customer: savedCustomer.Item?.name, before: before.Item?.status,
  paid: (paid.Items ?? []).map(item => item.orderId), after: after.Attributes?.status,
  shipped: (shipped.Items ?? []).map(item => item.orderId),
  paidAfter: (paidAfter.Items ?? []).map(item => item.orderId),
})
import {
  Table, Entity, item, string, number,
  PutItemCommand, GetItemCommand, QueryCommand, UpdateItemCommand,
} from "dynamodb-toolbox"
import { createTable, documentClient, customer, order, id, report } from "./shared.js"

const table = new Table({
  name: await createTable("OrmToolbox"), documentClient,
  partitionKey: { name: "pk", type: "string" },
  sortKey: { name: "sk", type: "string" },
  indexes: {
    byStatus: {
      type: "global",
      partitionKey: { name: "gsi1pk", type: "string" },
      sortKey: { name: "gsi1sk", type: "string" },
    },
  },
})
const Customer = new Entity({
  name: "Customer", table, timestamps: false,
  schema: item({ customerId: string().key(), name: string() }),
  computeKey: ({ customerId }) => ({ pk: `CUSTOMER#${customerId}`, sk: "PROFILE" }),
})
const Order = new Entity({
  name: "Order", table, timestamps: false,
  schema: item({
    customerId: string().key(), orderId: string().key(),
    status: string().enum("PAID", "SHIPPED"), totalCents: number(),
    gsi1pk: string(), gsi1sk: string(),
  }),
  computeKey: ({ customerId, orderId }) => ({
    pk: `CUSTOMER#${customerId}`, sk: `ORDER#${orderId}`,
  }),
})
const statusKey = (status: string) => `CUSTOMER#c1#STATUS#${status}`
const byStatus = (status: string) => table.build(QueryCommand)
  .entities(Order).query({ index: "byStatus", partition: statusKey(status) }).send()

await Customer.build(PutItemCommand).item(customer).send()
await Order.build(PutItemCommand).item({
  ...order, gsi1pk: statusKey(order.status), gsi1sk: "ORDER#o1",
}).send()
const savedCustomer = await Customer.build(GetItemCommand).key({ customerId: "c1" })
  .options({ consistent: true }).send()
const before = await Order.build(GetItemCommand).key(id).options({ consistent: true }).send()
const paid = await byStatus("PAID")
const after = await Order.build(UpdateItemCommand).item({
  ...id, status: "SHIPPED", gsi1pk: statusKey("SHIPPED"),
}).options({ returnValues: "ALL_NEW", condition: { attr: "orderId", exists: true } }).send()
const shipped = await byStatus("SHIPPED")
const paidAfter = await byStatus("PAID")
report("DynamoDB Toolbox", {
  customer: savedCustomer.Item?.name, before: before.Item?.status,
  paid: (paid.Items ?? []).map(item => item.orderId), after: after.Attributes?.status,
  shipped: (shipped.Items ?? []).map(item => item.orderId),
  paidAfter: (paidAfter.Items ?? []).map(item => item.orderId),
})

Dynamoose: dynamoose.ts

Both models belong to one dynamoose.Table. Its automatic table creation and updates are disabled because the shared setup already created the resources. The two Item subclasses provide domain-field types; the runtime schemas provide validation. See the Dynamoose Table options for deployment settings.

import dynamoose from "dynamoose"
import { Item } from "dynamoose/dist/Item.js"
import { config, createTable, customer, order, id, report } from "./shared.js"

class CustomerItem extends Item {
  pk!: string; sk!: string; customerId!: string; name!: string
}
class OrderItem extends Item {
  pk!: string; sk!: string; customerId!: string; orderId!: string
  status!: "PAID" | "SHIPPED"; totalCents!: number
  gsi1pk!: string; gsi1sk!: string
}
dynamoose.aws.ddb.set(new dynamoose.aws.ddb.DynamoDB(config))
const keys = { pk: { type: String, hashKey: true }, sk: { type: String, rangeKey: true } }
const Customer = dynamoose.model<CustomerItem>("Customer", new dynamoose.Schema({
  ...keys, customerId: { type: String, required: true }, name: { type: String, required: true },
}))
const Order = dynamoose.model<OrderItem>("Order", new dynamoose.Schema({
  ...keys,
  customerId: { type: String, required: true }, orderId: { type: String, required: true },
  status: { type: String, enum: ["PAID", "SHIPPED"], required: true },
  totalCents: { type: Number, required: true },
  gsi1pk: { type: String, index: { name: "byStatus", type: "global", rangeKey: "gsi1sk" } },
  gsi1sk: String,
}))
new dynamoose.Table(await createTable("OrmDynamoose"), [Customer, Order], {
  create: false, update: false, waitForActive: false,
})
const key = { pk: `CUSTOMER#${id.customerId}`, sk: `ORDER#${id.orderId}` }
const statusKey = (status: string) => `CUSTOMER#c1#STATUS#${status}`
const byStatus = (status: string) => Order.query("gsi1pk").eq(statusKey(status))
  .using("byStatus").exec()

await Customer.create({ ...customer, pk: "CUSTOMER#c1", sk: "PROFILE" }, { overwrite: true })
await Order.create({
  ...order, ...key, gsi1pk: statusKey(order.status), gsi1sk: key.sk,
}, { overwrite: true })
const savedCustomer = await Customer.get({ pk: "CUSTOMER#c1", sk: "PROFILE" }, { consistent: true })
const before = await Order.get(key, { consistent: true })
const paid = await byStatus("PAID")
const after = await Order.update(key, {
  status: "SHIPPED", gsi1pk: statusKey("SHIPPED"),
}, { condition: new dynamoose.Condition().where("pk").exists() })
const shipped = await byStatus("SHIPPED")
const paidAfter = await byStatus("PAID")
report("Dynamoose", {
  customer: savedCustomer?.name, before: before?.status,
  paid: paid.map(item => item.orderId), after: after?.status,
  shipped: shipped.map(item => item.orderId), paidAfter: paidAfter.map(item => item.orderId),
})
import dynamoose from "dynamoose"
import { Item } from "dynamoose/dist/Item.js"
import { config, createTable, customer, order, id, report } from "./shared.js"

class CustomerItem extends Item {
  pk!: string; sk!: string; customerId!: string; name!: string
}
class OrderItem extends Item {
  pk!: string; sk!: string; customerId!: string; orderId!: string
  status!: "PAID" | "SHIPPED"; totalCents!: number
  gsi1pk!: string; gsi1sk!: string
}
dynamoose.aws.ddb.set(new dynamoose.aws.ddb.DynamoDB(config))
const keys = { pk: { type: String, hashKey: true }, sk: { type: String, rangeKey: true } }
const Customer = dynamoose.model<CustomerItem>("Customer", new dynamoose.Schema({
  ...keys, customerId: { type: String, required: true }, name: { type: String, required: true },
}))
const Order = dynamoose.model<OrderItem>("Order", new dynamoose.Schema({
  ...keys,
  customerId: { type: String, required: true }, orderId: { type: String, required: true },
  status: { type: String, enum: ["PAID", "SHIPPED"], required: true },
  totalCents: { type: Number, required: true },
  gsi1pk: { type: String, index: { name: "byStatus", type: "global", rangeKey: "gsi1sk" } },
  gsi1sk: String,
}))
new dynamoose.Table(await createTable("OrmDynamoose"), [Customer, Order], {
  create: false, update: false, waitForActive: false,
})
const key = { pk: `CUSTOMER#${id.customerId}`, sk: `ORDER#${id.orderId}` }
const statusKey = (status: string) => `CUSTOMER#c1#STATUS#${status}`
const byStatus = (status: string) => Order.query("gsi1pk").eq(statusKey(status))
  .using("byStatus").exec()

await Customer.create({ ...customer, pk: "CUSTOMER#c1", sk: "PROFILE" }, { overwrite: true })
await Order.create({
  ...order, ...key, gsi1pk: statusKey(order.status), gsi1sk: key.sk,
}, { overwrite: true })
const savedCustomer = await Customer.get({ pk: "CUSTOMER#c1", sk: "PROFILE" }, { consistent: true })
const before = await Order.get(key, { consistent: true })
const paid = await byStatus("PAID")
const after = await Order.update(key, {
  status: "SHIPPED", gsi1pk: statusKey("SHIPPED"),
}, { condition: new dynamoose.Condition().where("pk").exists() })
const shipped = await byStatus("SHIPPED")
const paidAfter = await byStatus("PAID")
report("Dynamoose", {
  customer: savedCustomer?.name, before: before?.status,
  paid: paid.map(item => item.orderId), after: after?.status,
  shipped: shipped.map(item => item.orderId), paidAfter: paidAfter.map(item => item.orderId),
})

OneTable: onetable.ts

This example is for understanding or maintaining an existing OneTable application. Schema value templates derive all four keys, and as const preserves the schema's literal types. Passing the low-level v3 client lets OneTable wrap it internally. exists: null makes the initial create calls behave as replacement puts; update() requires an existing item by default.

import { Table } from "dynamodb-onetable"
import { client, createTable, customer, order, id, report } from "./shared.js"

const schema = {
  format: "onetable:1.1.0", version: "1.0.0",
  indexes: {
    primary: { hash: "pk", sort: "sk" },
    byStatus: { hash: "gsi1pk", sort: "gsi1sk" },
  },
  models: {
    Customer: {
      pk: { type: String, value: "CUSTOMER#${customerId}" },
      sk: { type: String, value: "PROFILE" },
      customerId: { type: String, required: true },
      name: { type: String, required: true },
    },
    Order: {
      pk: { type: String, value: "CUSTOMER#${customerId}" },
      sk: { type: String, value: "ORDER#${orderId}" },
      gsi1pk: { type: String, value: "CUSTOMER#${customerId}#STATUS#${status}" },
      gsi1sk: { type: String, value: "ORDER#${orderId}" },
      customerId: { type: String, required: true },
      orderId: { type: String, required: true },
      status: { type: String, enum: ["PAID", "SHIPPED"], required: true },
      totalCents: { type: Number, required: true },
    },
  },
  params: { timestamps: false },
} as const
const table = new Table({ name: await createTable("OrmOneTable"), client, schema, partial: true })
const Customer = table.getModel("Customer")
const Order = table.getModel("Order")
const byStatus = (status: "PAID" | "SHIPPED") => Order.find(
  { customerId: "c1", status }, { index: "byStatus" },
)

await Customer.create(customer, { exists: null })
await Order.create(order, { exists: null })
const savedCustomer = await Customer.get({ customerId: "c1" }, { consistent: true })
const before = await Order.get(id, { consistent: true })
const paid = await byStatus("PAID")
const after = await Order.update({ ...id, status: "SHIPPED" })
const shipped = await byStatus("SHIPPED")
const paidAfter = await byStatus("PAID")
report("OneTable", {
  customer: savedCustomer?.name, before: before?.status,
  paid: paid.map(item => item.orderId), after: after?.status,
  shipped: shipped.map(item => item.orderId), paidAfter: paidAfter.map(item => item.orderId),
})
import { Table } from "dynamodb-onetable"
import { client, createTable, customer, order, id, report } from "./shared.js"

const schema = {
  format: "onetable:1.1.0", version: "1.0.0",
  indexes: {
    primary: { hash: "pk", sort: "sk" },
    byStatus: { hash: "gsi1pk", sort: "gsi1sk" },
  },
  models: {
    Customer: {
      pk: { type: String, value: "CUSTOMER#${customerId}" },
      sk: { type: String, value: "PROFILE" },
      customerId: { type: String, required: true },
      name: { type: String, required: true },
    },
    Order: {
      pk: { type: String, value: "CUSTOMER#${customerId}" },
      sk: { type: String, value: "ORDER#${orderId}" },
      gsi1pk: { type: String, value: "CUSTOMER#${customerId}#STATUS#${status}" },
      gsi1sk: { type: String, value: "ORDER#${orderId}" },
      customerId: { type: String, required: true },
      orderId: { type: String, required: true },
      status: { type: String, enum: ["PAID", "SHIPPED"], required: true },
      totalCents: { type: Number, required: true },
    },
  },
  params: { timestamps: false },
} as const
const table = new Table({ name: await createTable("OrmOneTable"), client, schema, partial: true })
const Customer = table.getModel("Customer")
const Order = table.getModel("Order")
const byStatus = (status: "PAID" | "SHIPPED") => Order.find(
  { customerId: "c1", status }, { index: "byStatus" },
)

await Customer.create(customer, { exists: null })
await Order.create(order, { exists: null })
const savedCustomer = await Customer.get({ customerId: "c1" }, { consistent: true })
const before = await Order.get(id, { consistent: true })
const paid = await byStatus("PAID")
const after = await Order.update({ ...id, status: "SHIPPED" })
const shipped = await byStatus("SHIPPED")
const paidAfter = await byStatus("PAID")
report("OneTable", {
  customer: savedCustomer?.name, before: before?.status,
  paid: paid.map(item => item.orderId), after: after?.status,
  shipped: shipped.map(item => item.orderId), paidAfter: paidAfter.map(item => item.orderId),
})

Type-check and execute

Save this as tsconfig.json. It checks application code in strict mode and skips checking dependency declaration files.

{
  "compilerOptions": {
    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
    "strict": true, "skipLibCheck": true, "noEmit": true
  },
  "include": ["shared.ts", "electro.ts", "toolbox.ts", "dynamoose.ts", "onetable.ts"]
}
{
  "compilerOptions": {
    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
    "strict": true, "skipLibCheck": true, "noEmit": true
  },
  "include": ["shared.ts", "electro.ts", "toolbox.ts", "dynamoose.ts", "onetable.ts"]
}

Run each implementation once:

npx tsc --noEmit
npx tsx electro.ts
npx tsx toolbox.ts
npx tsx dynamoose.ts
npx tsx onetable.ts
npx tsc --noEmit
npx tsx electro.ts
npx tsx toolbox.ts
npx tsx dynamoose.ts
npx tsx onetable.ts

Observed output, October 23, 2026:

{"library":"ElectroDB","customer":"Ada","before":"PAID","paid":["o1"],"after":"SHIPPED","shipped":["o1"],"paidAfter":[]}
{"library":"DynamoDB Toolbox","customer":"Ada","before":"PAID","paid":["o1"],"after":"SHIPPED","shipped":["o1"],"paidAfter":[]}
{"library":"Dynamoose","customer":"Ada","before":"PAID","paid":["o1"],"after":"SHIPPED","shipped":["o1"],"paidAfter":[]}
{"library":"OneTable","customer":"Ada","before":"PAID","paid":["o1"],"after":"SHIPPED","shipped":["o1"],"paidAfter":[]}
{"library":"ElectroDB","customer":"Ada","before":"PAID","paid":["o1"],"after":"SHIPPED","shipped":["o1"],"paidAfter":[]}
{"library":"DynamoDB Toolbox","customer":"Ada","before":"PAID","paid":["o1"],"after":"SHIPPED","shipped":["o1"],"paidAfter":[]}
{"library":"Dynamoose","customer":"Ada","before":"PAID","paid":["o1"],"after":"SHIPPED","shipped":["o1"],"paidAfter":[]}
{"library":"OneTable","customer":"Ada","before":"PAID","paid":["o1"],"after":"SHIPPED","shipped":["o1"],"paidAfter":[]}

The report helper throws if any result differs. This verifies the basic writes, reads, index-key update and GSI queries. It does not exercise every batch, transaction, pagination or validation feature in the comparison table.

When finished, remove the in-memory database by stopping its container:

docker stop dynamodb-local
docker stop dynamodb-local

Mistakes a modeling library does not prevent

Confusing a schema with a migration. Changing a key template does not rewrite existing items. When moving between libraries, account for entity discriminator attributes, hidden fields, case conversion and timestamp defaults as well as PK/SK values. Test against representative stored items before changing production readers.

Updating a source attribute without its derived key. Our order needs status and gsi1pk changed together. A plain SDK write bypasses the library's derivation. Check the generated UpdateExpression and ensure every writer follows the same rule.

Treating a query filter as an index. A status filter on the customer partition reads candidate orders before discarding nonmatching ones. The byStatus key condition directly selects the customer's status partition. A convenient query method does not make the two access patterns equivalent.

Ignoring continuation keys. The one-order example fits in a single response. Larger queries need pagination. ElectroDB exposes a cursor; Toolbox exposes page keys and an async iterator; Dynamoose uses lastKey and startAt; OneTable uses next and prev. A filtered page can be empty and still have a continuation key. Follow the pagination rules rather than stopping at an empty array.

Mixing major-version tutorials. The examples use ElectroDB 3, Toolbox 2 and Dynamoose 4. ElectroDB's v3 migration guide documents changed validation and pagination semantics. Copying older imports or relying on old limit behavior can produce code that compiles differently or reads more data than intended.

Treating a model declaration as deployed infrastructure. The runtime table and its indexes must match the schema. Keep that definition in infrastructure code; Dynobase's infrastructure code generation can generate CDK, CloudFormation or Terraform for a table when you need to capture its configuration. It does not replace the application's library schema.

DynamoDB modeling libraries for other languages

Python: PynamoDB. PynamoDB provides model classes and typed attributes, secondary-index queries and batch operations. Use it when you want a Python model API; use the boto3 guide when you want direct SDK operations. The JavaScript examples above are not PynamoDB compatibility tests.

Java: the SDK 2.x Enhanced Client. AWS's DynamoDB Enhanced Client is the successor to the SDK 1.x DynamoDBMapper. It maps Java classes to items and also provides an Enhanced Document API for flexible documents. Our Java guide covers the current mapping approach despite its historical URL.

C# and .NET: the object persistence model. AWS's DynamoDBContext maps classes and properties to DynamoDB items. Use the current SDK v4 conventions, including the context builder, rather than copying an obsolete constructor from a v3 tutorial. See our .NET and C# examples.