Databases

Create a database

Cloud → Databases → Create database, or create it from a Serverless App Service's Storage tab to link it right away. You need resources:write.

• Name: 3–40 lowercase letters, numbers and dashes. It also decides the environment variable names.
• Location: the table is created in the region the location resolves to for DynamoDB (see Locations and regions) and stays there.
• Primary key: a partition key and an optional sort key, each a name and a type (String, Number or Binary). The default is pk and sk, both strings, for single-table designs. Keys can't be changed later; add indexes to query by other attributes.
• Serverless App Service: link it to a Serverless App Service now, or leave it Not linked.

Each database is a DynamoDB table:

Explore and edit data

A database's Data tab works on the live table (reading needs resources:read, changing resources:write):

• Scan reads the table or an index page by page; Query reads one partition, with an optional sort key condition (=, <, <=, >, >=, begins_with, between) and order.
• Filters narrow either one by any attribute (=, <>, <, <=, >, >=, begins_with, contains, between, exists, not_exists), matching all or any. Filters apply after DynamoDB reads a page, so a page can come back with fewer items than its size.
• Choose 25, 50 or 100 items per page and which attributes to return.
• View results as a table, as JSON or as DynamoDB JSON.
• Create Item, edit or delete an item. The editor takes plain JSON (numbers become N, strings S, arrays L, objects M) or DynamoDB JSON. Saving checks that the item hasn't changed since you opened it; changing a key attribute moves the item to the new key. Items can be up to 400 KB.
• Select items on a page and Delete them together.
• Import items from a file or pasted text: a JSON array or JSON Lines (DynamoDB JSON, plain JSON, or the lines of a DynamoDB export), or CSV with a header row (key columns take the key's type, numbers and true/false are typed, empty cells are left out). Choose whether items that already exist are kept or replaced. Items go in batches of up to 100; nothing in a batch is written if one of its items is invalid. Files up to 50 MB.
• Export this page (DynamoDB JSON, JSON or CSV), every item the current scan or query matches (DynamoDB JSON Lines or CSV, up to 50,000 items, read in your browser page by page), or the whole table to a bucket.

Export the whole table

Export → Whole table to a bucket asks DynamoDB to write every item, as gzipped DynamoDB JSON, into a bucket of the organization under a folder you choose (<folder>/AWSDynamoDB/<export id>/data/). It needs point-in-time recovery, doesn't use the table's capacity, and takes minutes to hours depending on size. The dialog lists recent exports with their status, item count and size.

Indexes

The Indexes tab lists the table's indexes with their status, size and item count. Create Global Index adds one with a partition key, an optional sort key and a projection: all attributes, keys only, or keys and up to 20 chosen attributes. DynamoDB builds it from existing items in the background; items without the index's key attributes aren't indexed. Deleting an index makes queries that use it fail and leaves the table's items alone.

Metrics

The Metrics tab charts consumed read and write capacity, read and write throttle events, and request latency per operation from CloudWatch over the last hour, 24 hours or 7 days.

Settings

Restore to a point in time

With point-in-time recovery on, Settings → Restore to a point in time creates a new database with the items as they were at the latest restorable time or a time you pick within the recovery window. The original doesn't change. The new table keeps the original's key schema and indexes; time to live and point-in-time recovery start off, and it gets deletion protection and the platform's tags once it's active. Restores take from minutes to hours. The new database isn't linked to any Serverless App Service.

Connect

The Connect tab shows the environment variables a linked Serverless App Service gets and code for them, using the table's own key names.

Link it to a Serverless App Service

Choose the Serverless App Service when you create the database, or open the Serverless App Service's Storage tab and choose Link storage. A database is linked to one Serverless App Service at a time; the database's menu on that tab has Change Serverless App Service and Unlink.

A linked database reaches the Serverless App Service's server function as two environment variables, from the next deployment on:

<NAME> is the database name in capitals with dashes turned into underscores: app-data becomes SI_DATABASE_APP_DATA. Two linked databases can't produce the same variable; Cloud rejects the link.

Use it from your code

The example uses the default pk/sk keys. The server function's runtime role gives it access, so the AWS SDK needs only the table name and region:

npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, GetCommand, PutCommand, QueryCommand } from "@aws-sdk/lib-dynamodb"

const TableName = process.env.SI_DATABASE_APP_DATA!
const db = DynamoDBDocumentClient.from(new DynamoDBClient({ region: process.env.SI_DATABASE_APP_DATA_REGION }))

export async function saveOrder(order: { id: string; customerId: string; total: number }) {
  await db.send(
    new PutCommand({
      TableName,
      Item: { pk: `customer#${order.customerId}`, sk: `order#${order.id}`, total: order.total },
    })
  )
}

export async function getOrder(customerId: string, id: string) {
  const res = await db.send(new GetCommand({ TableName, Key: { pk: `customer#${customerId}`, sk: `order#${id}` } }))
  return res.Item
}

export async function listOrders(customerId: string) {
  const res = await db.send(
    new QueryCommand({
      TableName,
      KeyConditionExpression: "pk = :pk AND begins_with(sk, :prefix)",
      ExpressionAttributeValues: { ":pk": `customer#${customerId}`, ":prefix": "order#" },
    })
  )
  return res.Items ?? []
}

The runtime role allows GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteItem, ConditionCheckItem and DescribeTable, which also covers transactions built from them. It allows them on every database of the organization; linking decides which names your code is given.

Delete a database

Turn off Deletion protection in Settings first, then choose Delete database (needs resources:write). The table and every item in it are deleted; this can't be undone. If the table was already deleted outside the platform, Remove from Cloud removes the record.