Node.js(AWS SDK v3)에서의 DynamoDB TransactWriteItems
TransactWriteItems는 최대 100개 쓰기를 하나의 전부 아니면 전무 연산으로 묶습니다 — 모든 액션이 커밋되거나, 하나도 커밋되지 않습니다. AWS SDK v3에서는 TransactItems 배열이 Put, Update, Delete, ConditionCheck 액션을 각각 선택적 조건과 함께 섞는 TransactWriteItemsCommand를 보냅니다.
Code
import {DynamoDBClient, TransactWriteItemsCommand} from '@aws-sdk/client-dynamodb';
const client = new DynamoDBClient({region: 'us-east-1'});
// Move one award between two songs — atomically. If the first song has no
// award to give, NEITHER update happens.
const command = new TransactWriteItemsCommand({
TransactItems: [
{
Update: {
TableName: 'Music',
Key: {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'Cubano Chant'}},
UpdateExpression: 'SET #upd0 = #upd0 - :one',
ConditionExpression: '#upd0 >= :one',
ExpressionAttributeNames: {'#upd0': 'Awards'},
ExpressionAttributeValues: {':one': {N: '1'}}
}
},
{
Update: {
TableName: 'Music',
Key: {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'A Mis Abuelos'}},
UpdateExpression: 'SET #upd0 = if_not_exists(#upd0, :zero) + :one',
ExpressionAttributeNames: {'#upd0': 'Awards'},
ExpressionAttributeValues: {':one': {N: '1'}, ':zero': {N: '0'}}
}
}
]
});
try {
await client.send(command);
console.log('Transaction committed');
} catch (err) {
if (err.name === 'TransactionCanceledException') {
// One reason per action, in TransactItems order. 'None' means that action
// was fine — some OTHER action sank the transaction.
const codes = (err.CancellationReasons ?? []).map((r) => r.Code);
console.log('Transaction canceled:', codes); // e.g. ['ConditionalCheckFailed', 'None']
} else {
throw err;
}
}Explanation
TransactItems— 최대 100개의Put/Update/Delete/ConditionCheck액션, 합계 4 MB입니다. 액션은 여러 테이블에 걸칠 수 있지만(동일 계정 + 리전), 두 액션이 동일한 항목을 대상으로 할 수 없습니다 — 그것만으로도 트랜잭션이 취소됩니다.ConditionCheck— 트랜잭션이 수정하지 않는 항목에 조건을 단언하고(예: "계정이 아직 존재함"), 실패하면 트랜잭션 전체를 거부합니다.TransactionCanceledException— 처리해야 할 유일한 오류입니다.err.CancellationReasons는 순서대로 액션당 하나의{Code, Message}를 나열합니다 — 코드에는ConditionalCheckFailed,TransactionConflict(다른 트랜잭션이 진행 중에 항목을 건드림 — 백오프와 함께 재시도해도 안전),ProvisionedThroughputExceeded,ValidationError가 포함되며,None은 무고한 액션을 표시합니다. 액션에ReturnValuesOnConditionCheckFailure: 'ALL_OLD'를 설정하면 그 사유에 진 항목의 속성을 얻습니다.ClientRequestToken— 호출을 10분 동안 멱등적으로 만들려면 하나 전달하세요. 네트워크 타임아웃 후의 SDK 재시도가 쓰기를 두 번 적용할 수 없게 됩니다.- 비용 — 트랜잭션 쓰기는 항목당 두 번의 기본 쓰기(준비 + 커밋)를 소비하므로, 일반 쓰기의 약 2배 WCU를 청구합니다. 단일 항목 조건부 쓰기가 이미 한 항목에 대한 원자성을 제공할 때는 트랜잭션에 손대지 마세요.
Do it visually
각 액션 안의 조건 및 업데이트 표현식이 까다로운 부분입니다 — DynamoDB Expression Builder가 이름/값 맵과 함께 이를 조립하고 실행 가능한 코드를 복사해 줍니다.
GUI에서 항목을 편집하고 생성된 표현식을 검토하려면 — DynoTable을 다운로드하세요.
Related examples
- DynamoDB TransactWriteItems in Python — boto3를 사용한 동일한 트랜잭션.
- DynamoDB TransactWriteItems with the AWS CLI — 셸에서 실행하는 동일한 트랜잭션.
- DynamoDB conditional write in Node.js — 2배 비용 없이 단일 항목 원자성.
- DynamoDB transactions — 격리, 멱등성, 그리고 트랜잭션이 그만한 가치가 있는 경우.
- DynamoDB TransactionCanceledException — 모든 취소 사유 코드를 풀어서 설명.
- "Too many actions in a TransactWriteItems call" — 100개 액션 및 4 MB 트랜잭션 한도.
- "Transaction request cannot include multiple operations on one item" — 트랜잭션당 항목당 하나의 액션.
References
- TransactWriteItems — Amazon DynamoDB API Reference
- Amazon DynamoDB transactions: how it works — Amazon DynamoDB Developer Guide
- DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide
Last verified 2026-07-13 against the official AWS documentation linked above.