Scrittura condizionale DynamoDB in Node.js (AWS SDK v3)

Una scrittura condizionale collega una ConditionExpression a PutItem, UpdateItem o DeleteItem: DynamoDB la valuta rispetto all'Item corrente e applica la scrittura solo se è vera — in modo atomico, senza race di lettura-modifica-scrittura. È la primitiva di locking ottimistico di DynamoDB. Questo esempio protegge un aggiornamento con un controllo di versione.

Code

import {DynamoDBClient, UpdateItemCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

// Update the item only if nobody changed it since we read version 7.
const command = new UpdateItemCommand({
  TableName: 'Music',
  Key: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'}
  },
  UpdateExpression: 'SET #upd0 = :updValue0, #version = :newVersion',
  ConditionExpression: 'attribute_exists(#cond0) AND #version = :expectedVersion',
  ExpressionAttributeNames: {
    '#upd0': 'Genre',
    '#version': 'Version',
    '#cond0': 'Artist'
  },
  ExpressionAttributeValues: {
    ':updValue0': {S: 'Latin Jazz'},
    ':expectedVersion': {N: '7'},
    ':newVersion': {N: '8'}
  },
  ReturnValuesOnConditionCheckFailure: 'ALL_OLD'
});

try {
  await client.send(command);
  console.log('Updated to version 8');
} catch (err) {
  if (err.name === 'ConditionalCheckFailedException') {
    // With ReturnValuesOnConditionCheckFailure: 'ALL_OLD', the current item
    // rides back on the exception — no extra read to see what beat you.
    console.log('Lost the race — item is now:', err.Item);
  } else {
    throw err;
  }
}

Spiegazione

ConditionExpression — verificata rispetto all'Item memorizzato in modo atomico con la scrittura. Funzioni disponibili: attribute_exists, attribute_not_exists, attribute_type, contains, begins_with, size, più i comparatori (=, <>, <, >, <=, >=, BETWEEN, IN) e AND/OR/NOT.
I due idiomi principali:
- attribute_exists(#key) su un update = "solo aggiornamento, mai creazione". Senza di essa, UpdateItem su una chiave mancante crea silenziosamente l'Item (il bug dell'upsert accidentale).
- attribute_not_exists(#key) su un put = "solo creazione, mai sovrascrittura" — mostrato nella pagina PutItem.
Locking ottimistico — leggi l'Item (versione 7), poi scrivi con #version = :expectedVersion incrementando a 8. Due writer concorrenti non possono vincere entrambi; il perdente ottiene ConditionalCheckFailedException, rilegge e riprova sulla nuova versione.
ReturnValuesOnConditionCheckFailure: 'ALL_OLD' — mette l'Item corrente sull'eccezione (err.Item, marshalled), risparmiando il GetItem successivo dopo un controllo fallito. Non consuma alcuna capacità di lettura; una scrittura condizionale fallita fattura comunque il suo tentativo di scrittura.
Qui tutto è aliasato (#version → Version) tramite ExpressionAttributeNames, così le parole riservate non danno problemi.

Fallo visivamente

Le espressioni di condizione sono esattamente ciò che costruisce il DynamoDB Expression Builder — scegli la funzione, ottieni l'espressione + le mappe di nomi/valori come codice eseguibile.

Per modificare gli Item con espressioni generate e verificabili invece di segnaposto digitati a mano — scarica DynoTable.

Esempi correlati

Scrittura condizionale DynamoDB in Python — lo stesso lock ottimistico con boto3.
Scrittura condizionale DynamoDB con la AWS CLI — lo stesso lock ottimistico dalla shell.
DynamoDB PutItem in Node.js — il put di sola creazione con attribute_not_exists.
Espressioni di condizione DynamoDB — ogni funzione, con esempi di pattern.
Garantire l'unicità su più attributi — condizioni + transazioni combinate.
DynamoDB ConditionalCheckFailedException — quando il controllo fallito è previsto e come gestirlo a basso costo.

References

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.