cdk-dms-replication 0.1.12 → 0.1.13

package/.jsii

@@ -3580,7 +3580,7 @@
   },
   "name": "cdk-dms-replication",
   "readme": {
-    "markdown": "# cdk-dms-replication\n\n[![npm version](https://badge.fury.io/js/cdk-dms-replication.svg)](https://badge.fury.io/js/cdk-dms-replication)\n[![PyPI version](https://badge.fury.io/py/cdk-dms-replication.svg)](https://badge.fury.io/py/cdk-dms-replication)\n[![build](https://github.com/kckempf/cdk-dms-replication/actions/workflows/build.yml/badge.svg)](https://github.com/kckempf/cdk-dms-replication/actions/workflows/build.yml)\n\nL3 CDK constructs for [Amazon Database Migration Service (DMS)](https://aws.amazon.com/dms/). Provision a complete migration pipeline — replication instance, endpoints, and task — in a few lines of code, with secure defaults and full support for all DMS-supported engines and migration patterns.\n\n## Features\n\n- **All migration patterns** — full load, CDC, and full-load-and-CDC\n- **Classic and Serverless** — `DmsMigrationPipeline` (fixed instance) or `DmsServerlessPipeline` (auto-scales DCUs)\n- **All DMS engines** — MySQL, PostgreSQL, Oracle, SQL Server, SAP ASE, IBM Db2, MongoDB, DocumentDB, S3, DynamoDB, Redshift, Kinesis, Kafka, OpenSearch, Neptune, Redis\n- **Secure defaults** — replication instance placed in private subnets, KMS encryption at rest, security group auto-created\n- **Fluent builders** — `TableMappings` and `TaskSettings` builders produce the JSON DMS expects without hand-crafting strings\n- **Multi-language** — TypeScript, Python, Java, .NET, Go (via JSII)\n- **Escape hatches** — pass existing endpoints or a pre-existing replication instance\n\n## Installation\n\n### TypeScript / JavaScript\n\n```bash\nnpm install cdk-dms-replication\n```\n\n### Python\n\n```bash\npip install cdk-dms-replication\n```\n\n### Java\n\n```xml\n<dependency>\n  <groupId>io.github.kckempf</groupId>\n  <artifactId>cdk-dms-replication</artifactId>\n  <version>VERSION</version>\n</dependency>\n```\n\n### .NET\n\n```bash\ndotnet add package KcKempf.CdkDmsReplication\n```\n\n### Go\n\n```bash\ngo get github.com/kckempf/cdk-dms-replication-go\n```\n\n---\n\n## Quick start\n\n### Classic pipeline (fixed replication instance)\n\n`DmsMigrationPipeline` provisions a replication instance, both endpoints, and a replication task in one construct.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport * as ec2 from 'aws-cdk-lib/aws-ec2';\nimport {\n  DmsMigrationPipeline,\n  EndpointEngine,\n  MigrationType,\n  TableMappings,\n} from 'cdk-dms-replication';\n\nconst app = new cdk.App();\nconst stack = new cdk.Stack(app, 'MigrationStack');\n\nconst vpc = ec2.Vpc.fromLookup(stack, 'Vpc', { isDefault: false });\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n\n  sourceEndpoint: {\n    engine: EndpointEngine.MYSQL,\n    serverName: 'mysql.internal.example.com',\n    port: 3306,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('mysql-dms-password'),\n    databaseName: 'orders',\n  },\n\n  targetEndpoint: {\n    engine: EndpointEngine.AURORA_POSTGRESQL,\n    serverName: cluster.clusterEndpoint.hostname,\n    port: 5432,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('aurora-dms-password'),\n    databaseName: 'orders',\n  },\n\n  tableMappings: new TableMappings()\n    .includeSchema('public')\n    .excludeTable('public', 'audit_log')\n    .toJson(),\n});\n```\n\n> **Note:** The `tableMappings` default (when omitted) is to include all tables in all schemas.\n\n### Serverless pipeline (auto-scaling)\n\n`DmsServerlessPipeline` uses DMS Serverless, which automatically scales capacity (measured in DMS Capacity Units — DCUs) between a configurable minimum and maximum. There is no replication instance to size or manage.\n\n```typescript\nimport {\n  DmsServerlessPipeline,\n  EndpointEngine,\n  MigrationType,\n} from 'cdk-dms-replication';\n\nnew DmsServerlessPipeline(stack, 'Pipeline', {\n  vpc,\n  maxCapacityUnits: 16,           // required; valid values: 1,2,4,8,16,32,64,128,192,256,384\n  minCapacityUnits: 2,            // optional; DMS auto-determines if omitted\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n\n  sourceEndpoint: {\n    engine: EndpointEngine.MYSQL,\n    serverName: 'mysql.internal.example.com',\n    port: 3306,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('mysql-dms-password'),\n    databaseName: 'orders',\n  },\n\n  targetEndpoint: {\n    engine: EndpointEngine.AURORA_POSTGRESQL,\n    serverName: cluster.clusterEndpoint.hostname,\n    port: 5432,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('aurora-dms-password'),\n    databaseName: 'orders',\n  },\n});\n```\n\n> **CDC start/stop position limitation:** `DmsServerlessPipeline` does not support `cdcStartPosition` or `cdcStartTime` at the CloudFormation level. To start replication from a specific LSN or timestamp, call the [`StartReplication` API](https://docs.aws.amazon.com/dms/latest/APIReference/API_StartReplication.html) after the config is created.\n\n---\n\n## Migration patterns\n\n### Full load\n\nMigrates all existing data once, then stops.\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n### CDC only\n\nReplicates ongoing changes starting from a specific position or time. The target must already be seeded with data.\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.CDC,\n  cdcStartPosition: 'mysql-bin-changelog.000024:373',  // binlog position\n  // — or —\n  cdcStartTime: '2024-01-01T00:00:00Z',                // ISO-8601 timestamp\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n### Full load then CDC\n\nMigrates existing data, then automatically switches to continuous replication.\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n---\n\n## Endpoint examples\n\n### MySQL / MariaDB / Aurora MySQL\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.MYSQL,          // or MARIADB, AURORA_MYSQL\n  serverName: 'mysql.example.com',\n  port: 3306,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('db-secret'),\n  databaseName: 'mydb',\n  mySqlSettings: {\n    parallelLoadThreads: 4,\n    serverTimezone: 'UTC',\n  },\n},\n```\n\n### PostgreSQL / Aurora PostgreSQL\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.POSTGRES,       // or AURORA_POSTGRESQL\n  serverName: 'pg.example.com',\n  port: 5432,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('db-secret'),\n  databaseName: 'appdb',\n  postgreSqlSettings: {\n    captureDdls: true,\n    slotName: 'dms_replication_slot',\n    pluginName: PostgresCdcPlugin.PG_LOGICAL,\n    heartbeatEnable: true,\n  },\n},\n```\n\n### Oracle\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.ORACLE,\n  serverName: 'oracle.example.com',\n  port: 1521,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('oracle-secret'),\n  databaseName: 'ORCL',\n  oracleSettings: {\n    addSupplementalLogging: true,\n    useLogminerReader: true,   // true = LogMiner, false = BinaryReader\n  },\n},\n```\n\n### SQL Server\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.SQLSERVER,\n  serverName: 'sqlserver.example.com',\n  port: 1433,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('sqlserver-secret'),\n  databaseName: 'AdventureWorks',\n  sqlServerSettings: {\n    readBackupOnly: false,\n    safeguardPolicy: SqlServerSafeguardPolicy.RELY_ON_SQL_SERVER_REPLICATION_AGENT,\n  },\n},\n```\n\n### MongoDB / DocumentDB\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.MONGODB,        // or DOCDB\n  serverName: 'mongo.example.com',\n  port: 27017,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('mongo-secret'),\n  mongoDbSettings: {\n    authType: MongoAuthType.PASSWORD,\n    authMechanism: MongoAuthMechanism.SCRAM_SHA_1,\n    nestingLevel: MongoNestingLevel.ONE,\n  },\n},\n```\n\n### Amazon S3 (source or target)\n\n```typescript\n// As a target\ntargetEndpoint: {\n  engine: EndpointEngine.S3,\n  s3Settings: {\n    bucketName: 'my-migration-data',\n    bucketFolder: 'dms-output',\n    serviceAccessRoleArn: s3Role.roleArn,\n    dataFormat: S3DataFormat.PARQUET,\n    parquetVersion: ParquetVersion.PARQUET_2_0,\n    datePartitionEnabled: true,\n    datePartitionSequence: DatePartitionSequence.YYYYMMDD,\n    encryptionMode: EncryptionMode.SSE_KMS,\n    serverSideEncryptionKmsKeyId: myKey.keyArn,\n  },\n},\n```\n\n### Amazon Redshift\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.REDSHIFT,\n  serverName: 'my-cluster.abc123.us-east-1.redshift.amazonaws.com',\n  port: 5439,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('redshift-secret'),\n  databaseName: 'dev',\n  redshiftSettings: {\n    bucketName: 'my-redshift-staging',\n    serviceAccessRoleArn: redshiftRole.roleArn,\n    encryptionMode: EncryptionMode.SSE_KMS,\n    serverSideEncryptionKmsKeyId: myKey.keyArn,\n    truncateColumns: true,\n    emptyAsNull: true,\n  },\n},\n```\n\n### Amazon Kinesis Data Streams\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.KINESIS,\n  kinesisSettings: {\n    streamArn: stream.streamArn,\n    serviceAccessRoleArn: kinesisRole.roleArn,\n    messageFormat: MessageFormat.JSON,\n    includeTransactionDetails: true,\n    includeTableAlterOperations: true,\n  },\n},\n```\n\n### Apache Kafka / Amazon MSK\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.KAFKA,\n  kafkaSettings: {\n    broker: 'b-1.my-cluster.abc123.kafka.us-east-1.amazonaws.com:9092',\n    topic: 'dms-changes',\n    messageFormat: MessageFormat.JSON,\n    securityProtocol: KafkaSecurityProtocol.SASL_SSL,\n    saslUsername: 'dms_user',\n    saslPassword: cdk.SecretValue.secretsManager('kafka-sasl-password'),\n  },\n},\n```\n\n### Amazon OpenSearch Service\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.OPENSEARCH,\n  openSearchSettings: {\n    endpointUri: 'https://search-my-domain.us-east-1.es.amazonaws.com',\n    serviceAccessRoleArn: openSearchRole.roleArn,\n    fullLoadErrorPercentage: 10,\n    errorRetryDuration: 300,\n  },\n},\n```\n\n### Amazon Neptune\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.NEPTUNE,\n  neptuneSettings: {\n    s3BucketName: 'my-neptune-staging',\n    s3BucketFolder: 'dms',\n    serviceAccessRoleArn: neptuneRole.roleArn,\n    iamAuthEnabled: true,\n  },\n},\n```\n\n### Amazon DynamoDB\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.DYNAMODB,\n  dynamoDbSettings: {\n    serviceAccessRoleArn: dynamoRole.roleArn,\n  },\n},\n```\n\n---\n\n## Table mappings\n\nUse the `TableMappings` fluent builder to control which tables are migrated and how they are named on the target.\n\n### Selection rules\n\n```typescript\nnew TableMappings()\n  .includeSchema('public')               // include all tables in 'public'\n  .includeSchema('%')                    // include all schemas (wildcard)\n  .excludeTable('public', 'audit_log')  // exclude a specific table\n  .excludeSchema('internal')            // exclude an entire schema\n  .explicitTable('public', 'orders')    // migrate only this one table\n  .toJson()\n```\n\n### Transformation rules\n\n```typescript\nnew TableMappings()\n  .includeSchema('%')\n  .renameSchema('legacy', 'v2')          // rename schema on target\n  .toLowerCaseTable('public', '%')       // lowercase all table names\n  .toUpperCaseSchema('%')                // uppercase all schema names\n  .addPrefixToTable('public', '%', 'migrated_')\n  .renameTable('public', 'usr', 'users') // rename a specific table\n  .renameColumn('public', 'orders', 'cust_id', 'customer_id')\n  .removeColumn('public', 'orders', 'internal_notes')\n  .toJson()\n```\n\n### Adding columns\n\n```typescript\nnew TableMappings()\n  .includeSchema('public')\n  .addColumn('public', 'orders', {\n    columnName: 'migrated_at',\n    columnType: ColumnDataType.DATETIME,\n    expression: '$timestamp',       // DMS built-in expression\n  })\n  .addColumn('public', 'orders', {\n    columnName: 'migration_version',\n    columnType: ColumnDataType.STRING,\n    columnLength: 10,\n    columnValue: 'v2.0',           // constant value\n  })\n  .toJson()\n```\n\n---\n\n## Task settings\n\nUse `TaskSettings` to tune LOB handling, error behaviour, full-load parallelism, and CDC batching.\n\n```typescript\nimport { TaskSettings, LobMode, ErrorAction, LoggingLevel } from 'cdk-dms-replication';\n\nconst settings = new TaskSettings()\n  // LOB handling\n  .withLobMode(LobMode.LIMITED_LOB, 64)   // truncate LOBs at 64 KB\n\n  // Full load tuning\n  .withFullLoadSubTasks(16)                // 16 parallel table loads\n  .withTargetTablePrepMode('DROP_AND_CREATE')\n  .withCommitRate(50000)                   // commit every 50k rows\n\n  // CDC batch apply\n  .withBatchApply(true, 5, 60)            // batch changes, 5–60 second window\n\n  // Error handling\n  .withDataErrorPolicy(ErrorAction.IGNORE_RECORD, 1000)\n  .withRecovery(-1, 5)                    // unlimited retries, 5s interval\n\n  // Logging\n  .withLogging('SOURCE_UNLOAD', LoggingLevel.LOGGER_SEVERITY_DEBUG)\n  .withLogging('TARGET_LOAD', LoggingLevel.LOGGER_SEVERITY_DEFAULT)\n  .toJson();\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  taskSettings: settings,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n---\n\n## Replication instance options\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n\n  // Instance sizing (default: R6I_LARGE)\n  replicationInstanceClass: ReplicationInstanceClass.R6I_4XLARGE,\n  allocatedStorage: 500,        // GB\n\n  // High availability\n  multiAz: true,\n\n  // Encryption — bring your own KMS key\n  encryptionKey: myKmsKey,\n\n  // Subnet placement\n  vpcSubnets: {\n    subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,\n  },\n\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n---\n\n## Using lower-level constructs directly\n\nIf you need more control, use the individual constructs and wire them together yourself.\n\n```typescript\nimport {\n  DmsReplicationInstance,\n  DmsEndpoint,\n  DmsReplicationTask,\n  EndpointType,\n  EndpointEngine,\n  MigrationType,\n  TableMappings,\n} from 'cdk-dms-replication';\n\n// 1. Replication instance\nconst instance = new DmsReplicationInstance(stack, 'Instance', {\n  vpc,\n  replicationInstanceClass: ReplicationInstanceClass.R6I_LARGE,\n  multiAz: true,\n});\n\n// Allow the source DB security group to accept connections from DMS\ninstance.allowInboundFrom(\n  ec2.Peer.securityGroupId(myDbSg.securityGroupId),\n  ec2.Port.tcp(3306),\n);\n\n// 2. Endpoints\nconst source = new DmsEndpoint(stack, 'Source', {\n  endpointType: EndpointType.SOURCE,\n  engine: EndpointEngine.MYSQL,\n  serverName: 'mysql.example.com',\n  port: 3306,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('db-secret'),\n  databaseName: 'mydb',\n});\n\nconst target = new DmsEndpoint(stack, 'Target', {\n  endpointType: EndpointType.TARGET,\n  engine: EndpointEngine.S3,\n  s3Settings: {\n    bucketName: 'my-bucket',\n    serviceAccessRoleArn: s3Role.roleArn,\n  },\n});\n\n// 3. Replication task\nnew DmsReplicationTask(stack, 'Task', {\n  replicationInstanceArn: instance.replicationInstanceArn,\n  sourceEndpoint: source,\n  targetEndpoint: target,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  tableMappings: new TableMappings().includeSchema('public').toJson(),\n});\n```\n\n---\n\n## Using existing endpoints\n\nBring your own endpoints if they already exist (e.g., created outside CDK or in a different stack):\n\n```typescript\nimport { IDmsEndpoint } from 'cdk-dms-replication';\n\n// Reference an existing endpoint by ARN\nconst existingSource: IDmsEndpoint = {\n  endpointArn: 'arn:aws:dms:us-east-1:123456789012:endpoint:ABCDEF',\n};\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.CDC,\n  existingSourceEndpoint: existingSource,\n  targetEndpoint: {\n    engine: EndpointEngine.S3,\n    s3Settings: { ... },\n  },\n});\n```\n\n---\n\n## Secrets Manager integration\n\nFor production workloads, store credentials in AWS Secrets Manager and let DMS retrieve them directly (no plaintext in CloudFormation):\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.MYSQL,\n  serverName: 'mysql.example.com',\n  port: 3306,\n  mySqlSettings: {\n    secretsManagerSecretId: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:dms/mysql-abc123',\n    secretsManagerAccessRoleArn: dmsSecretsRole.roleArn,\n  },\n},\n```\n\nThe secret must contain `username` and `password` keys. See [Using AWS Secrets Manager to access database credentials](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Security.html#security-iam-secretsmanager) for the required secret format and IAM permissions.\n\n---\n\n## Cross-account migrations\n\nDMS supports migrating data between AWS accounts. The replication instance always lives in one account (the **DMS account**) and connects to source and target databases over the network, regardless of which account owns them.\n\n### Prerequisites\n\nTwo things must be true before the construct can help:\n\n1. **Network connectivity** — The replication instance's VPC must be able to reach both endpoints. Establish this with [VPC peering](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html), [AWS Transit Gateway](https://docs.aws.amazon.com/vpc/latest/tgw/what-is-transit-gateway.html), or [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) before deploying. The construct has no visibility into routing — it will synthesise correctly regardless, but the task will fail at runtime if the endpoints are unreachable.\n\n2. **IAM cross-account trust** — For AWS-managed targets (S3, Kinesis, Redshift, DynamoDB, etc.) owned by a different account, DMS needs an IAM role in the **target account** that trusts the DMS service principal in the **DMS account**.\n\n### CDK stack setup\n\nCDK cannot pass constructs like `ec2.IVpc` across account boundaries. Use `Vpc.fromLookup` in the DMS account stack to reference the VPC by ID:\n\n```typescript\n// DMS account stack (e.g. account 111111111111)\nconst vpc = ec2.Vpc.fromLookup(stack, 'Vpc', {\n  vpcId: 'vpc-0abc1234def567890',\n});\n```\n\n### Database endpoints (any engine)\n\nFor source or target databases running in another account, provide the hostname that is reachable from the replication instance's VPC (private IP, private DNS name, or VPC peering DNS). No special construct configuration is needed beyond what you would use for a same-account migration.\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n\n  // Source DB in account 222222222222, reachable via Transit Gateway\n  sourceEndpoint: {\n    engine: EndpointEngine.ORACLE,\n    serverName: '10.1.2.3',           // private IP from peered VPC\n    port: 1521,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('oracle-dms-secret'),\n    databaseName: 'ORCL',\n  },\n\n  // Target in the same DMS account — normal config\n  targetEndpoint: {\n    engine: EndpointEngine.AURORA_POSTGRESQL,\n    serverName: cluster.clusterEndpoint.hostname,\n    port: 5432,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('aurora-dms-secret'),\n    databaseName: 'mydb',\n  },\n});\n```\n\n### AWS-managed targets in another account (S3, Kinesis, Redshift, etc.)\n\nWhen the target service lives in a different account, create an IAM role in the **target account** that DMS (running in the DMS account) can assume. Pass its ARN via `serviceAccessRoleArn`.\n\n**Step 1 — Create the cross-account role in the target account (222222222222):**\n\n```typescript\n// In a stack deployed to the TARGET account (222222222222)\nconst crossAccountDmsRole = new iam.Role(targetStack, 'DmsCrossAccountRole', {\n  assumedBy: new iam.CompositePrincipal(\n    // Allow DMS in the DMS account to assume this role\n    new iam.ArnPrincipal(`arn:aws:iam::111111111111:role/dms-vpc-role`),\n    new iam.ServicePrincipal('dms.amazonaws.com'),\n  ),\n  inlinePolicies: {\n    S3Access: new iam.PolicyDocument({\n      statements: [\n        new iam.PolicyStatement({\n          actions: ['s3:PutObject', 's3:DeleteObject', 's3:ListBucket'],\n          resources: [\n            targetBucket.bucketArn,\n            `${targetBucket.bucketArn}/*`,\n          ],\n        }),\n      ],\n    }),\n  },\n});\n```\n\n**Step 2 — Reference the role ARN in the DMS account stack:**\n\n```typescript\n// In the DMS account stack (111111111111)\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD,\n  sourceEndpoint: {\n    engine: EndpointEngine.MYSQL,\n    serverName: 'mysql.internal.example.com',\n    port: 3306,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('mysql-dms-secret'),\n    databaseName: 'orders',\n  },\n  targetEndpoint: {\n    engine: EndpointEngine.S3,\n    s3Settings: {\n      bucketName: 'target-account-bucket',   // bucket in account 222222222222\n      serviceAccessRoleArn: 'arn:aws:iam::222222222222:role/DmsCrossAccountRole',\n    },\n  },\n});\n```\n\nThe same pattern applies to Kinesis, Redshift, DynamoDB, and other AWS-managed targets — create the role in the target account, grant it the permissions that service needs, and pass its ARN to the relevant `serviceAccessRoleArn` field.\n\n### Cross-account Secrets Manager\n\nIf the database credentials are stored in Secrets Manager in the source account (222222222222) but DMS runs in a different account (111111111111):\n\n1. Add a [resource-based policy](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-based-policies.html) to the secret in account 222222222222 that allows the DMS account's role to call `secretsmanager:GetSecretValue`.\n2. Pass the full secret ARN and the cross-account access role ARN to the endpoint settings:\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.MYSQL,\n  serverName: 'mysql.internal.example.com',\n  port: 3306,\n  mySqlSettings: {\n    secretsManagerSecretId:\n      'arn:aws:secretsmanager:us-east-1:222222222222:secret:dms/mysql-abc123',\n    secretsManagerAccessRoleArn:\n      'arn:aws:iam::111111111111:role/DmsSecretsManagerRole',\n  },\n},\n```\n\n### Cross-account KMS encryption\n\nThe construct creates a KMS key in the DMS account for replication instance storage. If you need the replication instance to write to a KMS-encrypted target in another account, bring your own key and add a cross-account statement to its key policy:\n\n```typescript\n// Key in the DMS account (111111111111), with cross-account decrypt permission\nconst encryptionKey = new kms.Key(stack, 'ReplicationKey', {\n  enableKeyRotation: true,\n  policy: new iam.PolicyDocument({\n    statements: [\n      // Standard key admin/use permissions ...\n      new iam.PolicyStatement({\n        principals: [new iam.AccountPrincipal('222222222222')],\n        actions: ['kms:Decrypt', 'kms:GenerateDataKey'],\n        resources: ['*'],\n      }),\n    ],\n  }),\n});\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  encryptionKey,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n### Summary of cross-account responsibilities\n\n| Concern | Who sets it up | How to configure |\n|---------|---------------|-----------------|\n| Network connectivity | You (VPC peering / TGW / PrivateLink) | Prerequisite — no construct prop |\n| Database endpoint hostname | You | `serverName` — use private IP or private DNS |\n| Cross-account service role (S3, Kinesis, etc.) | You (role in target account) | `serviceAccessRoleArn` |\n| Cross-account Secrets Manager | You (resource policy on secret) | `secretsManagerSecretId` + `secretsManagerAccessRoleArn` |\n| Cross-account KMS | You (key policy) | `encryptionKey` (bring your own) |\n| Replication instance, subnet group, task | This construct | Fully managed |\n\n---\n\n## Observability\n\nA CloudWatch Logs log group is created by default. Customise the retention period or disable it:\n\n```typescript\nimport * as logs from 'aws-cdk-lib/aws-logs';\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  enableCloudWatchLogs: true,\n  logRetention: logs.RetentionDays.THREE_MONTHS,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n---\n\n## API reference\n\nFull API documentation is available in [API.md](https://github.com/kckempf/cdk-dms-replication/blob/main/API.md) and on [Construct Hub](https://constructs.dev/packages/cdk-dms-replication).\n\n---\n\n## Supported source engines\n\n| Engine | `EndpointEngine` value |\n|--------|----------------------|\n| MySQL | `MYSQL` |\n| Amazon Aurora (MySQL) | `AURORA_MYSQL` |\n| PostgreSQL | `POSTGRES` |\n| Amazon Aurora (PostgreSQL) | `AURORA_POSTGRESQL` |\n| Oracle | `ORACLE` |\n| Microsoft SQL Server | `SQLSERVER` |\n| MariaDB | `MARIADB` |\n| SAP ASE (Sybase) | `SAP_ASE` |\n| IBM Db2 LUW | `IBM_DB2` |\n| IBM Db2 for z/OS | `IBM_DB2_ZOS` |\n| MongoDB | `MONGODB` |\n| Amazon DocumentDB | `DOCDB` |\n| Amazon S3 | `S3` |\n\n## Supported target engines\n\nAll source engines above, plus:\n\n| Engine | `EndpointEngine` value |\n|--------|----------------------|\n| Amazon S3 | `S3` |\n| Amazon DynamoDB | `DYNAMODB` |\n| Amazon Redshift | `REDSHIFT` |\n| Amazon Kinesis Data Streams | `KINESIS` |\n| Apache Kafka / Amazon MSK | `KAFKA` |\n| Amazon OpenSearch Service | `OPENSEARCH` |\n| Amazon Neptune | `NEPTUNE` |\n| Amazon ElastiCache for Redis | `REDIS` |\n\n---\n\n## Security considerations\n\n- The replication instance is placed in **private subnets** by default. Set `publiclyAccessible: true` only if required.\n- Storage is encrypted at rest using a **KMS customer-managed key** (auto-created if you don't provide one).\n- **Do not use the `password` prop in production.** The resolved value is written as plaintext into the CloudFormation template and state file. Use Secrets Manager instead: set `secretsManagerSecretId` and `secretsManagerAccessRoleArn` in the engine-specific settings and omit `password` entirely.\n- Grant DMS only the minimum IAM permissions required for each target engine.\n- For CDC with PostgreSQL, the replication user needs the `rds_replication` role (RDS) or `REPLICATION` privilege (self-managed).\n- For CDC with Oracle, supplemental logging must be enabled on the source database.\n- **`dms-vpc-role` and `dms-cloudwatch-logs-role`** are account-level IAM roles required by DMS. When `createDmsServiceRoles` is `true` (the default), they are created idempotently via a custom resource — if they already exist in the account (created by another stack or manually), the existing roles are silently reused and their trust policies corrected if necessary. The roles are created with `RemovalPolicy.RETAIN` and are **not** lifecycle-managed by the deploying stack; they will not be deleted when the stack is destroyed. If you require the roles to be lifecycle-managed, create them in a dedicated stack and set `createDmsServiceRoles: false`.\n\n---\n\n## Contributing\n\nBug reports and pull requests are welcome. Please open an issue at [github.com/kckempf/cdk-dms-replication/issues](https://github.com/kckempf/cdk-dms-replication/issues) before starting significant work.\n\n---\n\n## Author\n\n[Kevin Kempf](https://github.com/kckempf)\n\n---\n\n## License\n\nApache-2.0 — see [LICENSE](https://github.com/kckempf/cdk-dms-replication/blob/main/LICENSE)\n"
+    "markdown": "# cdk-dms-replication\n\n[![npm version](https://badge.fury.io/js/cdk-dms-replication.svg)](https://badge.fury.io/js/cdk-dms-replication)\n[![PyPI version](https://badge.fury.io/py/cdk-dms-replication.svg)](https://badge.fury.io/py/cdk-dms-replication)\n[![build](https://github.com/kckempf/cdk-dms-replication/actions/workflows/build.yml/badge.svg)](https://github.com/kckempf/cdk-dms-replication/actions/workflows/build.yml)\n\nL3 CDK constructs for [Amazon Database Migration Service (DMS)](https://aws.amazon.com/dms/). Provision a complete migration pipeline — replication instance, endpoints, and task — in a few lines of code, with secure defaults and full support for all DMS-supported engines and migration patterns.\n\n## Features\n\n- **All migration patterns** — full load, CDC, and full-load-and-CDC\n- **Classic and Serverless** — `DmsMigrationPipeline` (fixed instance) or `DmsServerlessPipeline` (auto-scales DCUs)\n- **All DMS engines** — MySQL, PostgreSQL, Oracle, SQL Server, SAP ASE, IBM Db2, MongoDB, DocumentDB, S3, DynamoDB, Redshift, Kinesis, Kafka, OpenSearch, Neptune, Redis\n- **Secure defaults** — replication instance placed in private subnets, KMS encryption at rest, security group auto-created\n- **Fluent builders** — `TableMappings` and `TaskSettings` builders produce the JSON DMS expects without hand-crafting strings\n- **Multi-language** — TypeScript, Python, Java, .NET, Go (via JSII)\n- **Escape hatches** — pass existing endpoints or a pre-existing replication instance\n\n## Installation\n\n### TypeScript / JavaScript\n\n```bash\nnpm install cdk-dms-replication\n```\n\n### Python\n\n```bash\npip install cdk-dms-replication\n```\n\n### Java\n\n```xml\n<dependency>\n  <groupId>io.github.kckempf</groupId>\n  <artifactId>cdk-dms-replication</artifactId>\n  <version>VERSION</version>\n</dependency>\n```\n\n### .NET\n\n```bash\ndotnet add package KcKempf.CdkDmsReplication\n```\n\n### Go\n\n```bash\ngo get github.com/kckempf/cdk-dms-replication-go\n```\n\n---\n\n## Quick start\n\n### Classic pipeline (fixed replication instance)\n\n`DmsMigrationPipeline` provisions a replication instance, both endpoints, and a replication task in one construct.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport * as ec2 from 'aws-cdk-lib/aws-ec2';\nimport {\n  DmsMigrationPipeline,\n  EndpointEngine,\n  MigrationType,\n  TableMappings,\n} from 'cdk-dms-replication';\n\nconst app = new cdk.App();\nconst stack = new cdk.Stack(app, 'MigrationStack');\n\nconst vpc = ec2.Vpc.fromLookup(stack, 'Vpc', { isDefault: false });\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n\n  sourceEndpoint: {\n    engine: EndpointEngine.MYSQL,\n    serverName: 'mysql.internal.example.com',\n    port: 3306,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('mysql-dms-password'),\n    databaseName: 'orders',\n  },\n\n  targetEndpoint: {\n    engine: EndpointEngine.AURORA_POSTGRESQL,\n    serverName: cluster.clusterEndpoint.hostname,\n    port: 5432,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('aurora-dms-password'),\n    databaseName: 'orders',\n  },\n\n  tableMappings: new TableMappings()\n    .includeSchema('public')\n    .excludeTable('public', 'audit_log')\n    .toJson(),\n});\n```\n\n> **Note:** The `tableMappings` default (when omitted) is to include all tables in all schemas.\n\n### Serverless pipeline (auto-scaling)\n\n`DmsServerlessPipeline` uses DMS Serverless, which automatically scales capacity (measured in DMS Capacity Units — DCUs) between a configurable minimum and maximum. There is no replication instance to size or manage.\n\n```typescript\nimport {\n  DmsServerlessPipeline,\n  EndpointEngine,\n  MigrationType,\n} from 'cdk-dms-replication';\n\nnew DmsServerlessPipeline(stack, 'Pipeline', {\n  vpc,\n  maxCapacityUnits: 16,           // required; valid values: 1,2,4,8,16,32,64,128,192,256,384\n  minCapacityUnits: 2,            // optional; DMS auto-determines if omitted\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n\n  sourceEndpoint: {\n    engine: EndpointEngine.MYSQL,\n    serverName: 'mysql.internal.example.com',\n    port: 3306,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('mysql-dms-password'),\n    databaseName: 'orders',\n  },\n\n  targetEndpoint: {\n    engine: EndpointEngine.AURORA_POSTGRESQL,\n    serverName: cluster.clusterEndpoint.hostname,\n    port: 5432,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('aurora-dms-password'),\n    databaseName: 'orders',\n  },\n});\n```\n\n> **CDC start/stop position limitation:** `DmsServerlessPipeline` does not support `cdcStartPosition` or `cdcStartTime` at the CloudFormation level. To start replication from a specific LSN or timestamp, call the [`StartReplication` API](https://docs.aws.amazon.com/dms/latest/APIReference/API_StartReplication.html) after the config is created.\n\n---\n\n## Migration patterns\n\n### Full load\n\nMigrates all existing data once, then stops.\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n### CDC only\n\nReplicates ongoing changes starting from a specific position or time. The target must already be seeded with data.\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.CDC,\n  cdcStartPosition: 'mysql-bin-changelog.000024:373',  // binlog position\n  // — or —\n  cdcStartTime: '2024-01-01T00:00:00Z',                // ISO-8601 timestamp\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n### Full load then CDC\n\nMigrates existing data, then automatically switches to continuous replication.\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n---\n\n## Endpoint examples\n\n### MySQL / MariaDB / Aurora MySQL\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.MYSQL,          // or MARIADB, AURORA_MYSQL\n  serverName: 'mysql.example.com',\n  port: 3306,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('db-secret'),\n  databaseName: 'mydb',\n  mySqlSettings: {\n    parallelLoadThreads: 4,\n    serverTimezone: 'UTC',\n  },\n},\n```\n\n### PostgreSQL / Aurora PostgreSQL\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.POSTGRES,       // or AURORA_POSTGRESQL\n  serverName: 'pg.example.com',\n  port: 5432,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('db-secret'),\n  databaseName: 'appdb',\n  postgreSqlSettings: {\n    captureDdls: true,\n    slotName: 'dms_replication_slot',\n    pluginName: PostgresCdcPlugin.PG_LOGICAL,\n    heartbeatEnable: true,\n  },\n},\n```\n\n### Oracle\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.ORACLE,\n  serverName: 'oracle.example.com',\n  port: 1521,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('oracle-secret'),\n  databaseName: 'ORCL',\n  oracleSettings: {\n    addSupplementalLogging: true,\n    useLogminerReader: true,   // true = LogMiner, false = BinaryReader\n  },\n},\n```\n\n### SQL Server\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.SQLSERVER,\n  serverName: 'sqlserver.example.com',\n  port: 1433,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('sqlserver-secret'),\n  databaseName: 'AdventureWorks',\n  sqlServerSettings: {\n    readBackupOnly: false,\n    safeguardPolicy: SqlServerSafeguardPolicy.RELY_ON_SQL_SERVER_REPLICATION_AGENT,\n  },\n},\n```\n\n### MongoDB / DocumentDB\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.MONGODB,        // or DOCDB\n  serverName: 'mongo.example.com',\n  port: 27017,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('mongo-secret'),\n  mongoDbSettings: {\n    authType: MongoAuthType.PASSWORD,\n    authMechanism: MongoAuthMechanism.SCRAM_SHA_1,\n    nestingLevel: MongoNestingLevel.ONE,\n  },\n},\n```\n\n### Amazon S3 (source or target)\n\n```typescript\n// As a target\ntargetEndpoint: {\n  engine: EndpointEngine.S3,\n  s3Settings: {\n    bucketName: 'my-migration-data',\n    bucketFolder: 'dms-output',\n    serviceAccessRoleArn: s3Role.roleArn,\n    dataFormat: S3DataFormat.PARQUET,\n    parquetVersion: ParquetVersion.PARQUET_2_0,\n    datePartitionEnabled: true,\n    datePartitionSequence: DatePartitionSequence.YYYYMMDD,\n    encryptionMode: EncryptionMode.SSE_KMS,\n    serverSideEncryptionKmsKeyId: myKey.keyArn,\n  },\n},\n```\n\n### Amazon Redshift\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.REDSHIFT,\n  serverName: 'my-cluster.abc123.us-east-1.redshift.amazonaws.com',\n  port: 5439,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('redshift-secret'),\n  databaseName: 'dev',\n  redshiftSettings: {\n    bucketName: 'my-redshift-staging',\n    serviceAccessRoleArn: redshiftRole.roleArn,\n    encryptionMode: EncryptionMode.SSE_KMS,\n    serverSideEncryptionKmsKeyId: myKey.keyArn,\n    truncateColumns: true,\n    emptyAsNull: true,\n  },\n},\n```\n\n### Amazon Kinesis Data Streams\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.KINESIS,\n  kinesisSettings: {\n    streamArn: stream.streamArn,\n    serviceAccessRoleArn: kinesisRole.roleArn,\n    messageFormat: MessageFormat.JSON,\n    includeTransactionDetails: true,\n    includeTableAlterOperations: true,\n  },\n},\n```\n\n### Apache Kafka / Amazon MSK\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.KAFKA,\n  kafkaSettings: {\n    broker: 'b-1.my-cluster.abc123.kafka.us-east-1.amazonaws.com:9092',\n    topic: 'dms-changes',\n    messageFormat: MessageFormat.JSON,\n    securityProtocol: KafkaSecurityProtocol.SASL_SSL,\n    saslUsername: 'dms_user',\n    saslPassword: cdk.SecretValue.secretsManager('kafka-sasl-password'),\n  },\n},\n```\n\n### Amazon OpenSearch Service\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.OPENSEARCH,\n  openSearchSettings: {\n    endpointUri: 'https://search-my-domain.us-east-1.es.amazonaws.com',\n    serviceAccessRoleArn: openSearchRole.roleArn,\n    fullLoadErrorPercentage: 10,\n    errorRetryDuration: 300,\n  },\n},\n```\n\n### Amazon Neptune\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.NEPTUNE,\n  neptuneSettings: {\n    s3BucketName: 'my-neptune-staging',\n    s3BucketFolder: 'dms',\n    serviceAccessRoleArn: neptuneRole.roleArn,\n    iamAuthEnabled: true,\n  },\n},\n```\n\n### Amazon DynamoDB\n\n```typescript\ntargetEndpoint: {\n  engine: EndpointEngine.DYNAMODB,\n  dynamoDbSettings: {\n    serviceAccessRoleArn: dynamoRole.roleArn,\n  },\n},\n```\n\nDynamoDB targets also require an `object-mapping` rule per source table in the\ntable mappings. See [DynamoDB target (object mapping)](#dynamodb-target-object-mapping)\nbelow.\n\n---\n\n## Table mappings\n\nUse the `TableMappings` fluent builder to control which tables are migrated and how they are named on the target.\n\n### Selection rules\n\n```typescript\nnew TableMappings()\n  .includeSchema('public')               // include all tables in 'public'\n  .includeSchema('%')                    // include all schemas (wildcard)\n  .excludeTable('public', 'audit_log')  // exclude a specific table\n  .excludeSchema('internal')            // exclude an entire schema\n  .explicitTable('public', 'orders')    // migrate only this one table\n  .toJson()\n```\n\n### Transformation rules\n\n```typescript\nnew TableMappings()\n  .includeSchema('%')\n  .renameSchema('legacy', 'v2')          // rename schema on target\n  .toLowerCaseTable('public', '%')       // lowercase all table names\n  .toUpperCaseSchema('%')                // uppercase all schema names\n  .addPrefixToTable('public', '%', 'migrated_')\n  .renameTable('public', 'usr', 'users') // rename a specific table\n  .renameColumn('public', 'orders', 'cust_id', 'customer_id')\n  .removeColumn('public', 'orders', 'internal_notes')\n  .toJson()\n```\n\n### Adding columns\n\n```typescript\nnew TableMappings()\n  .includeSchema('public')\n  .addColumn('public', 'orders', {\n    columnName: 'migrated_at',\n    columnType: ColumnDataType.DATETIME,\n    expression: '$timestamp',       // DMS built-in expression\n  })\n  .addColumn('public', 'orders', {\n    columnName: 'migration_version',\n    columnType: ColumnDataType.STRING,\n    columnLength: 10,\n    columnValue: 'v2.0',           // constant value\n  })\n  .toJson()\n```\n\n### DynamoDB target (object mapping)\n\nWhen the target endpoint is DynamoDB, DMS requires an `object-mapping` rule per\nsource table that defines the partition key (and optionally a sort key) and\nhow source columns become DynamoDB attributes. Use `mapToDynamoDb()` alongside\nthe usual `includeTable()`:\n\n```typescript\nnew TableMappings()\n  .includeTable('public', 'orders')\n  .mapToDynamoDb('public', 'orders', {\n    targetTableName: 'Orders',\n    partitionKey: {\n      sourceColumn: 'order_id',\n      targetAttributeName: 'OrderId',\n      attributeSubType: DynamoDbAttributeSubType.STRING,\n    },\n    sortKey: {\n      sourceColumn: 'created_at',\n      targetAttributeName: 'CreatedAt',\n      attributeSubType: DynamoDbAttributeSubType.STRING,\n    },\n    excludeColumns: ['internal_flag'],\n    attributeMappings: [\n      {\n        sourceColumn: 'customer_id',\n        targetAttributeName: 'CustomerId',\n        attributeSubType: DynamoDbAttributeSubType.STRING,\n      },\n    ],\n  })\n  .toJson()\n```\n\nSource columns not listed in `attributeMappings` or `excludeColumns` are\nmigrated under their source column name.\n\n#### Composite key values\n\nFor DynamoDB single-table designs you often need composite keys built from a\nliteral prefix plus one or more source columns. Use `value` instead of\n`sourceColumn` to provide a raw DMS expression:\n\n```typescript\nnew TableMappings()\n  .includeTable('public', 'orders')\n  .mapToDynamoDb('public', 'orders', {\n    targetTableName: 'AppTable',\n    partitionKey: {\n      value: 'CUSTOMER#${customer_id}',\n      targetAttributeName: 'PK',\n      attributeSubType: DynamoDbAttributeSubType.STRING,\n    },\n    sortKey: {\n      value: 'ORDER#${order_id}',\n      targetAttributeName: 'SK',\n      attributeSubType: DynamoDbAttributeSubType.STRING,\n    },\n  })\n  .toJson()\n```\n\nExactly one of `sourceColumn` or `value` must be set on each key/attribute\nmapping — the builder throws at synth time otherwise.\n\n---\n\n## Task settings\n\nUse `TaskSettings` to tune LOB handling, error behaviour, full-load parallelism, and CDC batching.\n\n```typescript\nimport { TaskSettings, LobMode, ErrorAction, LoggingLevel } from 'cdk-dms-replication';\n\nconst settings = new TaskSettings()\n  // LOB handling\n  .withLobMode(LobMode.LIMITED_LOB, 64)   // truncate LOBs at 64 KB\n\n  // Full load tuning\n  .withFullLoadSubTasks(16)                // 16 parallel table loads\n  .withTargetTablePrepMode('DROP_AND_CREATE')\n  .withCommitRate(50000)                   // commit every 50k rows\n\n  // CDC batch apply\n  .withBatchApply(true, 5, 60)            // batch changes, 5–60 second window\n\n  // Error handling\n  .withDataErrorPolicy(ErrorAction.IGNORE_RECORD, 1000)\n  .withRecovery(-1, 5)                    // unlimited retries, 5s interval\n\n  // Logging\n  .withLogging('SOURCE_UNLOAD', LoggingLevel.LOGGER_SEVERITY_DEBUG)\n  .withLogging('TARGET_LOAD', LoggingLevel.LOGGER_SEVERITY_DEFAULT)\n  .toJson();\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  taskSettings: settings,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n---\n\n## Replication instance options\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n\n  // Instance sizing (default: R6I_LARGE)\n  replicationInstanceClass: ReplicationInstanceClass.R6I_4XLARGE,\n  allocatedStorage: 500,        // GB\n\n  // High availability\n  multiAz: true,\n\n  // Encryption — bring your own KMS key\n  encryptionKey: myKmsKey,\n\n  // Subnet placement\n  vpcSubnets: {\n    subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,\n  },\n\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n---\n\n## Using lower-level constructs directly\n\nIf you need more control, use the individual constructs and wire them together yourself.\n\n```typescript\nimport {\n  DmsReplicationInstance,\n  DmsEndpoint,\n  DmsReplicationTask,\n  EndpointType,\n  EndpointEngine,\n  MigrationType,\n  TableMappings,\n} from 'cdk-dms-replication';\n\n// 1. Replication instance\nconst instance = new DmsReplicationInstance(stack, 'Instance', {\n  vpc,\n  replicationInstanceClass: ReplicationInstanceClass.R6I_LARGE,\n  multiAz: true,\n});\n\n// Allow the source DB security group to accept connections from DMS\ninstance.allowInboundFrom(\n  ec2.Peer.securityGroupId(myDbSg.securityGroupId),\n  ec2.Port.tcp(3306),\n);\n\n// 2. Endpoints\nconst source = new DmsEndpoint(stack, 'Source', {\n  endpointType: EndpointType.SOURCE,\n  engine: EndpointEngine.MYSQL,\n  serverName: 'mysql.example.com',\n  port: 3306,\n  username: 'dms_user',\n  password: cdk.SecretValue.secretsManager('db-secret'),\n  databaseName: 'mydb',\n});\n\nconst target = new DmsEndpoint(stack, 'Target', {\n  endpointType: EndpointType.TARGET,\n  engine: EndpointEngine.S3,\n  s3Settings: {\n    bucketName: 'my-bucket',\n    serviceAccessRoleArn: s3Role.roleArn,\n  },\n});\n\n// 3. Replication task\nnew DmsReplicationTask(stack, 'Task', {\n  replicationInstanceArn: instance.replicationInstanceArn,\n  sourceEndpoint: source,\n  targetEndpoint: target,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  tableMappings: new TableMappings().includeSchema('public').toJson(),\n});\n```\n\n---\n\n## Using existing endpoints\n\nBring your own endpoints if they already exist (e.g., created outside CDK or in a different stack):\n\n```typescript\nimport { IDmsEndpoint } from 'cdk-dms-replication';\n\n// Reference an existing endpoint by ARN\nconst existingSource: IDmsEndpoint = {\n  endpointArn: 'arn:aws:dms:us-east-1:123456789012:endpoint:ABCDEF',\n};\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.CDC,\n  existingSourceEndpoint: existingSource,\n  targetEndpoint: {\n    engine: EndpointEngine.S3,\n    s3Settings: { ... },\n  },\n});\n```\n\n---\n\n## Secrets Manager integration\n\nFor production workloads, store credentials in AWS Secrets Manager and let DMS retrieve them directly (no plaintext in CloudFormation):\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.MYSQL,\n  serverName: 'mysql.example.com',\n  port: 3306,\n  mySqlSettings: {\n    secretsManagerSecretId: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:dms/mysql-abc123',\n    secretsManagerAccessRoleArn: dmsSecretsRole.roleArn,\n  },\n},\n```\n\nThe secret must contain `username` and `password` keys. See [Using AWS Secrets Manager to access database credentials](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Security.html#security-iam-secretsmanager) for the required secret format and IAM permissions.\n\n---\n\n## Cross-account migrations\n\nDMS supports migrating data between AWS accounts. The replication instance always lives in one account (the **DMS account**) and connects to source and target databases over the network, regardless of which account owns them.\n\n### Prerequisites\n\nTwo things must be true before the construct can help:\n\n1. **Network connectivity** — The replication instance's VPC must be able to reach both endpoints. Establish this with [VPC peering](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html), [AWS Transit Gateway](https://docs.aws.amazon.com/vpc/latest/tgw/what-is-transit-gateway.html), or [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) before deploying. The construct has no visibility into routing — it will synthesise correctly regardless, but the task will fail at runtime if the endpoints are unreachable.\n\n2. **IAM cross-account trust** — For AWS-managed targets (S3, Kinesis, Redshift, DynamoDB, etc.) owned by a different account, DMS needs an IAM role in the **target account** that trusts the DMS service principal in the **DMS account**.\n\n### CDK stack setup\n\nCDK cannot pass constructs like `ec2.IVpc` across account boundaries. Use `Vpc.fromLookup` in the DMS account stack to reference the VPC by ID:\n\n```typescript\n// DMS account stack (e.g. account 111111111111)\nconst vpc = ec2.Vpc.fromLookup(stack, 'Vpc', {\n  vpcId: 'vpc-0abc1234def567890',\n});\n```\n\n### Database endpoints (any engine)\n\nFor source or target databases running in another account, provide the hostname that is reachable from the replication instance's VPC (private IP, private DNS name, or VPC peering DNS). No special construct configuration is needed beyond what you would use for a same-account migration.\n\n```typescript\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n\n  // Source DB in account 222222222222, reachable via Transit Gateway\n  sourceEndpoint: {\n    engine: EndpointEngine.ORACLE,\n    serverName: '10.1.2.3',           // private IP from peered VPC\n    port: 1521,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('oracle-dms-secret'),\n    databaseName: 'ORCL',\n  },\n\n  // Target in the same DMS account — normal config\n  targetEndpoint: {\n    engine: EndpointEngine.AURORA_POSTGRESQL,\n    serverName: cluster.clusterEndpoint.hostname,\n    port: 5432,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('aurora-dms-secret'),\n    databaseName: 'mydb',\n  },\n});\n```\n\n### AWS-managed targets in another account (S3, Kinesis, Redshift, etc.)\n\nWhen the target service lives in a different account, create an IAM role in the **target account** that DMS (running in the DMS account) can assume. Pass its ARN via `serviceAccessRoleArn`.\n\n**Step 1 — Create the cross-account role in the target account (222222222222):**\n\n```typescript\n// In a stack deployed to the TARGET account (222222222222)\nconst crossAccountDmsRole = new iam.Role(targetStack, 'DmsCrossAccountRole', {\n  assumedBy: new iam.CompositePrincipal(\n    // Allow DMS in the DMS account to assume this role\n    new iam.ArnPrincipal(`arn:aws:iam::111111111111:role/dms-vpc-role`),\n    new iam.ServicePrincipal('dms.amazonaws.com'),\n  ),\n  inlinePolicies: {\n    S3Access: new iam.PolicyDocument({\n      statements: [\n        new iam.PolicyStatement({\n          actions: ['s3:PutObject', 's3:DeleteObject', 's3:ListBucket'],\n          resources: [\n            targetBucket.bucketArn,\n            `${targetBucket.bucketArn}/*`,\n          ],\n        }),\n      ],\n    }),\n  },\n});\n```\n\n**Step 2 — Reference the role ARN in the DMS account stack:**\n\n```typescript\n// In the DMS account stack (111111111111)\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD,\n  sourceEndpoint: {\n    engine: EndpointEngine.MYSQL,\n    serverName: 'mysql.internal.example.com',\n    port: 3306,\n    username: 'dms_user',\n    password: cdk.SecretValue.secretsManager('mysql-dms-secret'),\n    databaseName: 'orders',\n  },\n  targetEndpoint: {\n    engine: EndpointEngine.S3,\n    s3Settings: {\n      bucketName: 'target-account-bucket',   // bucket in account 222222222222\n      serviceAccessRoleArn: 'arn:aws:iam::222222222222:role/DmsCrossAccountRole',\n    },\n  },\n});\n```\n\nThe same pattern applies to Kinesis, Redshift, DynamoDB, and other AWS-managed targets — create the role in the target account, grant it the permissions that service needs, and pass its ARN to the relevant `serviceAccessRoleArn` field.\n\n### Cross-account Secrets Manager\n\nIf the database credentials are stored in Secrets Manager in the source account (222222222222) but DMS runs in a different account (111111111111):\n\n1. Add a [resource-based policy](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-based-policies.html) to the secret in account 222222222222 that allows the DMS account's role to call `secretsmanager:GetSecretValue`.\n2. Pass the full secret ARN and the cross-account access role ARN to the endpoint settings:\n\n```typescript\nsourceEndpoint: {\n  engine: EndpointEngine.MYSQL,\n  serverName: 'mysql.internal.example.com',\n  port: 3306,\n  mySqlSettings: {\n    secretsManagerSecretId:\n      'arn:aws:secretsmanager:us-east-1:222222222222:secret:dms/mysql-abc123',\n    secretsManagerAccessRoleArn:\n      'arn:aws:iam::111111111111:role/DmsSecretsManagerRole',\n  },\n},\n```\n\n### Cross-account KMS encryption\n\nThe construct creates a KMS key in the DMS account for replication instance storage. If you need the replication instance to write to a KMS-encrypted target in another account, bring your own key and add a cross-account statement to its key policy:\n\n```typescript\n// Key in the DMS account (111111111111), with cross-account decrypt permission\nconst encryptionKey = new kms.Key(stack, 'ReplicationKey', {\n  enableKeyRotation: true,\n  policy: new iam.PolicyDocument({\n    statements: [\n      // Standard key admin/use permissions ...\n      new iam.PolicyStatement({\n        principals: [new iam.AccountPrincipal('222222222222')],\n        actions: ['kms:Decrypt', 'kms:GenerateDataKey'],\n        resources: ['*'],\n      }),\n    ],\n  }),\n});\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  encryptionKey,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n### Summary of cross-account responsibilities\n\n| Concern | Who sets it up | How to configure |\n|---------|---------------|-----------------|\n| Network connectivity | You (VPC peering / TGW / PrivateLink) | Prerequisite — no construct prop |\n| Database endpoint hostname | You | `serverName` — use private IP or private DNS |\n| Cross-account service role (S3, Kinesis, etc.) | You (role in target account) | `serviceAccessRoleArn` |\n| Cross-account Secrets Manager | You (resource policy on secret) | `secretsManagerSecretId` + `secretsManagerAccessRoleArn` |\n| Cross-account KMS | You (key policy) | `encryptionKey` (bring your own) |\n| Replication instance, subnet group, task | This construct | Fully managed |\n\n---\n\n## Observability\n\nA CloudWatch Logs log group is created by default. Customise the retention period or disable it:\n\n```typescript\nimport * as logs from 'aws-cdk-lib/aws-logs';\n\nnew DmsMigrationPipeline(stack, 'Pipeline', {\n  vpc,\n  migrationType: MigrationType.FULL_LOAD_AND_CDC,\n  enableCloudWatchLogs: true,\n  logRetention: logs.RetentionDays.THREE_MONTHS,\n  sourceEndpoint: { ... },\n  targetEndpoint: { ... },\n});\n```\n\n---\n\n## API reference\n\nFull API documentation is available in [API.md](https://github.com/kckempf/cdk-dms-replication/blob/main/API.md) and on [Construct Hub](https://constructs.dev/packages/cdk-dms-replication).\n\n---\n\n## Supported source engines\n\n| Engine | `EndpointEngine` value |\n|--------|----------------------|\n| MySQL | `MYSQL` |\n| Amazon Aurora (MySQL) | `AURORA_MYSQL` |\n| PostgreSQL | `POSTGRES` |\n| Amazon Aurora (PostgreSQL) | `AURORA_POSTGRESQL` |\n| Oracle | `ORACLE` |\n| Microsoft SQL Server | `SQLSERVER` |\n| MariaDB | `MARIADB` |\n| SAP ASE (Sybase) | `SAP_ASE` |\n| IBM Db2 LUW | `IBM_DB2` |\n| IBM Db2 for z/OS | `IBM_DB2_ZOS` |\n| MongoDB | `MONGODB` |\n| Amazon DocumentDB | `DOCDB` |\n| Amazon S3 | `S3` |\n\n## Supported target engines\n\nAll source engines above, plus:\n\n| Engine | `EndpointEngine` value |\n|--------|----------------------|\n| Amazon S3 | `S3` |\n| Amazon DynamoDB | `DYNAMODB` |\n| Amazon Redshift | `REDSHIFT` |\n| Amazon Kinesis Data Streams | `KINESIS` |\n| Apache Kafka / Amazon MSK | `KAFKA` |\n| Amazon OpenSearch Service | `OPENSEARCH` |\n| Amazon Neptune | `NEPTUNE` |\n| Amazon ElastiCache for Redis | `REDIS` |\n\n---\n\n## Security considerations\n\n- The replication instance is placed in **private subnets** by default. Set `publiclyAccessible: true` only if required.\n- Storage is encrypted at rest using a **KMS customer-managed key** (auto-created if you don't provide one).\n- **Do not use the `password` prop in production.** The resolved value is written as plaintext into the CloudFormation template and state file. Use Secrets Manager instead: set `secretsManagerSecretId` and `secretsManagerAccessRoleArn` in the engine-specific settings and omit `password` entirely.\n- Grant DMS only the minimum IAM permissions required for each target engine.\n- For CDC with PostgreSQL, the replication user needs the `rds_replication` role (RDS) or `REPLICATION` privilege (self-managed).\n- For CDC with Oracle, supplemental logging must be enabled on the source database.\n- **`dms-vpc-role` and `dms-cloudwatch-logs-role`** are account-level IAM roles required by DMS. When `createDmsServiceRoles` is `true` (the default), they are created idempotently via a custom resource — if they already exist in the account (created by another stack or manually), the existing roles are silently reused and their trust policies corrected if necessary. The roles are created with `RemovalPolicy.RETAIN` and are **not** lifecycle-managed by the deploying stack; they will not be deleted when the stack is destroyed. If you require the roles to be lifecycle-managed, create them in a dedicated stack and set `createDmsServiceRoles: false`.\n\n---\n\n## Contributing\n\nBug reports and pull requests are welcome. Please open an issue at [github.com/kckempf/cdk-dms-replication/issues](https://github.com/kckempf/cdk-dms-replication/issues) before starting significant work.\n\n---\n\n## Author\n\n[Kevin Kempf](https://github.com/kckempf)\n\n---\n\n## License\n\nApache-2.0 — see [LICENSE](https://github.com/kckempf/cdk-dms-replication/blob/main/LICENSE)\n"
   },
   "repository": {
     "type": "git",
@@ -3622,7 +3622,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/table-mappings.ts",
-        "line": 71
+        "line": 78
       },
       "name": "AddColumnDefinition",
       "properties": [
@@ -3635,7 +3635,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 73
+            "line": 80
           },
           "name": "columnName",
           "type": {
@@ -3651,7 +3651,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 75
+            "line": 82
           },
           "name": "columnType",
           "type": {
@@ -3667,7 +3667,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 77
+            "line": 84
           },
           "name": "columnLength",
           "optional": true,
@@ -3684,7 +3684,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 79
+            "line": 86
           },
           "name": "columnPrecision",
           "optional": true,
@@ -3701,7 +3701,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 81
+            "line": 88
           },
           "name": "columnScale",
           "optional": true,
@@ -3719,7 +3719,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 89
+            "line": 96
           },
           "name": "columnValue",
           "optional": true,
@@ -3736,7 +3736,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 95
+            "line": 102
           },
           "name": "expression",
           "optional": true,
@@ -3884,7 +3884,7 @@
       "kind": "enum",
       "locationInModule": {
         "filename": "src/table-mappings.ts",
-        "line": 54
+        "line": 61
       },
       "members": [
         {
@@ -6563,6 +6563,329 @@
       ],
       "symbolId": "src/serverless-pipeline:DmsServerlessPipelineProps"
     },
+    "cdk-dms-replication.DynamoDbAttributeMapping": {
+      "assembly": "cdk-dms-replication",
+      "datatype": true,
+      "docs": {
+        "remarks": "Exactly one of `sourceColumn` or `value` must be set.\nSource columns not listed in `attributeMappings` or `excludeColumns` pass\nthrough with the source column name.",
+        "stability": "stable",
+        "summary": "Mapping from a source column (or DMS expression) to a non-key attribute on the DynamoDB target."
+      },
+      "fqn": "cdk-dms-replication.DynamoDbAttributeMapping",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/table-mappings.ts",
+        "line": 140
+      },
+      "name": "DynamoDbAttributeMapping",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "DynamoDB attribute sub-type (`string`, `number`, or `binary`)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 155
+          },
+          "name": "attributeSubType",
+          "type": {
+            "fqn": "cdk-dms-replication.DynamoDbAttributeSubType"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Name of the attribute on the DynamoDB target item."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 153
+          },
+          "name": "targetAttributeName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "The builder wraps this\nin the DMS expression `${sourceColumn}`. Mutually exclusive with `value`.",
+            "stability": "stable",
+            "summary": "Name of a single column on the relational source."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 145
+          },
+          "name": "sourceColumn",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Use this for composite values or\nother expressions like `'STATUS#${status}'`. Mutually exclusive with\n`sourceColumn`.",
+            "stability": "stable",
+            "summary": "Raw DMS value expression, used verbatim."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 151
+          },
+          "name": "value",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/table-mappings:DynamoDbAttributeMapping"
+    },
+    "cdk-dms-replication.DynamoDbAttributeSubType": {
+      "assembly": "cdk-dms-replication",
+      "docs": {
+        "stability": "stable",
+        "summary": "DynamoDB attribute sub-type for object-mapping rules."
+      },
+      "fqn": "cdk-dms-replication.DynamoDbAttributeSubType",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "src/table-mappings.ts",
+        "line": 54
+      },
+      "members": [
+        {
+          "docs": {
+            "stability": "stable"
+          },
+          "name": "STRING"
+        },
+        {
+          "docs": {
+            "stability": "stable"
+          },
+          "name": "NUMBER"
+        },
+        {
+          "docs": {
+            "stability": "stable"
+          },
+          "name": "BINARY"
+        }
+      ],
+      "name": "DynamoDbAttributeSubType",
+      "symbolId": "src/table-mappings:DynamoDbAttributeSubType"
+    },
+    "cdk-dms-replication.DynamoDbKeyMapping": {
+      "assembly": "cdk-dms-replication",
+      "datatype": true,
+      "docs": {
+        "remarks": "Exactly one of `sourceColumn` or `value` must be set.",
+        "stability": "stable",
+        "summary": "Mapping from a source column (or DMS expression) to a DynamoDB partition or sort key attribute."
+      },
+      "fqn": "cdk-dms-replication.DynamoDbKeyMapping",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/table-mappings.ts",
+        "line": 116
+      },
+      "name": "DynamoDbKeyMapping",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "DynamoDB attribute sub-type (`string`, `number`, or `binary`)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 131
+          },
+          "name": "attributeSubType",
+          "type": {
+            "fqn": "cdk-dms-replication.DynamoDbAttributeSubType"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Name of the partition/sort key attribute on the DynamoDB target item."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 129
+          },
+          "name": "targetAttributeName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "The builder wraps this\nin the DMS expression `${sourceColumn}`. Mutually exclusive with `value`.",
+            "stability": "stable",
+            "summary": "Name of a single column on the relational source."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 121
+          },
+          "name": "sourceColumn",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Use this for composite keys or\nother expressions like `'CUSTOMER#${customer_id}'`. Mutually exclusive\nwith `sourceColumn`.",
+            "stability": "stable",
+            "summary": "Raw DMS value expression, used verbatim."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 127
+          },
+          "name": "value",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/table-mappings:DynamoDbKeyMapping"
+    },
+    "cdk-dms-replication.DynamoDbObjectMappingOptions": {
+      "assembly": "cdk-dms-replication",
+      "datatype": true,
+      "docs": {
+        "stability": "stable",
+        "summary": "Options for `TableMappings.mapToDynamoDb`."
+      },
+      "fqn": "cdk-dms-replication.DynamoDbObjectMappingOptions",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/table-mappings.ts",
+        "line": 159
+      },
+      "name": "DynamoDbObjectMappingOptions",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Required.",
+            "stability": "stable",
+            "summary": "Mapping for the DynamoDB partition (hash) key."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 163
+          },
+          "name": "partitionKey",
+          "type": {
+            "fqn": "cdk-dms-replication.DynamoDbKeyMapping"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Name of the target DynamoDB table."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 161
+          },
+          "name": "targetTableName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Use this to rename non-key\ncolumns or change their DynamoDB sub-type. Columns not listed here pass\nthrough with the source column name.",
+            "stability": "stable",
+            "summary": "Additional column-to-attribute mappings."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 173
+          },
+          "name": "attributeMappings",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "fqn": "cdk-dms-replication.DynamoDbAttributeMapping"
+              },
+              "kind": "array"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Source columns to exclude from the migrated item."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 167
+          },
+          "name": "excludeColumns",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "array"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Optional.",
+            "stability": "stable",
+            "summary": "Mapping for the DynamoDB sort (range) key."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 165
+          },
+          "name": "sortKey",
+          "optional": true,
+          "type": {
+            "fqn": "cdk-dms-replication.DynamoDbKeyMapping"
+          }
+        }
+      ],
+      "symbolId": "src/table-mappings:DynamoDbObjectMappingOptions"
+    },
     "cdk-dms-replication.DynamoDbSettings": {
       "assembly": "cdk-dms-replication",
       "datatype": true,
@@ -10518,7 +10841,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/table-mappings.ts",
-        "line": 99
+        "line": 106
       },
       "name": "RuleObjectLocatorValue",
       "properties": [
@@ -10530,7 +10853,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 100
+            "line": 107
           },
           "name": "schemaName",
           "type": {
@@ -10545,7 +10868,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 102
+            "line": 109
           },
           "name": "columnName",
           "optional": true,
@@ -10561,7 +10884,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 101
+            "line": 108
           },
           "name": "tableName",
           "optional": true,
@@ -11843,7 +12166,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/table-mappings.ts",
-        "line": 106
+        "line": 177
       },
       "name": "TableMappingRule",
       "properties": [
@@ -11855,7 +12178,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 110
+            "line": 181
           },
           "name": "objectLocator",
           "type": {
@@ -11870,7 +12193,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 111
+            "line": 182
           },
           "name": "ruleAction",
           "type": {
@@ -11885,7 +12208,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 108
+            "line": 179
           },
           "name": "ruleId",
           "type": {
@@ -11900,7 +12223,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 109
+            "line": 180
           },
           "name": "ruleName",
           "type": {
@@ -11915,7 +12238,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 107
+            "line": 178
           },
           "name": "ruleType",
           "type": {
@@ -11930,7 +12253,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 113
+            "line": 184
           },
           "name": "oldValue",
           "optional": true,
@@ -11946,7 +12269,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 112
+            "line": 183
           },
           "name": "value",
           "optional": true,
@@ -11973,7 +12296,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/table-mappings.ts",
-        "line": 132
+        "line": 203
       },
       "methods": [
         {
@@ -11984,7 +12307,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 393
+            "line": 464
           },
           "name": "addColumn",
           "parameters": [
@@ -12020,7 +12343,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 232
+            "line": 303
           },
           "name": "addPrefixToSchema",
           "parameters": [
@@ -12050,7 +12373,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 294
+            "line": 365
           },
           "name": "addPrefixToTable",
           "parameters": [
@@ -12086,7 +12409,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 244
+            "line": 315
           },
           "name": "addSuffixToSchema",
           "parameters": [
@@ -12116,7 +12439,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 306
+            "line": 377
           },
           "name": "addSuffixToTable",
           "parameters": [
@@ -12152,7 +12475,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 149
+            "line": 220
           },
           "name": "excludeSchema",
           "parameters": [
@@ -12176,7 +12499,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 162
+            "line": 233
           },
           "name": "excludeTable",
           "parameters": [
@@ -12207,7 +12530,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 170
+            "line": 241
           },
           "name": "explicitTable",
           "parameters": [
@@ -12238,7 +12561,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 144
+            "line": 215
           },
           "name": "includeSchema",
           "parameters": [
@@ -12263,7 +12586,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 157
+            "line": 228
           },
           "name": "includeTable",
           "parameters": [
@@ -12286,6 +12609,44 @@
             }
           }
         },
+        {
+          "docs": {
+            "example": "const mappings = new TableMappings()\n  .includeTable('public', 'orders')\n  .mapToDynamoDb('public', 'orders', {\n    targetTableName: 'Orders',\n    // Composite partition key from a literal prefix + source column:\n    partitionKey: {\n      value: 'CUSTOMER#${customer_id}',\n      targetAttributeName: 'PK',\n      attributeSubType: DynamoDbAttributeSubType.STRING,\n    },\n    // Bare source column for the sort key:\n    sortKey: {\n      sourceColumn: 'created_at',\n      targetAttributeName: 'CreatedAt',\n      attributeSubType: DynamoDbAttributeSubType.STRING,\n    },\n    excludeColumns: ['internal_flag'],\n    attributeMappings: [\n      {\n        sourceColumn: 'customer_id',\n        targetAttributeName: 'CustomerId',\n        attributeSubType: DynamoDbAttributeSubType.STRING,\n      },\n    ],\n  })\n  .toJson();",
+            "remarks": "Emits a DMS `object-mapping` rule with `rule-action: map-record-to-record`.\nDMS requires this rule type when the target endpoint is DynamoDB; the\npartition key (and optional sort key) tell DMS how to build the item key\nfrom source columns.\n\nSource columns not listed in `attributeMappings` or `excludeColumns` are\nmigrated with the source column name as the attribute name.\n\nFor each key or attribute mapping, set either `sourceColumn` (a single\ncolumn wrapped as `${col}`) or `value` (a raw DMS expression, e.g.\n`'CUSTOMER#${customer_id}'` for composite keys). Exactly one is required.\n\nCalling this method twice with the same `schemaName`/`tableName` emits two\nseparate rules; DMS will reject duplicate object-mapping rules at deploy\ntime. Call it once per source table.",
+            "stability": "stable",
+            "summary": "Map a relational source table to a DynamoDB target table."
+          },
+          "locationInModule": {
+            "filename": "src/table-mappings.ts",
+            "line": 556
+          },
+          "name": "mapToDynamoDb",
+          "parameters": [
+            {
+              "name": "schemaName",
+              "type": {
+                "primitive": "string"
+              }
+            },
+            {
+              "name": "tableName",
+              "type": {
+                "primitive": "string"
+              }
+            },
+            {
+              "name": "options",
+              "type": {
+                "fqn": "cdk-dms-replication.DynamoDbObjectMappingOptions"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "cdk-dms-replication.TableMappings"
+            }
+          }
+        },
         {
           "docs": {
             "stability": "stable",
@@ -12293,7 +12654,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 369
+            "line": 440
           },
           "name": "removeColumn",
           "parameters": [
@@ -12329,7 +12690,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 322
+            "line": 393
           },
           "name": "renameColumn",
           "parameters": [
@@ -12371,7 +12732,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 198
+            "line": 269
           },
           "name": "renameSchema",
           "parameters": [
@@ -12401,7 +12762,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 260
+            "line": 331
           },
           "name": "renameTable",
           "parameters": [
@@ -12438,7 +12799,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 476
+            "line": 685
           },
           "name": "toJson",
           "returns": {
@@ -12454,7 +12815,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 339
+            "line": 410
           },
           "name": "toLowerCaseColumn",
           "parameters": [
@@ -12490,7 +12851,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 210
+            "line": 281
           },
           "name": "toLowerCaseSchema",
           "parameters": [
@@ -12515,7 +12876,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 272
+            "line": 343
           },
           "name": "toLowerCaseTable",
           "parameters": [
@@ -12545,7 +12906,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 354
+            "line": 425
           },
           "name": "toUpperCaseColumn",
           "parameters": [
@@ -12581,7 +12942,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 221
+            "line": 292
           },
           "name": "toUpperCaseSchema",
           "parameters": [
@@ -12605,7 +12966,7 @@
           },
           "locationInModule": {
             "filename": "src/table-mappings.ts",
-            "line": 283
+            "line": 354
           },
           "name": "toUpperCaseTable",
           "parameters": [
@@ -13480,6 +13841,6 @@
       "symbolId": "src/table-mappings:TransformationAction"
     }
   },
-  "version": "0.1.12",
-  "fingerprint": "j7i4XdI+mKmEi3G1631qNk2r4nGql7DIfbek2SEI/PU="
+  "version": "0.1.13",
+  "fingerprint": "1l2+vGaCmbjjkpoqGmRhWQ6bQeLCsOXcaxNbcgL9qY4="
 }