DynamoDB Single-Table Pattern: Chat/Messaging

Chat looks simple until you’re designing the schema. Messages need pagination. Conversation lists need sorting by most recent activity. Unread counts need to be fast. And sending a message is actually a multi-item write - the message record plus an update to the conversation’s last message metadata.

This pattern handles 1:1 direct messages and group conversations in a single-table design. The same schema works for Slack-style channels, customer support chat, or in-app messaging.

Access patterns

Seven access patterns. Three entity types. One table, one GSI.

Entities

• Conversation: the chat room or DM thread
• Participant: a user’s membership in a conversation, including their last-read timestamp
• Message: an individual message within a conversation

Table design

Primary key structure

The conversation metadata, all participants, and all messages share the CONVO#<convoId> partition key. Opening a chat window is a single Query with different SK prefixes.

The MSG#<ulid> sort key gives chronological ordering and direct lookup - same principle as the E-Commerce Orders pattern. Paginate with ScanIndexForward: false and Limit: 50 to get the newest messages first. More on ULID vs UUID for sort keys here.

lastMessageBody, lastMessageSender, and lastMessageAt are stored directly on the conversation record. This means AP2 (list conversations for a user) can show a message preview without querying the messages for each conversation. The tradeoff: every new message triggers an update to the conversation record.

GSI design

GSI1 indexes the Participant entity. When a user opens their inbox, Query GSI1 with PK = USER#<userId> to get all their conversations. The conversation metadata (including last message preview) is projected into the GSI.

Sorting conversations by recent activity is the one limitation here. GSI1’s SK is the convoId, not the lastMessageAt timestamp. To sort by recent activity, you’d need to either update the GSI SK on every message (expensive) or sort client-side after the query. For most apps with < 100 conversations per user, client-side sorting is fine. At scale, add a GSI2 with SK = lastMessageAt on the Participant record, updated on each new message.

Sample data

Resolving each access pattern

AP1 - Get conversation metadata:

GetItem(pk=CONVO#c_01, sk=#METADATA)

One read. Returns name, type, and last message preview.

AP2 - List conversations for a user:

Query(GSI1, gsi1pk=USER#u_01)

One query on GSI1. Returns all conversations the user participates in. Sort client-side by lastMessageAt for “most recent first” ordering.

AP3 - List participants in a conversation:

Query(pk=CONVO#c_01, sk begins_with PARTICIPANT#)

One query. Returns all members.

AP4 - Get paginated messages (newest first):

Query(pk=CONVO#c_01, sk begins_with MSG#, ScanIndexForward=false, Limit=50)

One query. Returns the 50 newest messages. For the next page, use the last message’s SK as ExclusiveStartKey. ULIDs make this pagination natural - they’re chronologically sorted, so “older messages” means “lower ULID values.”

AP5 - Get a specific message:

GetItem(pk=CONVO#c_01, sk=MSG#01HW1A2B3C...)

One read. The ULID is the message ID.

AP6 - Unread count:

This is derived, not stored. Compare the participant’s lastReadAt with message timestamps:

Query(pk=CONVO#c_01, sk begins_with MSG#, 
  FilterExpression: createdAt > :lastReadAt)

Or more efficiently: since ULIDs encode timestamps, you can compute the ULID prefix for lastReadAt and use a range query:

Query(pk=CONVO#c_01, sk > MSG#<ulidForLastReadAt>)

Count the results. This is the unread count.

AP7 - Send a message:

await client.transactWrite({
  TransactItems: [
    { Put: { /* new Message item */ } },
    { Update: { 
      /* update Conversation #METADATA: lastMessageBody, lastMessageSender, lastMessageAt */ 
    }},
    { Update: {
      /* update sender's Participant record: lastReadAt = now */
    }},
  ]
});

Three operations in one transaction. The message is created, the conversation preview is updated, and the sender’s read receipt is advanced - all atomically.

ElectroDB entity definitions

export const ConversationEntity = new Entity({
  model: { entity: "conversation", version: "1", service: "chat" },
  attributes: {
    convoId:     { type: "string", required: true },
    name:        { type: "string" },
    type:        { type: "string", required: true, enum: ["direct", "group"] },
    lastMessageBody:   { type: "string" },
    lastMessageSender: { type: "string" },
    lastMessageAt:     { type: "string" },
    createdAt: {
      type: "string", required: true,
      default: () => new Date().toISOString(), readOnly: true,
    },
    updatedAt: {
      type: "string", required: true,
      default: () => new Date().toISOString(),
      set: () => new Date().toISOString(), watch: "*",
    },
  },
  indexes: {
    primary: {
      pk: { field: "pk", composite: ["convoId"], template: "CONVO#${convoId}" },
      sk: { field: "sk", composite: [],          template: "#METADATA" },
    },
  },
}, { client, table });

export const ParticipantEntity = new Entity({
  model: { entity: "participant", version: "1", service: "chat" },
  attributes: {
    convoId:   { type: "string", required: true },
    userId:    { type: "string", required: true },
    role:      { type: "string", required: true, default: "member" },
    joinedAt: {
      type: "string", required: true,
      default: () => new Date().toISOString(), readOnly: true,
    },
    lastReadAt: { type: "string" },
  },
  indexes: {
    primary: {
      pk: { field: "pk", composite: ["convoId"], template: "CONVO#${convoId}" },
      sk: { field: "sk", composite: ["userId"],  template: "PARTICIPANT#${userId}" },
    },
    // AP2: all conversations for a user, sorted by last activity
    byUser: {
      index: "GSI1",
      pk: { field: "gsi1pk", composite: ["userId"],  template: "USER#${userId}" },
      sk: { field: "gsi1sk", composite: ["convoId"],  template: "CONVO#${convoId}" },
    },
  },
}, { client, table });

export const MessageEntity = new Entity({
  model: { entity: "message", version: "1", service: "chat" },
  attributes: {
    convoId:   { type: "string", required: true },
    messageId: { type: "string", required: true },  // ULID
    senderId:  { type: "string", required: true },
    body:      { type: "string", required: true },
    type:      { type: "string", required: true, default: "text", enum: ["text", "image", "system"] },
    createdAt: {
      type: "string", required: true,
      default: () => new Date().toISOString(), readOnly: true,
    },
  },
  indexes: {
    primary: {
      pk: { field: "pk", composite: ["convoId"],   template: "CONVO#${convoId}" },
      sk: { field: "sk", composite: ["messageId"], template: "MSG#${messageId}" },
    },
  },
}, { client, table });

Why this design

The last-message denormalization is the key decision here. Without it, showing a conversation list with message previews requires one query per conversation - an N+1 problem. With it, the conversation list is a single GSI query with all preview data included. The cost is one extra UpdateItem per message sent. This is the same tradeoff that drives FeedItem denormalization in the Social Media Feed pattern.

Messages are not nested on the conversation record. A chat can have thousands of messages. Nesting them would blow past the 400KB item limit immediately. Separate items with ULID sort keys give unlimited message history with efficient pagination.

Read receipts are per-participant, not per-message. Storing a “read” flag on each message would require updating every unread message when a user opens the chat. Instead, lastReadAt on the Participant record is a single timestamp - compare it to message timestamps to derive unread state.

DynamoDB doesn’t support full-text search. If you need “search messages containing X,” stream messages to OpenSearch via DynamoDB Streams. The DynamoDB schema handles all the real-time access patterns; search is a separate concern.

Design this visually → coming soon

The unread count derivation and the send-message transaction are the two decisions that trip up most implementations. Seeing them laid out visually - with the partition structure clear and the GSI connections explicit - makes the tradeoffs obvious before you write any code. That’s what I’m building at singletable.dev.

Join the waitlist →

Pattern #4 of 10 in the SingleTable pattern library.

This is pattern #4 in the singletable.dev pattern library. Previously: Social Media Feed - adjacency lists, fan-out writes, and timeline pagination. Next up: IoT Time-Series - high-volume device readings, TTL-based data lifecycle, and pre-computed aggregations.