Databases

Create a database

Cloud → Databases → Create database, or create it from a project'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.
• Project: link it to a project 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.

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

Connect

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

Link it to a project

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

A linked database reaches the project'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.