DynamoDB
このコンテンツはまだ日本語訳がありません。
The DynamoDB backend provides all three persistence components against Amazon
DynamoDB, via @aws-sdk/client-dynamodb:
DynamoDbJournal— the event journal forPersistentActors.DynamoDbSnapshotStore— snapshots to bound recovery.DynamoDbDurableStateStore— key-value durable state forDurableStateActors.
It has the strongest optimistic concurrency of any backend the framework ships — see Concurrency model — and it is fully serverless: no instance to run, on-demand capacity by default.
Install
Section titled “Install”@aws-sdk/client-dynamodb is an optional peer dependency:
bun add @aws-sdk/client-dynamodbIt is the same SDK family already used for the S3 object-storage backend, so if you use that, the runtime story is one you already have. The framework imports it only when a DynamoDB store opens — at startup, or on first use when the boot-time open is turned off.
Register all three stores through the plugins slot of the system’s options
and select them in its configuration. Set the connection once on the
composite and all three components inherit it:
import { ActorSystem, ActorSystemOptions,} from 'actor-ts';import { DynamoDbDurableStateStoreOptions, DynamoDbJournalOptions, DynamoDbSnapshotStoreOptions, RegisterDynamoDbPluginsOptions, registerDynamoDbPlugins,} from 'actor-ts/persistence';
const dynamoDbSnapshotStoreOptions = DynamoDbSnapshotStoreOptions.create() .withKeepN(3);const registerOptions = RegisterDynamoDbPluginsOptions.create() .withRegion('eu-central-1') .withJournal(DynamoDbJournalOptions.create() /* .withEventsTable(...) */) .withSnapshotStore(dynamoDbSnapshotStoreOptions) .withDurableStateStore(DynamoDbDurableStateStoreOptions.create() /* .withTable(...) */);const systemOptions = ActorSystemOptions.create() // Select the DynamoDB plugins for all three stores. .withConfig({ 'actor-ts': { persistence: { journal: { plugin: 'actor-ts.persistence.journal.dynamodb' }, 'snapshot-store': { plugin: 'actor-ts.persistence.snapshot-store.dynamodb' }, 'durable-state': { plugin: 'actor-ts.persistence.durable-state.dynamodb' }, }, }, }) .withPersistence({ plugins: [(persistence) => registerDynamoDbPlugins(persistence, registerOptions)] });const system = ActorSystem.create('my-app', systemOptions);The plug-in runs inside ActorSystem.create, so all three stores are registered
before create returns, and the ones the configuration selects open as part of
the startup — see opening the stores at
startup.
registerDynamoDbPlugins also returns the durable-state store, for a caller
that would rather wire it by hand; a store wired that way is not a selected
one, so it opens on first use rather than with the startup.
Credentials come from the standard AWS provider chain (environment, shared
config, IAM role), so nothing about them is actor-ts-specific. Pass
withClientConfig({ credentials }) to override.
Local development
Section titled “Local development”dynamodb-local needs an endpoint override, and the SDK will not sign a request
without credentials even though the emulator ignores them:
const dynamoDbJournalOptions = DynamoDbJournalOptions.create() .withRegion('eu-central-1') .withEndpoint('http://localhost:8000') .withClientConfig({ credentials: { accessKeyId: 'local', secretAccessKey: 'local' } });Configure it from HOCON
Section titled “Configure it from HOCON”The plugin id is the config section, so the block named after the id is the
block that plugin reads (#872). The whole reachability half — region, endpoint
and the table names — can come from application.conf, which means
registerDynamoDbPlugins(persistence) needs no options at all:
import { ActorSystem, ActorSystemOptions } from 'actor-ts';import { registerDynamoDbPlugins } from 'actor-ts/persistence';
const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerDynamoDbPlugins(persistence)],});const system = ActorSystem.create('my-app', systemOptions);actor-ts.persistence { journal { plugin = "actor-ts.persistence.journal.dynamodb" } snapshot-store { plugin = "actor-ts.persistence.snapshot-store.dynamodb" } durable-state { plugin = "actor-ts.persistence.durable-state.dynamodb" }
journal.dynamodb { region = "eu-central-1", events-table = "actor_ts_events" } snapshot-store.dynamodb { region = "eu-central-1", keep-n = 5 } durable-state.dynamodb { region = "eu-central-1", table = "actor_ts_durable_state" }}endpoint is the leaf you set for dynamodb-local or LocalStack; left empty it
means the real service. Credentials have no leaf at all — omitted, the SDK’s
own default chain supplies them (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY,
an instance profile, or IAM Roles for Service Accounts), which is the same
treatment the object-storage plugin’s S3 backend gets. Neither does
clientConfig — the SDK’s whole option surface, which stays code-only — nor a
pre-built operations façade or a serializer, which are live objects.
What you do tune on the client has typed leaves (#1490), each a comment in
the reference configuration so that leaving it out keeps the SDK’s own
resolution — AWS_MAX_ATTEMPTS or AWS_RETRY_MODE, then the shared config
file, then the SDK’s default — rather than overruling it:
actor-ts.persistence.journal.dynamodb { region = "eu-central-1" max-attempts = 5 # attempts per request, the first included (SDK default 3) retry-mode = adaptive # standard (the SDK default) or adaptive request-timeout = 10s # one attempt's limit, after which it fails (default: none) connection-timeout = 2s # opening the connection (default: none)}Each reaches the SDK only when set. retry-mode takes standard or
adaptive — the SDK’s own words, kebab-case already — and anything else is
refused at startup with the key and the two values, because the SDK would read
any other word as standard and say nothing. The two timeouts become the
request handler’s requestTimeout and connectionTimeout, and
request-timeout sets throwOnRequestTimeout beside it: without that, the
handler only logs a warning when a request outlives its timeout, so the leaf
would time nothing out. It bounds one attempt, and the retry strategy may try
again, so one call can take up to max-attempts of them plus the backoff in
between. A handler built from these leaves replaces the SDK’s default one, so a
connection timeout that AWS_DEFAULTS_MODE would supply no longer applies; set
connection-timeout beside request-timeout if you rely on one.
The store checks them when it is built: an attempt count or timeout that is not
a positive whole number, or a timeout longer than a timer can hold, is refused
with an OptionsError. So is a leaf beside what it replaces in clientConfig
— maxAttempts or retryMode, a retryStrategy that makes both moot, or a
requestHandler — naming both, rather than one of them quietly winning.
Table provisioning — how a table the store creates when it opens is created
— has leaves too (#1490), under all three blocks: billing-mode
("pay-per-request"), table-ready-timeout (30s) and auto-create-tables
(on). The billing mode’s values are kebab-case, like every HOCON value, and
the reader maps them to AWS’s spelling: pay-per-request is PAY_PER_REQUEST
and provisioned is PROVISIONED. PAY_PER_REQUEST written in a config file
is refused at startup with the key and the two values it takes.
The capacity pair ships as a comment, because published it would be refused
for every store under the default pay-per-request — AWS ignores capacity
there, and the validator says so rather than letting a typo pass unseen.
A provisioned table with no pair is created at 5 read and 5 write capacity
units (DEFAULT_DYNAMODB_PROVISIONED_CAPACITY_UNITS), from a config file as
from code, so name the pair when you provision on purpose:
actor-ts.persistence.journal.dynamodb { billing-mode = provisioned provisioned-throughput { read-capacity-units = 25, write-capacity-units = 10 }}Set one half without the other and the store refuses to start, naming the missing half — a default does not quietly complete the pair.
durable-state.plugin now selects this backend’s durable-state store. It
used to be built eagerly and handed back from registerDynamoDbPlugins, so it
could only be wired by threading that instance through application code. The
returned handle still works and still yields the same instance — it is simply
built when it is first asked for rather than at registration, which for a
selected store is the startup.
When to use it
Section titled “When to use it”- You are on AWS and want no database to operate. No instance, no connection pool, no patching.
- You want the strongest append guarantee available. The transactional append is atomic, which not even the relational backends manage for a multi-event batch under contention.
- Your write pattern is spiky. On-demand billing needs no capacity planning.
Configuration
Section titled “Configuration”type DynamoDbConnection = { region?: string; // eu-central-1, … endpoint?: string; // http(s) URL — dynamodb-local, LocalStack clientConfig?: Record<string, unknown>; // { credentials, … } — the code-only long tail operations?: DynamoDbOperations; // pre-built / shared façade maxAttempts?: number; // attempts per request, SDK default 3 (max-attempts) retryMode?: 'standard' | 'adaptive'; // SDK default 'standard' (retry-mode) requestTimeoutMs?: number; // requestTimeout, fails the attempt (request-timeout) connectionTimeoutMs?: number; // connectionTimeout (connection-timeout)};
type DynamoDbTableProvisioning = { autoCreateTables?: boolean; // default true billingMode?: 'PAY_PER_REQUEST' | 'PROVISIONED'; // default on-demand provisionedThroughput?: { readCapacityUnits: number; writeCapacityUnits: number }; tableReadyTimeoutMs?: number; // default 30_000};
interface DynamoDbJournalOptions extends DynamoDbConnection, DynamoDbTableProvisioning { eventsTable?: string; // default 'actor_ts_events'}interface DynamoDbSnapshotStoreOptions extends DynamoDbConnection, DynamoDbTableProvisioning { snapshotsTable?: string; // default 'actor_ts_snapshots' keepN?: number; // keep newest N per pid; default 3, <=0 keeps all}interface DynamoDbDurableStateStoreOptions extends DynamoDbConnection, DynamoDbTableProvisioning { table?: string; // default 'actor_ts_durable_state'}Options are validated when the store is constructed. Two rules earn their
keep: a table name is checked against DynamoDB’s own charset and length, and
capacity units are rejected unless billingMode is PROVISIONED — AWS silently
ignores them otherwise, which makes the mistake invisible. The opposite gap is
allowed and silent: PROVISIONED with no provisionedThroughput creates every
table at 5 read and 5 write capacity units.
Tables
Section titled “Tables”| Table | Partition key | Sort key | Holds |
|---|---|---|---|
actor_ts_events | pid | seq (N) | one item per event; seq = 0 is the compaction mark |
actor_ts_snapshots | pid | seq (N) | one item per snapshot |
actor_ts_durable_state | pid | — | one item per persistence id |
With autoCreateTables (the default) each store creates its table when it opens
and waits for it to become ACTIVE — CreateTable returns while the table
is still CREATING, and every operation against it fails until it flips. The
wait is part of the open: a selected store opens at startup, so the startup
waits — or, with the boot-time open turned off, the first caller does — and
everyone behind it gets a table that works. At startup the wait counts against
the persistence-start phase’s budget, 30 s unless withCoordinatedStartup
sets another — the same as the default table-ready-timeout — so a first boot
that has to create its tables wants a larger budget, or the tables created
ahead of it.
With autoCreateTables off — tables you provision yourself — each store
describes its own table when it opens instead: one DescribeTable, once per
open and never per operation. An endpoint the node cannot reach and a table
that does not exist both fail the open with an error naming the store, so they
fail the startup rather than the first persisted message. DescribeTable reads
the table’s metadata and needs no write permission, but it is a call of its own:
a role scoped to the item calls needs dynamodb:DescribeTable on the store’s
table as well.
Concurrency model
Section titled “Concurrency model”- Journal append is one atomic transaction. Every event goes into a single
TransactWriteItems, eachPutcarryingConditionExpression: attribute_not_exists(pid)— “only if this(pid, seq)item does not exist”. A racing writer therefore cannot win a partial append: the transaction is all-or-nothing, and its cancellation becomesJournalConcurrencyError. The head read that precedes it is only an optimization for the write’s safety, turning the common stale append into one cheap query instead of a rejected transaction — but the value it returns is load-bearing, which is why it is a strong read (next bullet). - Every read that recovery or a sequence-number decision depends on is a strong
read. DynamoDB serves eventually-consistent reads unless a request says
ConsistentRead: true, and the journal sets it on the head read, on the replay query and on the doomed-key query behinddelete; the snapshot store sets it onloadLatestandloadBefore. A stale read here is not “slightly old data”: a head from a lagging replica makes an intact stream look rewound, and a stale replay page truncates history in a way nothing downstream can detect — the replay integrity checks catch a hole, a wrong order and an out-of-window event, but nothing states where the stream should end. - Durable-state CAS is a native conditional write —
PutItem … attribute_not_exists(pid)to create,UpdateItem … revision = :expectedto update — needing neither a transaction nor a read-back. - The compaction mark only rises. It is updated with
attribute_not_exists(deletedTo) OR deletedTo < :value, which isGREATESTexpressed as a condition; a lower value is rejected, and that rejection is the expected outcome rather than an error.
Pitfalls
Section titled “Pitfalls”Where to next
Section titled “Where to next”- MongoDB — the other non-SQL backend, with an indexed tag query.
- PostgreSQL — if you would rather run a relational database.
- Durable state — the contract DynamoDB fits best.
- Snapshots — bound the recovery scan.
