AWS.StateStore reference

state

Source: packages/aws/src/StateStore/Store.ts

The AWS state store: one DynamoDB table per account and region, alchemy-state.

A deploy loads a stage’s state with one query and writes each change as it happens. Records too large for a DynamoDB item go to an S3 overflow bucket. Concurrent deploys of a stage fail fast on its lease instead of mixing writes.

The table is created on first use, except in CI, where alchemy state bootstrap --backend aws provisions it ahead.

state: Using the State Store

Default table

import * as Alchemy from "alchemy";
import * as AWS from "@alchemy.run/aws";

const Stack = Alchemy.Stack(
  "my-stack",
  { providers: AWS.providers(), state: AWS.state() },
  Effect.gen(function* () {
    // ...
  }),
);

A separate, named store

const stateStore = AWS.state({ name: "team-a" }); // table alchemy-state-team-a

state: Migrating from the S3 State Store

Earlier versions kept state in an S3 bucket, alchemy-state-<accountId>-<region>-an. A stage still there is refused until it is moved. In the project, so the store the entrypoint configures is the one migrated:

alchemy state migrate --profile <your-profile>

The command moves every stage, or those --stack and --stage select. The bucket policy closes each moved stage’s S3 objects, so every older alchemy fails at its first read instead of deploying from the old copy; the objects are kept. A stage another deploy holds is reported and skipped: run the command again once it finishes. --rollback, run with the same version, moves stages back to S3 before going back to an older one.

state: Keeping State in S3

The S3 store

const stateStore = AWS.state({ backend: "s3" });

A custom bucket, prefix and KMS key

const stateStore = AWS.state({
  bucketName: "my-company-state-123456789012-us-east-1-an",
  prefix: "alchemy",
  encryption: { sseAlgorithm: "aws:kms", kmsMasterKeyId: "alias/alchemy-state" },
});

state: Supplying the AWS Environment

The store resolves its account, region and credentials from the configured profile, CI credentials or the ambient AWS environment. Provide an AWSEnvironment to use another credential source, and the same layer to AWS.providers().

const Stack = Alchemy.Stack(
  "my-stack",
  {
    providers: AWS.providers().pipe(Layer.provide(environment)),
    state: AWS.state().pipe(Layer.provide(environment)),
  },
  Effect.gen(function* () {
    // ...
  }),
);