# DynamoDB (parlel emulator)

A zero-dependency, in-process fake of Amazon DynamoDB. Speaks the AWS JSON 1.0
wire protocol so the real `@aws-sdk/client-dynamodb` works unmodified.

| Property    | Value                          |
| ----------- | ------------------------------ |
| Port        | 4567                           |
| Protocol    | AWS JSON 1.0 (`X-Amz-Target: DynamoDB_20120810.<Op>`) |
| Healthcheck | `GET /_parlel/health`          |
| Reset       | `POST /_parlel/reset`          |

## Default connection

```
AWS_REGION=us-east-1
AWS_ENDPOINT_URL=http://127.0.0.1:4567
AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
```

Any credentials are accepted.

## Supported operations

- Tables: `CreateTable`, `DescribeTable`, `ListTables`, `DeleteTable`, `UpdateTable`
- Items: `PutItem`, `GetItem`, `DeleteItem`, `UpdateItem`
- Reads: `Query`, `Scan`
- Batch: `BatchWriteItem`, `BatchGetItem`
- Transactions: `TransactWriteItems`, `TransactGetItems`
- Tagging: `TagResource`, `UntagResource`, `ListTagsOfResource`
- TTL: `UpdateTimeToLive`, `DescribeTimeToLive`

### Expressions

Supports the typed attribute-value format (`S`, `N`, `B`, `BOOL`, `NULL`, `L`,
`M`, `SS`, `NS`, `BS`), `KeyConditionExpression`, `FilterExpression`,
`ConditionExpression`, `UpdateExpression` (`SET`/`ADD`/`REMOVE`/`DELETE`,
`if_not_exists`, arithmetic), `ExpressionAttributeNames` / `Values`, and the
operators `=`, `<>`, `<`, `>`, `<=`, `>=`, `begins_with`, `between`, `AND`,
`OR`, `NOT`, `attribute_exists`, `attribute_not_exists`, `contains`, `size`.

## SDK example

```ts
import { DynamoDBClient, PutItemCommand, GetItemCommand } from "@aws-sdk/client-dynamodb";

const db = new DynamoDBClient({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:4567",
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
});

await db.send(new PutItemCommand({
  TableName: "Users",
  Item: { pk: { S: "u1" }, sk: { S: "profile" }, name: { S: "Alice" } },
}));

const { Item } = await db.send(new GetItemCommand({
  TableName: "Users",
  Key: { pk: { S: "u1" }, sk: { S: "profile" } },
}));
```

## Access via MCP / preview URL

When run inside a parlel pool, the service is reachable through the pool's MCP
bridge and preview URL. Point any DynamoDB SDK at the advertised endpoint; no
auth setup is required.

## Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

| Area              | Limitation                                              |
| ----------------- | ------------------------------------------------------- |
| Capacity          | Provisioned throughput is recorded but never enforced.  |
| Indexes           | GSI/LSI metadata is stored; queries scan the base table.|
| Streams           | Stream specification stored; see the `dynamodb-streams` service. |
| Nested paths      | Deep document-path updates/filters are best-effort.     |
| Pagination        | Token-free index pagination uses key-based cursors.     |
| TTL               | Expiry attribute stored but items are not auto-expired. |