@empire-builder-kit/nx 1.0.0-beta.10 → 1.0.0-beta.11

package/src/generators/slice/slice.js

@@ -4,6 +4,7 @@ exports.STANDARD_LOCAL_DEV_ADAPTER = exports.PRODUCT_PACKAGE_MANAGED_JSON_POINTE
 exports.createBuiltInSlicePlan = createBuiltInSlicePlan;
 exports.sliceGenerator = sliceGenerator;
 const devkit_1 = require("@nx/devkit");
+const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const index_js_1 = require("../../blueprints/index.js");
 const index_js_2 = require("../../foundation/index.js");
@@ -12,8 +13,8 @@ const index_js_4 = require("../../repository-policy/index.js");
 const PRODUCT_VERSIONS = {
     awsCognito: '^3.700.0',
     awsEventBridge: '^3.700.0',
-    awsRdsData: '^3.700.0',
-    awsSecretsManager: '^3.700.0',
+    awsRdsSigner: '^3.700.0',
+    awsSfn: '^3.700.0',
     awsSsm: '^3.700.0',
     drizzle: '^0.45.1',
     drizzleKit: '^0.31.4',
@@ -23,6 +24,7 @@ const PRODUCT_VERSIONS = {
     react: '19.2.4',
     reactDom: '19.2.4',
     typesNode: '25.5.0',
+    typesPg: '^8.15.5',
     typesReact: '19.2.14',
     typesReactDom: '19.2.3',
     vitest: '4.1.4',
@@ -33,20 +35,21 @@ exports.PRODUCT_PACKAGE_MANAGED_JSON_POINTERS = [
     '/private',
     '/dependencies/@aws-sdk~1client-cognito-identity-provider',
     '/dependencies/@aws-sdk~1client-eventbridge',
-    '/dependencies/@aws-sdk~1client-rds-data',
-    '/dependencies/@aws-sdk~1client-secrets-manager',
+    '/dependencies/@aws-sdk~1client-sfn',
+    '/dependencies/@aws-sdk~1rds-signer',
     '/dependencies/@aws-sdk~1client-ssm',
     '/dependencies/@empire-builder-kit~1runtime',
     '/dependencies/drizzle-orm',
     '/dependencies/next',
+    '/dependencies/pg',
     '/dependencies/react',
     '/dependencies/react-dom',
     '/devDependencies/@playwright~1test',
     '/devDependencies/@types~1node',
+    '/devDependencies/@types~1pg',
     '/devDependencies/@types~1react',
     '/devDependencies/@types~1react-dom',
     '/devDependencies/drizzle-kit',
-    '/devDependencies/pg',
     '/devDependencies/vitest',
     '/exports/.~1contracts',
 ];
@@ -94,6 +97,18 @@ function workspaceScope(packageJson) {
 function json(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
+const MIGRATION_PACKAGE_LOCK = JSON.parse((0, node_fs_1.readFileSync)(require.resolve('./migration-package-lock.json'), 'utf8'));
+function renderMigrationPackageLock(name) {
+    const lock = structuredClone(MIGRATION_PACKAGE_LOCK);
+    const packageName = `@ebk-migration/${name}`;
+    lock.name = packageName;
+    const root = lock.packages[''];
+    if (!root) {
+        throw new Error('Migration package lock is missing its root package.');
+    }
+    root.name = packageName;
+    return json(lock);
+}
 function reportSlicePolicyPosture(tree, name) {
     const contents = tree.read(index_js_4.REPOSITORY_POLICY_FILE, 'utf8');
     if (contents === null) {
@@ -135,12 +150,999 @@ function parseBlueprintInputs(inputs) {
 }
 function renderStandardProductFiles(name, pascalName) {
     return {
+        '.dockerignore': `.sst
+.env
+.env.*
+!.env.example
+dist
+node_modules
+web/.next
+web/.open-next
+`,
         'database/bindings.json': json({
             primary: {
                 active: 'primary',
                 provisioned: ['primary'],
             },
         }),
+        'migration/Dockerfile': `FROM node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2
+
+WORKDIR /app
+ADD --checksum=sha256:e5bb2084ccf45087bda1c9bffdea0eb15ee67f0b91646106e466714f9de3c7e3 https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem ./rds-global-bundle.pem
+COPY migration/package.json migration/package-lock.json ./
+RUN npm ci --omit=dev --omit=optional --ignore-scripts
+
+COPY jobs/bootstrap-database.mjs ./jobs/bootstrap-database.mjs
+COPY jobs/migrate-database.mjs ./jobs/migrate-database.mjs
+COPY jobs/retire-database.mjs ./jobs/retire-database.mjs
+COPY database/migrations ./database/migrations
+USER node
+CMD ["node", "jobs/migrate-database.mjs"]
+`,
+        'migration/package.json': json({
+            name: `@ebk-migration/${name}`,
+            version: '0.0.0',
+            private: true,
+            type: 'module',
+            dependencies: {
+                '@aws-sdk/client-secrets-manager': '3.1090.0',
+                '@aws-sdk/rds-signer': '3.1090.0',
+                pg: '8.22.0',
+            },
+        }),
+        'migration/package-lock.json': renderMigrationPackageLock(name),
+        'jobs/bootstrap-database.mjs': `import { randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import {
+  GetSecretValueCommand,
+  PutSecretValueCommand,
+  SecretsManagerClient,
+} from '@aws-sdk/client-secrets-manager';
+import { Signer } from '@aws-sdk/rds-signer';
+import pg from 'pg';
+
+const { Client } = pg;
+const required = (name) => {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(name + ' is required.');
+  return value;
+};
+const requiredIdentifier = (name) => {
+  const value = required(name);
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(value)) {
+    throw new Error(name + ' must be a normalized PostgreSQL identifier.');
+  }
+  return value;
+};
+const requiredPort = () => {
+  const value = required('EBK_DATABASE_PORT');
+  if (!/^\\d+$/.test(value)) {
+    throw new Error('EBK_DATABASE_PORT must be an integer.');
+  }
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    throw new Error('EBK_DATABASE_PORT must be from 1 through 65535.');
+  }
+  return port;
+};
+let bootstrapId = 'unresolved';
+let bootstrapPhase = 'configuration';
+let bootstrapLockClient;
+let bootstrapLockKey;
+
+const log = (level, event, fields = {}) => {
+  process.stdout.write(JSON.stringify({
+    bootstrapId,
+    event,
+    level,
+    timestamp: new Date().toISOString(),
+    ...fields,
+  }) + '\\n');
+};
+const safeErrorFields = (error) => {
+  const name = error instanceof Error ? error.name : 'UnknownError';
+  const code =
+    error &&
+    typeof error === 'object' &&
+    typeof error.code === 'string' &&
+    /^[A-Z0-9_]{2,32}$/.test(error.code)
+      ? error.code
+      : undefined;
+  return {
+    errorName: name.replace(/[^A-Za-z0-9_.-]/g, '').slice(0, 80) || 'Error',
+    ...(code ? { errorCode: code } : {}),
+  };
+};
+const retryableConnection = (error) => {
+  const code = error && typeof error === 'object' ? error.code : undefined;
+  const message = error instanceof Error ? error.message : String(error);
+  return new Set([
+    '08000',
+    '08001',
+    '08003',
+    '08006',
+    '57P03',
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+  ]).has(code) ||
+    /resum|starting up|temporarily unavailable|timeout|connection terminated unexpectedly|server closed the connection unexpectedly|terminating connection/i.test(message);
+};
+const sleep = (milliseconds) =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));
+const quoteIdentifier = (value) => {
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(value)) {
+    throw new Error('Unsafe PostgreSQL identifier.');
+  }
+  return '"' + value + '"';
+};
+const quoteLiteral = (value) => "'" + value.replaceAll("'", "''") + "'";
+const generatePassword = () =>
+  randomBytes(24)
+    .toString('base64')
+    .replace(/[^A-Za-z0-9]/g, '')
+    .slice(0, 32)
+    .padEnd(32, 'a');
+
+const secrets = new SecretsManagerClient({});
+const readJsonSecret = async (secretArn, missingAllowed = false) => {
+  try {
+    const result = await secrets.send(
+      new GetSecretValueCommand({ SecretId: secretArn }),
+    );
+    if (!result.SecretString) {
+      throw new Error('Secret must contain a JSON SecretString.');
+    }
+    const value = JSON.parse(result.SecretString);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error('Secret JSON must be an object.');
+    }
+    return value;
+  } catch (error) {
+    if (
+      missingAllowed &&
+      error &&
+      typeof error === 'object' &&
+      error.name === 'ResourceNotFoundException'
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+};
+const runtimeCredential = async ({
+  database,
+  host,
+  port,
+  rotationToken,
+  secretArn,
+  username,
+}) => {
+  const current = await readJsonSecret(secretArn, true);
+  const identityMatches =
+    current &&
+    current.database === database &&
+    current.username === username &&
+    typeof current.password === 'string' &&
+    /^[A-Za-z0-9]{32}$/.test(current.password);
+  if (current && !identityMatches) {
+    throw new Error('Existing generated database credential has incompatible metadata.');
+  }
+  const rotate =
+    rotationToken !== '' && current?.rotationToken !== rotationToken;
+  const connectionMetadataChanged =
+    current && (current.host !== host || current.port !== port);
+  return {
+    needsWrite: !current || rotate || connectionMetadataChanged,
+    password: !current || rotate ? generatePassword() : current.password,
+  };
+};
+const writeRuntimeCredential = async ({
+  database,
+  host,
+  password,
+  port,
+  rotationToken,
+  secretArn,
+  username,
+}) => {
+  await secrets.send(
+    new PutSecretValueCommand({
+      SecretId: secretArn,
+      SecretString: JSON.stringify({
+        database,
+        host,
+        password,
+        port,
+        ...(rotationToken ? { rotationToken } : {}),
+        username,
+      }),
+    }),
+  );
+};
+const publishRuntimeCredentials = async ({
+  database,
+  host,
+  port,
+  readonly,
+  readonlySecretArn,
+  readonlyRole,
+  readwrite,
+  readwriteSecretArn,
+  readwriteRole,
+  rotationToken,
+}) => {
+  if (readwrite.needsWrite) {
+    await writeRuntimeCredential({
+      database,
+      host,
+      password: readwrite.password,
+      port,
+      rotationToken,
+      secretArn: readwriteSecretArn,
+      username: readwriteRole,
+    });
+  }
+  if (readonly.needsWrite) {
+    await writeRuntimeCredential({
+      database,
+      host,
+      password: readonly.password,
+      port,
+      rotationToken,
+      secretArn: readonlySecretArn,
+      username: readonlyRole,
+    });
+  }
+};
+const connectWithRetry = async ({
+  database,
+  host,
+  password,
+  port,
+  roleKind,
+  username,
+  ssl,
+}) => {
+  const startedAt = Date.now();
+  let lastError;
+  for (let attempt = 1; attempt <= 10; attempt += 1) {
+    let candidate;
+    try {
+      candidate = new Client({
+        connectionTimeoutMillis: 10_000,
+        database,
+        host,
+        password:
+          typeof password === 'function' ? await password() : password,
+        port,
+        ssl: { ca: ssl, rejectUnauthorized: true },
+        statement_timeout: 10 * 60 * 1000,
+        user: username,
+      });
+      candidate.on('error', (error) => {
+        log('error', 'database_bootstrap_client_error', {
+          roleKind,
+          ...safeErrorFields(error),
+        });
+      });
+      await candidate.connect();
+      return candidate;
+    } catch (error) {
+      lastError = error;
+      await candidate?.end().catch(() => undefined);
+      if (!retryableConnection(error) || attempt === 10) throw error;
+      log('warn', 'database_bootstrap_connection_retry', {
+        attempt,
+        elapsedMs: Date.now() - startedAt,
+        roleKind,
+        ...safeErrorFields(error),
+      });
+      await sleep(Math.min(attempt * 5_000, 30_000));
+    }
+  }
+  throw lastError;
+};
+const roleExists = async (client, role) => {
+  const result = await client.query(
+    'SELECT 1 FROM pg_roles WHERE rolname = ' + quoteLiteral(role),
+  );
+  return result.rowCount > 0;
+};
+const executeStatements = async (client, statements) => {
+  for (const statement of statements) await client.query(statement);
+};
+const releaseBootstrapLock = async () => {
+  const client = bootstrapLockClient;
+  const key = bootstrapLockKey;
+  bootstrapLockClient = undefined;
+  bootstrapLockKey = undefined;
+  if (!client) return;
+  if (key) {
+    await client
+      .query('SELECT pg_advisory_unlock(hashtextextended($1, 0))', [key])
+      .catch(() => undefined);
+  }
+  await client.end().catch(() => undefined);
+};
+
+async function main() {
+  const database = requiredIdentifier('EBK_DATABASE_NAME');
+  const host = required('EBK_DATABASE_HOST');
+  const masterSecretArn = required('EBK_MASTER_SECRET_ARN');
+  const migratorRole = requiredIdentifier('EBK_DATABASE_MIGRATOR_ROLE');
+  const port = requiredPort();
+  const readonlyRole = requiredIdentifier('EBK_DATABASE_READONLY_ROLE');
+  const readonlySecretArn = required('EBK_READONLY_SECRET_ARN');
+  const readwriteRole = requiredIdentifier('EBK_DATABASE_READWRITE_ROLE');
+  const readwriteSecretArn = required('EBK_READWRITE_SECRET_ARN');
+  const region = required('AWS_REGION');
+  const rotationToken = process.env.EBK_DATABASE_ROTATION_TOKEN?.trim() ?? '';
+  const runtimeHost = required('EBK_RUNTIME_DATABASE_HOST');
+  const ca = await readFile(required('EBK_RDS_CA_BUNDLE'), 'utf8');
+  bootstrapId = required('EBK_BOOTSTRAP_ID');
+
+  bootstrapPhase = 'credential-resolution';
+  const master = await readJsonSecret(masterSecretArn);
+  if (
+    typeof master.username !== 'string' ||
+    typeof master.password !== 'string' ||
+    master.password.length === 0
+  ) {
+    throw new Error('Foundation master secret lacks username or password.');
+  }
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(master.username)) {
+    throw new Error('Foundation master secret username is invalid.');
+  }
+  const masterUsername = master.username;
+
+  bootstrapPhase = 'database-convergence';
+  const postgres = await connectWithRetry({
+    database: 'postgres',
+    host,
+    password: master.password,
+    port,
+    roleKind: 'master',
+    ssl: ca,
+    username: masterUsername,
+  });
+  bootstrapLockClient = postgres;
+  bootstrapLockKey = 'ebk-bootstrap:' + database;
+  await postgres.query(
+    'SELECT pg_advisory_lock(hashtextextended($1, 0))',
+    [bootstrapLockKey],
+  );
+  bootstrapPhase = 'credential-resolution';
+  const readwrite = await runtimeCredential({
+    database,
+    host: runtimeHost,
+    port,
+    rotationToken,
+    secretArn: readwriteSecretArn,
+    username: readwriteRole,
+  });
+  const readonly = await runtimeCredential({
+    database,
+    host: runtimeHost,
+    port,
+    rotationToken,
+    secretArn: readonlySecretArn,
+    username: readonlyRole,
+  });
+
+  bootstrapPhase = 'database-convergence';
+  const existing = await postgres.query(
+    'SELECT 1 FROM pg_database WHERE datname = ' + quoteLiteral(database),
+  );
+  if (existing.rowCount === 0) {
+    await postgres.query('CREATE DATABASE ' + quoteIdentifier(database));
+  }
+
+  const masterDatabase = await connectWithRetry({
+    database,
+    host,
+    password: master.password,
+    port,
+    roleKind: 'master',
+    ssl: ca,
+    username: masterUsername,
+  });
+  try {
+    for (const [role, password] of [
+      [readwriteRole, readwrite.password],
+      [readonlyRole, readonly.password],
+    ]) {
+      if (await roleExists(masterDatabase, role)) {
+        await masterDatabase.query(
+          'ALTER ROLE ' + quoteIdentifier(role) + ' WITH LOGIN PASSWORD ' + quoteLiteral(password),
+        );
+      } else {
+        await masterDatabase.query(
+          'CREATE ROLE ' + quoteIdentifier(role) + ' WITH LOGIN PASSWORD ' + quoteLiteral(password),
+        );
+      }
+    }
+    if (await roleExists(masterDatabase, migratorRole)) {
+      await masterDatabase.query(
+        'ALTER ROLE ' + quoteIdentifier(migratorRole) + ' WITH LOGIN PASSWORD NULL',
+      );
+    } else {
+      await masterDatabase.query(
+        'CREATE ROLE ' + quoteIdentifier(migratorRole) + ' WITH LOGIN',
+      );
+    }
+
+    // PostgreSQL 16+ can record creator ADMIN memberships when a CREATEROLE
+    // principal creates a role. Keep that non-inheriting administration path
+    // available for the membership grants below, but explicitly remove SET
+    // and INHERIT options before the migrator receives rds_iam. Default
+    // privileges are then converged through direct role-owned sessions.
+    await executeStatements(masterDatabase, [
+      'REVOKE INHERIT OPTION FOR ' + quoteIdentifier(migratorRole) +
+        ' FROM CURRENT_USER',
+      'REVOKE SET OPTION FOR ' + quoteIdentifier(migratorRole) +
+        ' FROM CURRENT_USER',
+      'REVOKE INHERIT OPTION FOR ' + quoteIdentifier(readwriteRole) +
+        ' FROM CURRENT_USER',
+      'REVOKE SET OPTION FOR ' + quoteIdentifier(readwriteRole) +
+        ' FROM CURRENT_USER',
+      'REVOKE ALL ON DATABASE ' + quoteIdentifier(database) + ' FROM PUBLIC',
+      'REVOKE CREATE ON DATABASE ' + quoteIdentifier(database) + ' FROM ' +
+        quoteIdentifier(migratorRole) + ', ' + quoteIdentifier(readwriteRole),
+      'GRANT CONNECT ON DATABASE ' + quoteIdentifier(database) + ' TO ' +
+        quoteIdentifier(migratorRole) + ', ' + quoteIdentifier(readwriteRole) +
+        ', ' + quoteIdentifier(readonlyRole),
+      'GRANT ALL ON SCHEMA public TO ' + quoteIdentifier(migratorRole) +
+        ', ' + quoteIdentifier(readwriteRole),
+      'GRANT USAGE ON SCHEMA public TO ' + quoteIdentifier(readonlyRole),
+      'GRANT rds_iam TO ' + quoteIdentifier(migratorRole),
+      'GRANT ' + quoteIdentifier(readwriteRole) + ' TO ' +
+        quoteIdentifier(migratorRole),
+    ]);
+  } finally {
+    await masterDatabase.end().catch(() => undefined);
+  }
+
+  // Publish immediately after ALTER ROLE convergence. A database password and
+  // Secrets Manager AWSCURRENT cannot change atomically, so keep this
+  // serialized stale window ahead of slower default-privilege work. Runtime
+  // authentication failure invalidates the bounded cache and retries once.
+  bootstrapPhase = 'runtime-secret-publication';
+  await publishRuntimeCredentials({
+    database,
+    host: runtimeHost,
+    port,
+    readonly,
+    readonlySecretArn,
+    readonlyRole,
+    readwrite,
+    readwriteSecretArn,
+    readwriteRole,
+    rotationToken,
+  });
+
+  bootstrapPhase = 'default-privilege-convergence';
+  const readwriteDatabase = await connectWithRetry({
+    database,
+    host,
+    password: readwrite.password,
+    port,
+    roleKind: 'readwrite',
+    ssl: ca,
+    username: readwriteRole,
+  });
+  try {
+    await executeStatements(readwriteDatabase, [
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO ' +
+        quoteIdentifier(readwriteRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ' +
+        quoteIdentifier(readonlyRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ' +
+        quoteIdentifier(readonlyRole),
+    ]);
+  } finally {
+    await readwriteDatabase.end().catch(() => undefined);
+  }
+
+  const signer = new Signer({
+    hostname: host,
+    port,
+    region,
+    username: migratorRole,
+  });
+  const migratorDatabase = await connectWithRetry({
+    database,
+    host,
+    password: () => signer.getAuthToken(),
+    port,
+    roleKind: 'migrator',
+    ssl: ca,
+    username: migratorRole,
+  });
+  try {
+    await executeStatements(migratorDatabase, [
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO ' +
+        quoteIdentifier(readwriteRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ' +
+        quoteIdentifier(readonlyRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO ' +
+        quoteIdentifier(readwriteRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ' +
+        quoteIdentifier(readonlyRole),
+    ]);
+  } finally {
+    await migratorDatabase.end().catch(() => undefined);
+  }
+
+  await releaseBootstrapLock();
+  log('info', 'database_bootstrap_succeeded', { database });
+}
+
+main().catch(async (error) => {
+  await releaseBootstrapLock();
+  log('error', 'database_bootstrap_failed', {
+    phase: bootstrapPhase,
+    ...safeErrorFields(error),
+  });
+  process.exitCode = 1;
+});
+`,
+        'jobs/retire-database.mjs': `import { readFile } from 'node:fs/promises';
+import {
+  GetSecretValueCommand,
+  SecretsManagerClient,
+} from '@aws-sdk/client-secrets-manager';
+import pg from 'pg';
+
+const { Client } = pg;
+const required = (name) => {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(name + ' is required.');
+  return value;
+};
+const requiredIdentifier = (name) => {
+  const value = required(name);
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(value)) {
+    throw new Error(name + ' must be a normalized PostgreSQL identifier.');
+  }
+  return value;
+};
+const requiredPort = () => {
+  const value = required('EBK_DATABASE_PORT');
+  if (!/^\\d+$/.test(value)) {
+    throw new Error('EBK_DATABASE_PORT must be an integer.');
+  }
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    throw new Error('EBK_DATABASE_PORT must be from 1 through 65535.');
+  }
+  return port;
+};
+let retirementId = 'unresolved';
+let retirementPhase = 'configuration';
+
+const log = (level, event, fields = {}) => {
+  process.stdout.write(JSON.stringify({
+    event,
+    level,
+    retirementId,
+    timestamp: new Date().toISOString(),
+    ...fields,
+  }) + '\\n');
+};
+const safeErrorFields = (error) => {
+  const name = error instanceof Error ? error.name : 'UnknownError';
+  const code =
+    error &&
+    typeof error === 'object' &&
+    typeof error.code === 'string' &&
+    /^[A-Z0-9_]{2,32}$/.test(error.code)
+      ? error.code
+      : undefined;
+  return {
+    errorName: name.replace(/[^A-Za-z0-9_.-]/g, '').slice(0, 80) || 'Error',
+    ...(code ? { errorCode: code } : {}),
+  };
+};
+const quoteIdentifier = (value) => {
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(value)) {
+    throw new Error('Unsafe PostgreSQL identifier.');
+  }
+  return '"' + value + '"';
+};
+const quoteLiteral = (value) => "'" + value.replaceAll("'", "''") + "'";
+const secrets = new SecretsManagerClient({});
+const readJsonSecret = async (secretArn) => {
+  const result = await secrets.send(
+    new GetSecretValueCommand({ SecretId: secretArn }),
+  );
+  if (!result.SecretString) {
+    throw new Error('Secret must contain a JSON SecretString.');
+  }
+  const value = JSON.parse(result.SecretString);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Secret JSON must be an object.');
+  }
+  return value;
+};
+
+async function main() {
+  const database = requiredIdentifier('EBK_DATABASE_NAME');
+  const host = required('EBK_DATABASE_HOST');
+  const masterSecretArn = required('EBK_MASTER_SECRET_ARN');
+  const migratorRole = requiredIdentifier('EBK_DATABASE_MIGRATOR_ROLE');
+  const port = requiredPort();
+  const readonlyRole = requiredIdentifier('EBK_DATABASE_READONLY_ROLE');
+  const readwriteRole = requiredIdentifier('EBK_DATABASE_READWRITE_ROLE');
+  const ca = await readFile(required('EBK_RDS_CA_BUNDLE'), 'utf8');
+  retirementId = required('EBK_RETIREMENT_ID');
+
+  retirementPhase = 'credential-resolution';
+  const master = await readJsonSecret(masterSecretArn);
+  if (
+    typeof master.username !== 'string' ||
+    typeof master.password !== 'string' ||
+    master.password.length === 0 ||
+    !/^[a-z][a-z0-9_]{0,62}$/.test(master.username)
+  ) {
+    throw new Error('Foundation master secret is invalid.');
+  }
+  const postgres = new Client({
+    connectionTimeoutMillis: 10_000,
+    database: 'postgres',
+    host,
+    password: master.password,
+    port,
+    ssl: { ca, rejectUnauthorized: true },
+    statement_timeout: 10 * 60 * 1000,
+    user: master.username,
+  });
+  postgres.on('error', (error) => {
+    log('error', 'database_retirement_client_error', safeErrorFields(error));
+  });
+  await postgres.connect();
+  const lockKey = 'ebk-bootstrap:' + database;
+  try {
+    retirementPhase = 'serialized-retirement';
+    await postgres.query(
+      'SELECT pg_advisory_lock(hashtextextended($1, 0))',
+      [lockKey],
+    );
+    const existing = await postgres.query(
+      'SELECT 1 FROM pg_database WHERE datname = ' + quoteLiteral(database),
+    );
+    if (existing.rowCount > 0) {
+      const grantees = [migratorRole, readwriteRole, readonlyRole]
+        .map(quoteIdentifier)
+        .join(', ');
+      await postgres.query(
+        'REVOKE ALL ON DATABASE ' + quoteIdentifier(database) +
+          ' FROM ' + grantees,
+      );
+      await postgres.query(
+        'DROP DATABASE ' + quoteIdentifier(database) + ' WITH (FORCE)',
+      );
+    }
+    const roles = await postgres.query(
+      'SELECT rolname FROM pg_roles WHERE rolname IN (' +
+        [migratorRole, readwriteRole, readonlyRole]
+          .map(quoteLiteral)
+          .join(', ') +
+        ')',
+    );
+    const existingRoles = new Set(roles.rows.map(({ rolname }) => rolname));
+    if (
+      existingRoles.has(readwriteRole) &&
+      existingRoles.has(migratorRole)
+    ) {
+      await postgres.query(
+        'REVOKE ' + quoteIdentifier(readwriteRole) + ' FROM ' +
+          quoteIdentifier(migratorRole),
+      );
+    }
+    for (const role of [migratorRole, readwriteRole, readonlyRole]) {
+      await postgres.query('DROP ROLE IF EXISTS ' + quoteIdentifier(role));
+    }
+    log('info', 'database_retirement_succeeded', { database });
+  } finally {
+    await postgres
+      .query('SELECT pg_advisory_unlock(hashtextextended($1, 0))', [lockKey])
+      .catch(() => undefined);
+    await postgres.end().catch(() => undefined);
+  }
+}
+
+main().catch((error) => {
+  log('error', 'database_retirement_failed', {
+    phase: retirementPhase,
+    ...safeErrorFields(error),
+  });
+  process.exitCode = 1;
+});
+`,
+        'jobs/migrate-database.mjs': `import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { Signer } from '@aws-sdk/rds-signer';
+import pg from 'pg';
+
+const { Client } = pg;
+const required = (name) => {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(name + ' is required.');
+  return value;
+};
+let migrationId = 'unresolved';
+let migrationPhase = 'configuration';
+
+const log = (level, event, fields = {}) => {
+  process.stdout.write(JSON.stringify({
+    event,
+    level,
+    migrationId,
+    timestamp: new Date().toISOString(),
+    ...fields,
+  }) + '\\n');
+};
+const safeErrorFields = (error) => {
+  const name = error instanceof Error ? error.name : 'UnknownError';
+  const code =
+    error &&
+    typeof error === 'object' &&
+    typeof error.code === 'string' &&
+    /^[A-Z0-9_]{2,32}$/.test(error.code)
+      ? error.code
+      : undefined;
+  return {
+    errorName: name.replace(/[^A-Za-z0-9_.-]/g, '').slice(0, 80) || 'Error',
+    ...(code ? { errorCode: code } : {}),
+  };
+};
+const retryableConnection = (error) => {
+  const code = error && typeof error === 'object' ? error.code : undefined;
+  const message = error instanceof Error ? error.message : String(error);
+  return new Set([
+    '08000',
+    '08001',
+    '08003',
+    '08006',
+    '57P03',
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+  ]).has(code) ||
+    /resum|starting up|temporarily unavailable|timeout|connection terminated unexpectedly|server closed the connection unexpectedly|terminating connection/i.test(message);
+};
+const sleep = (milliseconds) =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+const sqlCodeOnly = (sql) => {
+  let index = 0;
+  let result = '';
+  const masked = (value) => value.replace(/[^\\r\\n]/g, ' ');
+  while (index < sql.length) {
+    if (sql.startsWith('--', index)) {
+      const end = sql.indexOf('\\n', index);
+      const next = end === -1 ? sql.length : end;
+      result += masked(sql.slice(index, next));
+      index = next;
+      continue;
+    }
+    if (sql.startsWith('/*', index)) {
+      const start = index;
+      let depth = 1;
+      index += 2;
+      while (index < sql.length && depth > 0) {
+        if (sql.startsWith('/*', index)) {
+          depth += 1;
+          index += 2;
+        } else if (sql.startsWith('*/', index)) {
+          depth -= 1;
+          index += 2;
+        } else {
+          index += 1;
+        }
+      }
+      result += masked(sql.slice(start, index));
+      continue;
+    }
+    const quote = sql[index];
+    if (quote === "'" || quote === '"') {
+      const start = index;
+      index += 1;
+      while (index < sql.length) {
+        if (sql[index] === quote) {
+          if (sql[index + 1] === quote) {
+            index += 2;
+            continue;
+          }
+          index += 1;
+          break;
+        }
+        if (quote === "'" && sql[index] === '\\\\' && index + 1 < sql.length) {
+          index += 2;
+        } else {
+          index += 1;
+        }
+      }
+      result += masked(sql.slice(start, index));
+      continue;
+    }
+    if (sql[index] === '$') {
+      const tag = sql
+        .slice(index)
+        .match(/^\\$(?:[A-Za-z_][A-Za-z0-9_]*)?\\$/)?.[0];
+      if (tag) {
+        const start = index;
+        const close = sql.indexOf(tag, index + tag.length);
+        index = close === -1 ? sql.length : close + tag.length;
+        result += masked(sql.slice(start, index));
+        continue;
+      }
+    }
+    result += sql[index];
+    index += 1;
+  }
+  return result;
+};
+const hasExecutableSql = (sql) => sqlCodeOnly(sql).trim().length > 0;
+const unsupportedNonTransactionalSql =
+  /\\b(?:CREATE|DROP)\\s+INDEX\\s+CONCURRENTLY\\b|\\bVACUUM\\b/i;
+
+async function main() {
+  const host = required('EBK_DATABASE_HOST');
+  const database = required('EBK_DATABASE_NAME');
+  const username = required('EBK_DATABASE_USERNAME');
+  const region = required('AWS_REGION');
+  migrationId = required('EBK_MIGRATION_ID');
+  const caBundlePath = required('EBK_RDS_CA_BUNDLE');
+  const port = Number(required('EBK_DATABASE_PORT'));
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    throw new Error('EBK_DATABASE_PORT must be a valid TCP port.');
+  }
+  migrationPhase = 'load_ca_bundle';
+  const ca = await readFile(caBundlePath, 'utf8');
+  const connectDeadline = Date.now() + 8 * 60 * 1000;
+  let attempt = 0;
+  let client;
+  while (!client) {
+    attempt += 1;
+    let candidate;
+    try {
+      migrationPhase = 'connect';
+      const password = await new Signer({
+        hostname: host,
+        port,
+        region,
+        username,
+      }).getAuthToken();
+      candidate = new Client({
+        application_name: migrationId,
+        connectionTimeoutMillis: 15_000,
+        database,
+        host,
+        password,
+        port,
+        ssl: { ca, rejectUnauthorized: true },
+        user: username,
+      });
+      await candidate.connect();
+      client = candidate;
+    } catch (error) {
+      await candidate?.end().catch(() => undefined);
+      if (!retryableConnection(error) || Date.now() >= connectDeadline) {
+        throw error;
+      }
+      const delayMs = Math.min(attempt * 5_000, 30_000);
+      log('warn', 'database_connection_retry', {
+        attempt,
+        delayMs,
+        ...safeErrorFields(error),
+      });
+      await sleep(delayMs);
+    }
+  }
+
+  let clientFailure;
+  client.on('error', (error) => {
+    clientFailure ??= error;
+    log('error', 'database_client_error', {
+      phase: migrationPhase,
+      ...safeErrorFields(error),
+    });
+  });
+
+  let locked = false;
+  try {
+    migrationPhase = 'lock';
+    await client.query("SET lock_timeout = '5min'");
+    await client.query(
+      'SELECT pg_advisory_lock(hashtextextended($1, 0))',
+      [migrationId],
+    );
+    locked = true;
+    migrationPhase = 'ledger';
+    await client.query(
+      'CREATE TABLE IF NOT EXISTS _ebk_migrations (' +
+        'name text PRIMARY KEY, ' +
+        'checksum text NOT NULL, ' +
+        'applied_at timestamptz NOT NULL DEFAULT now())',
+    );
+    const directory = new URL('../database/migrations/', import.meta.url);
+    const files = (await readdir(directory))
+      .filter((file) => file.endsWith('.sql'))
+      .sort();
+    for (const name of files) {
+      migrationPhase = 'migration:' + name;
+      const sql = await readFile(new URL(name, directory), 'utf8');
+      if (!hasExecutableSql(sql)) {
+        throw new Error('Migration contains no executable SQL.');
+      }
+      if (unsupportedNonTransactionalSql.test(sqlCodeOnly(sql))) {
+        throw new Error(
+          'Migration requires an unsupported non-transactional operation.',
+        );
+      }
+      const checksum = createHash('sha256').update(sql).digest('hex');
+      const existing = await client.query(
+        'SELECT checksum FROM _ebk_migrations WHERE name = $1',
+        [name],
+      );
+      const appliedChecksum = existing.rows[0]?.checksum;
+      if (appliedChecksum === checksum) {
+        log('info', 'migration_skipped', { checksum, name });
+        continue;
+      }
+      if (appliedChecksum) {
+        throw new Error('An applied migration checksum changed.');
+      }
+
+      await client.query('BEGIN');
+      try {
+        const statements = sql
+          .split(/^--> statement-breakpoint\\s*$/m)
+          .map((value) => value.trim())
+          .filter(Boolean);
+        for (const statement of statements) {
+          await client.query(statement);
+        }
+        await client.query(
+          'INSERT INTO _ebk_migrations (name, checksum) VALUES ($1, $2)',
+          [name, checksum],
+        );
+        await client.query('COMMIT');
+        log('info', 'migration_applied', { checksum, name });
+      } catch (error) {
+        await client.query('ROLLBACK').catch((rollbackError) => {
+          log('error', 'migration_rollback_failed', {
+            phase: migrationPhase,
+            ...safeErrorFields(rollbackError),
+          });
+        });
+        throw error;
+      }
+    }
+    if (clientFailure) throw clientFailure;
+    log('info', 'migration_completed', { count: files.length });
+  } finally {
+    migrationPhase = 'cleanup';
+    if (locked) {
+      await client.query(
+        'SELECT pg_advisory_unlock(hashtextextended($1, 0))',
+        [migrationId],
+      ).catch(() => undefined);
+    }
+    await client.end().catch(() => undefined);
+  }
+}
+
+await main().catch((error) => {
+  log('error', 'migration_failed', {
+    phase: migrationPhase,
+    ...safeErrorFields(error),
+  });
+  process.exitCode = 1;
+});
+`,
         'contracts/events.ts': `export interface ${pascalName}CreatedData {
   id: string;
   occurredBy: string;
@@ -307,6 +1309,80 @@ export const handler = createHttpJsonHandler({
     return { message: 'Authenticated request accepted.', principal };
   },
 });
+`,
+        'database/runtime-health.ts': `import {
+  databaseTlsOptions,
+  invalidateDatabaseCredential,
+  resolveDatabaseCredential,
+  type LinkedDatabaseResource,
+} from '@empire-builder-kit/runtime/database';
+import { createBetterAuthConfig } from '@empire-builder-kit/runtime/auth';
+import { createAuthGuard } from '@empire-builder-kit/runtime/auth-backend';
+import { createHttpJsonHandler } from '@empire-builder-kit/runtime/lambda';
+import pg from 'pg';
+import { Resource } from 'sst';
+
+const { Client } = pg;
+let guard: ReturnType<typeof createAuthGuard> | undefined;
+function getGuard() {
+  return guard ??= createAuthGuard({
+    config: createBetterAuthConfig({
+      clientId: process.env.AUTH_CLIENT_ID ?? '',
+      region: process.env.AWS_REGION ?? '',
+      userPoolId: process.env.AUTH_USER_POOL_ID ?? '',
+    }),
+    policy: { defaultKind: 'customer' },
+  });
+}
+function linkedDatabase(): LinkedDatabaseResource {
+  const resource = (Resource as unknown as Record<string, unknown>)
+    .${pascalName}PrimaryDatabase;
+  if (!resource || typeof resource !== 'object') {
+    throw new Error('Primary database resource is not linked.');
+  }
+  return resource as LinkedDatabaseResource;
+}
+async function queryDatabase(resource: LinkedDatabaseResource) {
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    const credential = await resolveDatabaseCredential(resource);
+    const client = new Client({
+      ...credential,
+      connectionTimeoutMillis: 10_000,
+      ssl: databaseTlsOptions(resource),
+    });
+    try {
+      await client.connect();
+      await client.query('SELECT 1');
+      return;
+    } catch (error) {
+      const code =
+        error && typeof error === 'object' && 'code' in error
+          ? error.code
+          : undefined;
+      if (
+        attempt === 1 &&
+        resource.provider === 'aws-secrets-manager' &&
+        code === '28P01'
+      ) {
+        invalidateDatabaseCredential(resource);
+        continue;
+      }
+      throw error;
+    } finally {
+      await client.end().catch(() => undefined);
+    }
+  }
+}
+
+export const handler = createHttpJsonHandler({
+  app: '${name}',
+  operation: 'database-health',
+  async handle({ event }) {
+    await getGuard().authorize(event);
+    await queryDatabase(linkedDatabase());
+    return { service: '${name}', status: 'ok' };
+  },
+});
 `,
         'api/event-consumer.ts': `import { parseSqsEventBridgeRecords } from '@empire-builder-kit/runtime/events';
 import type { ${pascalName}CreatedData } from '../contracts/events.js';
@@ -378,7 +1454,11 @@ export const handler = createHttpJsonHandler({
 `,
         'infra/product.ts': `import { provisionDatabaseBindings } from '@empire-builder-kit/nx/foundation';
 import databaseBindings from '../database/bindings.json';
-import { getFoundationInfrastructure } from './foundation.js';
+import {
+  getFoundationInfrastructure,
+  registerProductMigration,
+  registerProductRetirement,
+} from './foundation.js';
 // <ebk:composition-imports:start>
 // <ebk:composition-imports:end>
 
@@ -392,10 +1472,12 @@ export function product() {
     throw new Error('EBK_DEV_PORT must be an integer from 1024 through 65535.');
   }
   const foundation = getFoundationInfrastructure();
-  const { db: database } = provisionDatabaseBindings(foundation, {
+  const databaseProvisions = provisionDatabaseBindings(foundation, {
     bindings: databaseBindings,
     slice: '${name}',
-  }).primary;
+  });
+  const databaseProvision = databaseProvisions.bindings.primary;
+  const { db: database } = databaseProvision;
   // <ebk:workload-registrations:start>
   // <ebk:workload-registrations:end>
 
@@ -427,6 +1509,17 @@ export function product() {
     link: [database],
     logging: { format: 'json', retention: '1 month' },
   });
+  api.route('GET /database-health', {
+    environment: {
+      AUTH_CLIENT_ID: authClient.id,
+      AUTH_USER_POOL_ID: foundation.userPool.id,
+      EBK_STAGE: $app.stage,
+    },
+    handler: 'database/runtime-health.handler',
+    link: [database],
+    logging: { format: 'json', retention: '1 month' },
+    vpc: foundation.vpc,
+  });
   api.route('POST /events/example', {
     environment: {
       AUTH_CLIENT_ID: authClient.id,
@@ -490,6 +1583,259 @@ export function product() {
     vpc: foundation.vpc,
   });
 
+  const migrationControls: Record<string, any> = {};
+  if (!$dev) {
+    const ephemeralStage = !new Set([
+      'development',
+      'staging',
+      'production',
+    ]).has($app.stage);
+    const accountId = aws.getCallerIdentityOutput({}).accountId;
+    const partition = aws.getPartitionOutput({}).partition;
+    const region = aws.getRegionOutput({}).name;
+    const runTask = (name: string, task: any) =>
+      sst.aws.StepFunctions.task({
+        arguments: {
+          Cluster: task.cluster,
+          LaunchType: 'FARGATE',
+          NetworkConfiguration: {
+            AwsvpcConfiguration: {
+              AssignPublicIp: task.assignPublicIp.apply(
+                (value: boolean) => value ? 'ENABLED' : 'DISABLED',
+              ),
+              SecurityGroups: task.securityGroups,
+              Subnets: task.subnets,
+            },
+          },
+          TaskDefinition: task.taskDefinition,
+        },
+        integration: 'sync',
+        name,
+        permissions: [
+          {
+            actions: ['ecs:RunTask'],
+            resources: [task.nodes.taskDefinition.arn],
+          },
+          {
+            actions: ['iam:PassRole'],
+            resources: [
+              task.nodes.executionRole.arn,
+              task.nodes.taskRole.arn,
+            ],
+          },
+          {
+            actions: ['ecs:DescribeTasks', 'ecs:StopTask'],
+            resources: ['*'],
+          },
+          {
+            actions: [
+              'events:DescribeRule',
+              'events:PutRule',
+              'events:PutTargets',
+            ],
+            resources: [
+              $interpolate\`arn:\${partition}:events:\${region}:\${accountId}:rule/StepFunctionsGetEventsForECSTaskRule\`,
+            ],
+          },
+        ],
+        resource: 'arn:aws:states:::ecs:runTask',
+        timeout: '45 minutes',
+      });
+
+    for (const [databaseIdentifier, target] of Object.entries(
+      databaseProvisions.databases,
+    )) {
+      if (!target.readwriteSecretArn || !target.readonlySecretArn) {
+        throw new Error(
+          'Deployed database target ' + databaseIdentifier +
+            ' is missing its generated credential references.',
+        );
+      }
+      const databaseUserArn =
+        $interpolate\`arn:\${partition}:rds-db:\${region}:\${accountId}:dbuser:\${foundation.database.clusterResourceId}/\${target.migratorRole}\`;
+      const bootstrapTask = new sst.aws.Task(
+        target.resourceName + 'BootstrapTask',
+        {
+          cluster: foundation.cluster,
+          command: ['node', 'jobs/bootstrap-database.mjs'],
+          environment: {
+            AWS_REGION: region,
+            EBK_BOOTSTRAP_ID:
+              $app.name + ':' + $app.stage + ':' + databaseIdentifier,
+            EBK_DATABASE_HOST: foundation.database.clusterEndpoint,
+            EBK_DATABASE_MIGRATOR_ROLE: target.migratorRole,
+            EBK_DATABASE_NAME: target.databaseName,
+            EBK_DATABASE_PORT:
+              $interpolate\`\${foundation.database.port}\`,
+            EBK_DATABASE_READONLY_ROLE: target.readonlyRole,
+            EBK_DATABASE_READWRITE_ROLE: target.readwriteRole,
+            EBK_DATABASE_ROTATION_TOKEN: target.rotationToken ?? '',
+            EBK_MASTER_SECRET_ARN: foundation.database.masterSecretArn,
+            EBK_READONLY_SECRET_ARN: target.readonlySecretArn,
+            EBK_READWRITE_SECRET_ARN: target.readwriteSecretArn,
+            EBK_RDS_CA_BUNDLE: '/app/rds-global-bundle.pem',
+            EBK_RUNTIME_DATABASE_HOST: foundation.database.host,
+          },
+          image: {
+            context: '.',
+            dockerfile: 'migration/Dockerfile',
+          },
+          logging: {
+            name:
+              '/ebk/' + $app.stage + '/${name}/database-bootstrap/' +
+              databaseIdentifier,
+            retention: '1 month',
+          },
+          permissions: [
+            {
+              actions: ['secretsmanager:GetSecretValue'],
+              resources: [
+                foundation.database.masterSecretArn,
+                target.readonlySecretArn,
+                target.readwriteSecretArn,
+              ],
+            },
+            {
+              actions: ['secretsmanager:PutSecretValue'],
+              resources: [
+                target.readonlySecretArn,
+                target.readwriteSecretArn,
+              ],
+            },
+            {
+              actions: ['rds-db:connect'],
+              resources: [databaseUserArn],
+            },
+          ],
+        },
+      );
+      const migrationTask = new sst.aws.Task(
+        target.resourceName + 'MigrationTask',
+        {
+          cluster: foundation.cluster,
+          environment: {
+            AWS_REGION: region,
+            EBK_DATABASE_HOST: foundation.database.clusterEndpoint,
+            EBK_DATABASE_NAME: target.databaseName,
+            EBK_DATABASE_PORT:
+              $interpolate\`\${foundation.database.port}\`,
+            EBK_DATABASE_USERNAME: target.migratorRole,
+            EBK_MIGRATION_ID:
+              $app.name + ':' + $app.stage + ':' + databaseIdentifier,
+            EBK_RDS_CA_BUNDLE: '/app/rds-global-bundle.pem',
+          },
+          image: {
+            context: '.',
+            dockerfile: 'migration/Dockerfile',
+          },
+          logging: {
+            name:
+              '/ebk/' + $app.stage + '/${name}/database-migration/' +
+              databaseIdentifier,
+            retention: '1 month',
+          },
+          permissions: [
+            {
+              actions: ['rds-db:connect'],
+              resources: [databaseUserArn],
+            },
+          ],
+        },
+      );
+      const retirementTask = ephemeralStage
+        ? new sst.aws.Task(target.resourceName + 'RetirementTask', {
+          cluster: foundation.cluster,
+          command: ['node', 'jobs/retire-database.mjs'],
+          environment: {
+            EBK_DATABASE_HOST: foundation.database.clusterEndpoint,
+            EBK_DATABASE_MIGRATOR_ROLE: target.migratorRole,
+            EBK_DATABASE_NAME: target.databaseName,
+            EBK_DATABASE_PORT:
+              $interpolate\`\${foundation.database.port}\`,
+            EBK_DATABASE_READONLY_ROLE: target.readonlyRole,
+            EBK_DATABASE_READWRITE_ROLE: target.readwriteRole,
+            EBK_MASTER_SECRET_ARN: foundation.database.masterSecretArn,
+            EBK_RDS_CA_BUNDLE: '/app/rds-global-bundle.pem',
+            EBK_RETIREMENT_ID:
+              $app.name + ':' + $app.stage + ':' + databaseIdentifier,
+          },
+          image: {
+            context: '.',
+            dockerfile: 'migration/Dockerfile',
+          },
+          logging: {
+            name:
+              '/ebk/' + $app.stage + '/${name}/database-retirement/' +
+              databaseIdentifier,
+            retention: '1 month',
+          },
+          permissions: [
+            {
+              actions: ['secretsmanager:GetSecretValue'],
+              resources: [foundation.database.masterSecretArn],
+            },
+          ],
+          })
+        : undefined;
+      const bootstrap = runTask('BootstrapDatabase', bootstrapTask);
+      const migrate = runTask('RunDatabaseMigration', migrationTask);
+      const succeeded = sst.aws.StepFunctions.succeed({
+        name: 'DatabaseMigrationSucceeded',
+      });
+      const stateMachine = new sst.aws.StepFunctions(
+        target.resourceName + 'Migration',
+        {
+          definition: bootstrap.next(migrate).next(succeeded),
+          logging: {
+            includeData: false,
+            level: 'error',
+            retention: '1 month',
+          },
+        },
+      );
+      const registration = registerProductMigration(
+        target.resourceName + 'MigrationRegistration',
+        databaseIdentifier,
+        stateMachine.arn,
+      );
+      let retirementControl;
+      if (retirementTask) {
+        const retirement = runTask('RetireDatabase', retirementTask);
+        const retirementSucceeded = sst.aws.StepFunctions.succeed({
+          name: 'DatabaseRetirementSucceeded',
+        });
+        const retirementStateMachine = new sst.aws.StepFunctions(
+          target.resourceName + 'MigrationRetirement',
+          {
+            definition: retirement.next(retirementSucceeded),
+            logging: {
+              includeData: false,
+              level: 'error',
+              retention: '1 month',
+            },
+          },
+        );
+        const retirementRegistration = registerProductRetirement(
+          target.resourceName + 'RetirementRegistration',
+          databaseIdentifier,
+          retirementStateMachine.arn,
+        );
+        retirementControl = {
+          retirementRegistration,
+          retirementStateMachine,
+          retirementTask,
+        };
+      }
+      migrationControls[databaseIdentifier] = {
+        bootstrapTask,
+        migrationTask,
+        registration,
+        ...(retirementControl ?? {}),
+        stateMachine,
+      };
+    }
+  }
+
   const apiAlarm = new aws.cloudwatch.MetricAlarm('${pascalName}ApiErrors', {
     alarmActions: [foundation.discovery.alertTopicArn],
     comparisonOperator: 'GreaterThanOrEqualToThreshold',
@@ -532,6 +1878,7 @@ export function product() {
     dlqAlarm,
     eventDlq,
     eventQueue,
+    migrationControls,
     apiAlarm,
     web,
     // <ebk:composition-outputs:start>
@@ -842,10 +2189,12 @@ signal, callback/logout URLs, and allocated internal port; do not persist a deve
 this project.
 
 \`database/bindings.json\` is the adopter-owned database selection contract. Add a candidate
-identifier to \`primary.provisioned\` to provision it without moving workload traffic. After the
-candidate is migrated and verified through the database-replacement runbook, change only
-\`primary.active\` to select it on the next reviewed deployment. Do not edit managed
-\`infra/product.ts\` or provision databases with Foundation master credentials.
+identifier to \`primary.provisioned\` to provision it without moving workload traffic. Every
+provisioned identifier receives its own AWS-internal bootstrap-and-migration workflow. Run
+\`pnpm nx run ${name}:db-migrate --stage=<stage> --database=<identifier>\` to migrate and verify
+a non-active candidate before switching \`primary.active\`. Without \`--database\`, the target
+selects the active \`primary\` identifier. Do not edit managed \`infra/product.ts\` or provision
+databases with Foundation master credentials.
 
 The readiness route is framework-managed for local orchestration. Put product-specific
 dependency and status checks under \`/${name}/api/status\` rather than editing that route.
@@ -853,6 +2202,29 @@ dependency and status checks under \`/${name}/api/status\` rather than editing t
 Run \`pnpm nx run ${name}:db-local-down\` when finished. The named volume preserves local data
 between sessions.
 
+For a deployed canonical stage, \`${name}:db-migrate\` does not connect from the
+local or GitHub process. It starts the generated Standard Step Functions
+workflow, waits for its one-off Fargate task, and reports the execution ARN.
+The workflow first runs an AWS-internal bootstrap task that converges the
+database, roles, and reference-only runtime credentials, then runs the
+IAM-authenticated migration task. Neither password resolves in GitHub, SST, or
+Pulumi state. The authenticated \`GET /database-health\` API route uses the
+server-only resolver, linked secret, and runtime-embedded AWS RDS global CA
+bundle to prove the deployed runtime path with hostname-verified TLS.
+Staging and production use the existing environment-scoped
+\`AWS_DEPLOY_ROLE_ARN\`; no second migration OIDC role or database password is
+configured by the adopter. That role needs only \`ssm:GetParameter\` for the
+exact generated migration-registration path and \`states:StartExecution\` /
+\`states:DescribeExecution\` for the exact generated state machine and its
+execution namespace; it never receives SQL, database-token, or arbitrary ECS
+authority.
+
+The Product Slice \`remove\` target depends on \`db-retire\`. Canonical
+development, staging, and production retain logical data. A deployed
+preview/personal stage runs its AWS-internal retirement workflow for every
+declared database before SST removal; do not bypass this with direct
+\`sst remove\`.
+
 Use \`pnpm nx run ${name}:dev --stage=<personal-name>\` for a personal live relay. The target
 maps that consumer stage to the \`development\` Foundation and reports both stages during
 preflight. It never deploys a personal Foundation. A normal full deploy at a mapped personal
@@ -885,6 +2257,50 @@ Record consumed slice contracts here before adding a source dependency.
 
 Document deployment smoke checks, alarms, rollback, event redrive, database migration, and
 Service or Job recovery procedures as those capabilities are added.
+
+## Database migration
+
+Protected migration runs from generated immutable bootstrap and migration
+Fargate tasks through one Standard Step Functions workflow per provisioned
+database identifier. The bootstrap task owns exact master-secret read,
+runtime-secret read/write, and migrator-connect permissions; it converges the
+database and roles under a database-scoped advisory lock. PostgreSQL may retain
+a creator ADMIN membership for role administration; bootstrap removes its
+\`SET\` and \`INHERIT\` options before granting \`rds_iam\`. The migration task
+receives only exact migrator-connect permission.
+
+Retain the workflow execution ARN, both task identities, image identity, source
+commit, migration checksums, sanitized CloudWatch logs, backup reference, and
+verification result. The GitHub job reuses
+\`AWS_DEPLOY_ROLE_ARN\` only to start and describe the exact workflow; it must
+not have direct SQL, secret-value, \`rds-db:connect\`, or arbitrary
+\`ecs:RunTask\` authority.
+
+The default \`db-migrate\` target selects the active \`primary\` database.
+During replacement, first add the candidate to \`primary.provisioned\`, deploy
+infrastructure, then run \`db-migrate --database=<candidate>\` and complete
+candidate verification before changing \`primary.active\`.
+
+Preview/personal removal invokes the generated retirement state machine for
+every provisioned identifier before infrastructure removal. Canonical stages
+retain their logical data. A preview created by a pre-bootstrap candidate must
+be removed before upgrading the Foundation and disabling its legacy Data API.
+If an interrupted current-candidate deploy never registered the retirement
+state machine in SSM, rerun the same Slice infrastructure deployment to restore
+the registration, then retry \`remove\`; do not bypass retirement.
+
+The authenticated \`GET /database-health\` route uses the server-only runtime
+resolver and its checksum-pinned AWS RDS global CA bundle. Remote Aurora
+connections retain hostname verification; only local loopback database
+connections disable TLS.
+
+Migrations are lexically ordered, checksum-locked, transaction-scoped, and
+serialized with a Postgres advisory lock. v1 schema migrations are restricted
+to the \`public\` schema. Known non-transactional operations fail closed; use a
+reviewed replacement or forward-compatible design instead of bypassing the
+transaction. Apply expand/migrate/contract. Repair failures with a forward
+migration or the documented restore/replacement procedure; do not edit an
+applied SQL file.
 `,
         'ebk-globals.d.ts': `declare const sst: any;
 declare const aws: any;
@@ -899,7 +2315,9 @@ declare const $util: any;
 `,
         'infra/foundation.ts': `import {
   foundationSsmPath,
+  productSliceMigrationPath,
   productSliceRegistrationPath,
+  productSliceRetirementPath,
   resolveFoundationStages,
   type FoundationDiscovery,
 } from '@empire-builder-kit/nx/foundation';
@@ -924,8 +2342,14 @@ export function getFoundation(): FoundationDiscovery {
     clusterId: foundationParameter('clusterId'),
     contractVersion: foundationParameter('contractVersion'),
     databaseClusterArn: foundationParameter('databaseClusterArn'),
+    databaseClusterEndpoint: foundationParameter('databaseClusterEndpoint'),
     databaseClusterId: foundationParameter('databaseClusterId'),
+    databaseClusterResourceId: foundationParameter(
+      'databaseClusterResourceId',
+    ),
+    databaseHost: foundationParameter('databaseHost'),
     databaseMasterSecretArn: foundationParameter('databaseMasterSecretArn'),
+    databasePort: foundationParameter('databasePort').apply(Number),
     eventBusArn: foundationParameter('eventBusArn'),
     eventBusName: foundationParameter('eventBusName'),
     hasPublicDomain: foundationParameter('hasPublicDomain').apply(
@@ -962,17 +2386,15 @@ export function getFoundationInfrastructure() {
     'FoundationEventBus',
     discovery.eventBusName,
   );
-  const database = sst.aws.Aurora.get(
-    'FoundationDatabase',
-    discovery.databaseClusterId,
-  );
-
   return {
     cluster,
     database: {
-      cluster: database,
       clusterArn: discovery.databaseClusterArn,
+      clusterEndpoint: discovery.databaseClusterEndpoint,
+      clusterResourceId: discovery.databaseClusterResourceId,
+      host: discovery.databaseHost,
       masterSecretArn: discovery.databaseMasterSecretArn,
+      port: discovery.databasePort,
     },
     discovery,
     eventBus,
@@ -999,6 +2421,40 @@ export function registerProductSlice() {
     }),
   });
 }
+
+export function registerProductMigration(
+  resourceName: string,
+  database: string,
+  stateMachineArn: any,
+) {
+  return new aws.ssm.Parameter(resourceName, {
+    name: productSliceMigrationPath(
+      stages.foundationStage,
+      stages.consumerStage,
+      '${name}',
+      database,
+    ),
+    type: 'String',
+    value: stateMachineArn,
+  });
+}
+
+export function registerProductRetirement(
+  name: string,
+  database: string,
+  stateMachineArn: any,
+) {
+  return new aws.ssm.Parameter(name, {
+    name: productSliceRetirementPath(
+      stages.foundationStage,
+      stages.consumerStage,
+      '${name}',
+      database,
+    ),
+    type: 'String',
+    value: stateMachineArn,
+  });
+}
 `,
         'infra/index.ts': `import { getFoundation, registerProductSlice } from './foundation.js';
 import { product } from './product.js';
@@ -1025,22 +2481,23 @@ export function app() {
             dependencies: {
                 '@aws-sdk/client-cognito-identity-provider': PRODUCT_VERSIONS.awsCognito,
                 '@aws-sdk/client-eventbridge': PRODUCT_VERSIONS.awsEventBridge,
-                '@aws-sdk/client-rds-data': PRODUCT_VERSIONS.awsRdsData,
-                '@aws-sdk/client-secrets-manager': PRODUCT_VERSIONS.awsSecretsManager,
+                '@aws-sdk/client-sfn': PRODUCT_VERSIONS.awsSfn,
                 '@aws-sdk/client-ssm': PRODUCT_VERSIONS.awsSsm,
+                '@aws-sdk/rds-signer': PRODUCT_VERSIONS.awsRdsSigner,
                 '@empire-builder-kit/runtime': runtimeVersion,
                 'drizzle-orm': PRODUCT_VERSIONS.drizzle,
                 next: PRODUCT_VERSIONS.next,
+                pg: PRODUCT_VERSIONS.pg,
                 react: PRODUCT_VERSIONS.react,
                 'react-dom': PRODUCT_VERSIONS.reactDom,
             },
             devDependencies: {
                 '@playwright/test': PRODUCT_VERSIONS.playwright,
                 '@types/node': PRODUCT_VERSIONS.typesNode,
+                '@types/pg': PRODUCT_VERSIONS.typesPg,
                 '@types/react': PRODUCT_VERSIONS.typesReact,
                 '@types/react-dom': PRODUCT_VERSIONS.typesReactDom,
                 'drizzle-kit': PRODUCT_VERSIONS.drizzleKit,
-                pg: PRODUCT_VERSIONS.pg,
                 vitest: PRODUCT_VERSIONS.vitest,
             },
             exports: {
@@ -1123,6 +2580,14 @@ export function app() {
                         cwd: `packages/${name}`,
                     },
                 },
+                'db-retire': {
+                    executor: 'nx:run-commands',
+                    options: {
+                        command: 'node scripts/retire-databases.mjs',
+                        cwd: `packages/${name}`,
+                        forwardAllArgs: true,
+                    },
+                },
                 deploy: {
                     executor: 'nx:run-commands',
                     dependsOn: [{ target: 'db-migrate', params: 'forward' }],
@@ -1203,6 +2668,7 @@ export function app() {
                 },
                 remove: {
                     executor: '@empire-builder-kit/nx:remove',
+                    dependsOn: [{ target: 'db-retire', params: 'forward' }],
                     options: {
                         cwd: `packages/${name}`,
                         stage: 'development',
@@ -1338,122 +2804,366 @@ const result = spawnSync('docker', args, {
 });
 if (result.error) throw result.error;
 if (result.status !== 0) process.exit(result.status ?? 1);
+`,
+        'scripts/retire-databases.mjs': `import { createHash } from 'node:crypto';
+import {
+  DescribeExecutionCommand,
+  SFNClient,
+  StartExecutionCommand,
+} from '@aws-sdk/client-sfn';
+import { GetParameterCommand, SSMClient } from '@aws-sdk/client-ssm';
+import {
+  createDatabaseBindingPlan,
+  productSliceRetirementPath,
+  resolveFoundationStages,
+} from '@empire-builder-kit/nx/foundation';
+import databaseBindings from '../database/bindings.json' with { type: 'json' };
+
+const stageArg = process.argv.find((value) => value.startsWith('--stage='));
+const foundationStageArg = process.argv.find((value) =>
+  value.startsWith('--foundationStage='),
+);
+const { consumerStage: stage, foundationStage } = resolveFoundationStages({
+  consumerStage: stageArg?.slice('--stage='.length) ?? 'development',
+  foundationStage:
+    foundationStageArg?.slice('--foundationStage='.length) ??
+    process.env.EBK_FOUNDATION_STAGE,
+});
+if (new Set(['development', 'staging', 'production']).has(stage)) {
+  process.stdout.write(
+    '[database-retirement] canonical stage ' + stage +
+      ' retains logical databases and roles.\\n',
+  );
+  process.exit(0);
+}
+
+const bindingPlan = createDatabaseBindingPlan(databaseBindings, {
+  slice: '${name}',
+  stage,
+});
+const sourceCommit = (
+  process.env.GITHUB_SHA ??
+  process.env.EBK_SOURCE_COMMIT ??
+  'local'
+).replace(/[^A-Za-z0-9_-]/g, '-');
+const runIdentity = (
+  process.env.GITHUB_RUN_ID ??
+  process.env.EBK_RETIREMENT_RUN_ID ??
+  String(Date.now())
+).replace(/[^A-Za-z0-9_-]/g, '-');
+const runAttempt = (
+  process.env.GITHUB_RUN_ATTEMPT ??
+  '1'
+).replace(/[^A-Za-z0-9_-]/g, '-');
+const sfn = new SFNClient({});
+const ssm = new SSMClient({});
+const terminal = new Set(['ABORTED', 'FAILED', 'SUCCEEDED', 'TIMED_OUT']);
+
+for (const database of bindingPlan.provisioned) {
+  const parameterName = productSliceRetirementPath(
+    foundationStage,
+    stage,
+    '${name}',
+    database,
+  );
+  const missingRegistration = () =>
+    new Error(
+      'Database retirement state machine ARN is missing at ' +
+        parameterName +
+        '. Redeploy the Slice infrastructure with its adopted framework candidate to restore retirement registration, then retry removal. A pre-bootstrap preview must instead be removed with its old candidate before Foundation cutover.',
+    );
+  let parameter;
+  try {
+    parameter = await ssm.send(
+      new GetParameterCommand({ Name: parameterName }),
+    );
+  } catch (error) {
+    if (
+      error &&
+      typeof error === 'object' &&
+      error.name === 'ParameterNotFound'
+    ) {
+      throw missingRegistration();
+    }
+    throw error;
+  }
+  const stateMachineArn = parameter.Parameter?.Value;
+  if (!stateMachineArn) {
+    throw missingRegistration();
+  }
+  const identity = createHash('sha256')
+    .update(['${name}', stage, database, runIdentity, runAttempt, sourceCommit].join('\\0'))
+    .digest('hex')
+    .slice(0, 16);
+  const executionName = [
+    'ebk-retire',
+    '${name}'.slice(0, 16),
+    database.slice(0, 16),
+    identity,
+  ].join('-').slice(0, 80);
+  const executionArn =
+    stateMachineArn.replace(':stateMachine:', ':execution:') +
+    ':' +
+    executionName;
+  let execution;
+  try {
+    execution = await sfn.send(
+      new DescribeExecutionCommand({ executionArn }),
+    );
+  } catch (error) {
+    if (
+      !error ||
+      typeof error !== 'object' ||
+      error.name !== 'ExecutionDoesNotExist'
+    ) {
+      throw error;
+    }
+  }
+  if (!execution) {
+    try {
+      await sfn.send(
+        new StartExecutionCommand({
+          input: JSON.stringify({
+            databaseIdentifier: database,
+            sourceCommit,
+            stage,
+            slice: '${name}',
+            workflowRunAttempt: runAttempt,
+            workflowRunId: runIdentity,
+          }),
+          name: executionName,
+          stateMachineArn,
+        }),
+      );
+    } catch (error) {
+      if (
+        !error ||
+        typeof error !== 'object' ||
+        error.name !== 'ExecutionAlreadyExists'
+      ) {
+        throw error;
+      }
+    }
+  }
+  let status = execution?.status ?? 'RUNNING';
+  const deadline = Date.now() + 50 * 60 * 1000;
+  while (!terminal.has(status)) {
+    if (Date.now() >= deadline) {
+      throw new Error(
+        'Timed out waiting for database retirement execution ' + executionArn,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 5_000));
+    execution = await sfn.send(
+      new DescribeExecutionCommand({ executionArn }),
+    );
+    status = execution.status ?? 'UNKNOWN';
+  }
+  if (status !== 'SUCCEEDED') {
+    throw new Error(
+      'Database retirement execution ' + executionArn +
+        ' ended with status ' + status + '. Infrastructure removal is blocked.',
+    );
+  }
+  process.stdout.write(
+    '[database-retirement] database=' + database +
+      ' execution=' + executionArn + ' status=SUCCEEDED\\n',
+  );
+}
 `,
         'scripts/confirm-deploy.mjs': `const stageArg = process.argv.find((value) => value.startsWith('--stage='));
 const stage = stageArg?.slice('--stage='.length) ?? 'development';
 process.stdout.write('${name} infrastructure and database migrations completed for ' + stage + '.\\n');
 `,
         'scripts/migrate-database.mjs': `import { createHash } from 'node:crypto';
-import { readdir, readFile } from 'node:fs/promises';
-import { createDatabaseBindingPlan, resolveFoundationStages } from '@empire-builder-kit/nx/foundation';
 import {
-  BeginTransactionCommand,
-  CommitTransactionCommand,
-  ExecuteStatementCommand,
-  RDSDataClient,
-  RollbackTransactionCommand,
-} from '@aws-sdk/client-rds-data';
-import { DescribeSecretCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+  DescribeExecutionCommand,
+  SFNClient,
+  StartExecutionCommand,
+} from '@aws-sdk/client-sfn';
 import { GetParameterCommand, SSMClient } from '@aws-sdk/client-ssm';
+import {
+  createDatabaseBindingPlan,
+  productSliceMigrationPath,
+  resolveFoundationStages,
+  selectDatabaseTarget,
+} from '@empire-builder-kit/nx/foundation';
 import databaseBindings from '../database/bindings.json' with { type: 'json' };
 
 const stageArg = process.argv.find((value) => value.startsWith('--stage='));
-const foundationStageArg = process.argv.find((value) => value.startsWith('--foundationStage='));
+const foundationStageArg = process.argv.find((value) =>
+  value.startsWith('--foundationStage='),
+);
 const { consumerStage: stage, foundationStage } = resolveFoundationStages({
   consumerStage: stageArg?.slice('--stage='.length) ?? 'development',
-  foundationStage: foundationStageArg?.slice('--foundationStage='.length) ?? process.env.EBK_FOUNDATION_STAGE,
+  foundationStage:
+    foundationStageArg?.slice('--foundationStage='.length) ??
+    process.env.EBK_FOUNDATION_STAGE,
 });
 const bindingPlan = createDatabaseBindingPlan(databaseBindings, {
   slice: '${name}',
   stage,
 });
-const activeDatabase = bindingPlan.active.primary;
-if (!activeDatabase) throw new Error('Database binding "primary" is required.');
-const database = bindingPlan.identifiers[activeDatabase].database;
-const clusterParameter = '/ebk/' + foundationStage + '/foundation/databaseClusterArn';
-const clusterResponse = await new SSMClient({}).send(
-  new GetParameterCommand({ Name: clusterParameter }),
+const databaseArg = process.argv.find((value) =>
+  value.startsWith('--database='),
 );
-const resourceArn = clusterResponse.Parameter?.Value;
-if (!resourceArn) throw new Error('Foundation database cluster ARN is missing at ' + clusterParameter + '.');
-const secretId = 'ebk/' + stage + '/${name}/database/' + activeDatabase + '/readwrite';
-const secretResponse = await new SecretsManagerClient({}).send(
-  new DescribeSecretCommand({ SecretId: secretId }),
+const selectedDatabase = selectDatabaseTarget(bindingPlan, {
+  database: databaseArg?.slice('--database='.length),
+});
+
+const parameterName = productSliceMigrationPath(
+  foundationStage,
+  stage,
+  '${name}',
+  selectedDatabase,
 );
-const secretArn = secretResponse.ARN;
-if (!secretArn) throw new Error('Logical database secret ARN is missing for ' + secretId + '.');
-
-const client = new RDSDataClient({});
-const resumeRetryDelaysMs = [1_000, 2_000, 4_000, 8_000, 16_000];
-const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-const send = async (command) => {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      return await client.send(command);
-    } catch (error) {
-      const resumable = error && typeof error === 'object' && error.name === 'DatabaseResumingException';
-      if (!resumable || attempt >= resumeRetryDelaysMs.length) throw error;
-      await sleep(resumeRetryDelaysMs[attempt]);
-    }
-  }
-};
-const execute = (sql, parameters = [], transactionId) => send(
-  new ExecuteStatementCommand({
-    database,
-    parameters,
-    resourceArn,
-    secretArn,
-    sql,
-    transactionId,
-  }),
+const parameter = await new SSMClient({}).send(
+  new GetParameterCommand({ Name: parameterName }),
 );
-
-await execute('CREATE TABLE IF NOT EXISTS _ebk_migrations (name text PRIMARY KEY, checksum text NOT NULL, applied_at timestamptz NOT NULL DEFAULT now())');
-const directory = new URL('../database/migrations/', import.meta.url);
-const files = (await readdir(directory)).filter((file) => file.endsWith('.sql')).sort();
-for (const name of files) {
-  const sql = await readFile(new URL(name, directory), 'utf8');
-  const checksum = createHash('sha256').update(sql).digest('hex');
-  const existing = await execute(
-    'SELECT checksum FROM _ebk_migrations WHERE name = :name',
-    [{ name: 'name', value: { stringValue: name } }],
+const stateMachineArn = parameter.Parameter?.Value;
+if (!stateMachineArn) {
+  throw new Error(
+    'Database migration state machine ARN is missing at ' +
+      parameterName +
+      '. Deploy Slice infrastructure before running migrations.',
   );
-  const appliedChecksum = existing.records?.[0]?.[0]?.stringValue;
-  if (appliedChecksum === checksum) continue;
-  if (appliedChecksum) throw new Error('Applied migration changed: ' + name);
+}
 
-  const transaction = await send(new BeginTransactionCommand({
-    database,
-    resourceArn,
-    secretArn,
-  }));
-  if (!transaction.transactionId) throw new Error('Data API did not return a transaction id.');
+const sourceCommit = (
+  process.env.GITHUB_SHA ??
+  process.env.EBK_SOURCE_COMMIT ??
+  'local'
+).replace(/[^A-Za-z0-9_-]/g, '-');
+const runIdentity = (
+  process.env.GITHUB_RUN_ID ??
+  process.env.EBK_MIGRATION_RUN_ID ??
+  String(Date.now())
+).replace(/[^A-Za-z0-9_-]/g, '-');
+const runAttempt = (
+  process.env.GITHUB_RUN_ATTEMPT ??
+  '1'
+).replace(/[^A-Za-z0-9_-]/g, '-');
+if (!/^\\d+$/.test(runAttempt)) {
+  throw new Error('GITHUB_RUN_ATTEMPT must be a positive integer.');
+}
+const parsedRunAttempt = Number.parseInt(runAttempt, 10);
+if (!Number.isSafeInteger(parsedRunAttempt) || parsedRunAttempt < 1) {
+  throw new Error('GITHUB_RUN_ATTEMPT must be a positive integer.');
+}
+const executionIdentity = createHash('sha256')
+  .update([
+    '${name}',
+    selectedDatabase,
+    runIdentity,
+    sourceCommit,
+  ].join('\\0'))
+  .digest('hex')
+  .slice(0, 16);
+const baseExecutionName = [
+  'ebk',
+  '${name}'.slice(0, 20),
+  selectedDatabase.slice(0, 20),
+  executionIdentity,
+].join('-').slice(0, 80);
+const sfn = new SFNClient({});
+const executionArnFor = (name) =>
+  stateMachineArn.replace(':stateMachine:', ':execution:') + ':' + name;
+const describeExecution = async (name) => {
   try {
-    const statements = sql.split(/^--> statement-breakpoint\\s*$/m).map((value) => value.trim()).filter(Boolean);
-    for (const statement of statements) await execute(statement, [], transaction.transactionId);
-    await execute(
-      'INSERT INTO _ebk_migrations (name, checksum) VALUES (:name, :checksum)',
-      [
-        { name: 'name', value: { stringValue: name } },
-        { name: 'checksum', value: { stringValue: checksum } },
-      ],
-      transaction.transactionId,
+    return await sfn.send(
+      new DescribeExecutionCommand({ executionArn: executionArnFor(name) }),
     );
-    await send(new CommitTransactionCommand({
-      resourceArn,
-      secretArn,
-      transactionId: transaction.transactionId,
-    }));
   } catch (error) {
-    await send(new RollbackTransactionCommand({
-      resourceArn,
-      secretArn,
-      transactionId: transaction.transactionId,
-    }));
+    if (
+      error &&
+      typeof error === 'object' &&
+      error.name === 'ExecutionDoesNotExist'
+    ) {
+      return undefined;
+    }
     throw error;
   }
+};
+const startExecution = async (name) => {
+  try {
+    await sfn.send(
+      new StartExecutionCommand({
+        input: JSON.stringify({
+          databaseIdentifier: selectedDatabase,
+          sourceCommit,
+          stage,
+          slice: '${name}',
+          workflowRunId: runIdentity,
+          workflowRunAttempt: runAttempt,
+        }),
+        name,
+        stateMachineArn,
+      }),
+    );
+  } catch (error) {
+    if (
+      !error ||
+      typeof error !== 'object' ||
+      error.name !== 'ExecutionAlreadyExists'
+    ) {
+      throw error;
+    }
+  }
+};
+const terminal = new Set([
+  'ABORTED',
+  'FAILED',
+  'SUCCEEDED',
+  'TIMED_OUT',
+]);
+
+let executionName = baseExecutionName;
+let execution = await describeExecution(executionName);
+if (
+  execution &&
+  terminal.has(execution.status ?? 'UNKNOWN') &&
+  execution.status !== 'SUCCEEDED' &&
+  parsedRunAttempt > 1
+) {
+  const retrySuffix = '-retry-' + runAttempt;
+  executionName =
+    baseExecutionName.slice(0, 80 - retrySuffix.length) + retrySuffix;
+  execution = await describeExecution(executionName);
 }
-process.stdout.write('${name} database migrations completed for ' + stage + '.\\n');
+if (!execution) {
+  await startExecution(executionName);
+}
+
+const executionArn = executionArnFor(executionName);
+let status = execution?.status ?? 'RUNNING';
+process.stdout.write(
+  '[database-migration] execution=' + executionArn + ' status=' + status + '\\n',
+);
+const deadline = Date.now() + 95 * 60 * 1000;
+while (!terminal.has(status)) {
+  if (Date.now() >= deadline) {
+    throw new Error(
+      'Timed out waiting for database migration execution ' + executionArn,
+    );
+  }
+  await new Promise((resolve) => setTimeout(resolve, 5_000));
+  const execution = await sfn.send(
+    new DescribeExecutionCommand({ executionArn }),
+  );
+  status = execution.status ?? 'UNKNOWN';
+}
+if (status !== 'SUCCEEDED') {
+  throw new Error(
+    'Database migration execution ' +
+      executionArn +
+      ' ended with status ' +
+      status +
+      '. Inspect its Step Functions and CloudWatch records.',
+  );
+}
+process.stdout.write(
+  '[database-migration] execution=' + executionArn + ' status=SUCCEEDED\\n',
+);
 `,
         'sst-env.d.ts': `// Bootstrap placeholder. SST overwrites this file after install, dev, or deploy.
 export {};