Tema 3 · 7 · DynamoDB: tabla Usuarios, CLI, Python y exportar/importar con S3

Presentación del Tema 3: «Creación de base de datos DynamoDB», «Acceso desde AWS CLI», «Ejemplo aplicaciones uso DynamoDB – Ejercicio 1» (Python: dynamodb-cli.py) y «Ejercicio 3» (exportar e importar con S3). Duración: unos 10 minutos con dynamodb-cli.py y unos 10 minutos más (casi todo espera) con S3: ~2,5 min la exportación y ~3 min la importación, incluso con 7 ítems (medido). Coste: con tablas pequeñas, céntimos; PITR cuesta 0,21 USD por GB-mes mientras esté activo.

¿Dudas con un script? Todos los scripts de esta carpeta traen su propia ayuda: python3 dynamodb-cli.py --ayuda (también vale --help o -h) explica los pasos y las opciones. Este README.md es el paso a paso de la actividad: tenlo a mano y consúltalo antes de preguntar.

Etiquetas de lo que creas. Todo recurso que crees a mano (máquina, volumen, bucket, base de datos, tabla, función...) ponle estas etiquetas, al crearlo (apartado Tags / Etiquetas) o después desde su pestaña de etiquetas: curso = G214, universidad = CUNEF y actividad = 03.07-dynamodbcli. Si algún día hay que borrar recursos a mano, se localizan todos de golpe con aws resourcegroupstaggingapi get-resources --region eu-north-1 --tag-filters Key=actividad,Values=03.07-dynamodbcli. Más detalle (cómo etiquetar con la CLI, cómo buscar y qué hacer en una emergencia): README principal, sección «Etiquetas».

Qué vas a hacer

Vas a trabajar con una base no relacional, Amazon DynamoDB: crear la tabla Usuarios (consola o CLI), leer y escribir ítems con la AWS CLI y con un script de Python (boto3) desde CloudShell, y por último exportar la tabla a S3 y reimportarla en una tabla nueva.

CloudShell ──aws dynamodb ... / dynamodb-cli.py──> tabla Usuarios (UserID, String)
tabla Usuarios ──export (PITR)──> S3 (AWSDynamoDB/<código>/data/*.json.gz) ──import──> tabla nueva

Qué se crea en AWS: la tabla Usuarios (modo on-demand), opcionalmente un bucket de S3, la exportación a S3 (carpeta AWSDynamoDB/), una tabla nueva al importar y un grupo de logs /aws-dynamodb/imports. dynamodb-cli.py en sí no crea nada: lee o escribe un ítem en una tabla que ya existe.

Qué contiene esta carpeta

Antes de empezar

• [ ] Cuenta de AWS propia, región de la consola eu-north-1 elegida ANTES de abrir CloudShell (CloudShell trabaja en la región de la consola).
• [ ] Sabes abrir AWS CloudShell (el icono >_ de la barra superior): terminal Linux en el navegador con la AWS CLI, unzip, nano y Python 3.
• [ ] La tabla Usuarios con clave de partición UserID (String) en eu-north-1 (el paso 1 la crea por CLI). Esta actividad no necesita la RDS ni Adminer.

Comprobación previa en CloudShell:

aws sts get-caller-identity
echo "$AWS_REGION"

Qué verás: un JSON con tu cuenta y eu-north-1. Si imprime otra región, cierra CloudShell, cambia la región de la consola a Estocolmo y ábrelo de nuevo.

Cómo llevar los ficheros a donde toque

Se hace en CloudShell, porque necesita credenciales de AWS.

1. En tu PC, comprime esta carpeta (clic derecho sobre 03.07-dynamodbcli > Comprimir en archivo ZIP, o Enviar a > Carpeta comprimida en zip en Windows 10). Obtienes 03.07-dynamodbcli.zip.
2. En la consola de AWS (región eu-north-1) abre CloudShell, pulsa Actions > Upload file y sube el zip.
3. Descomprime y deja el script listo:

unzip -o 03.07-dynamodbcli.zip && cd 03.07-dynamodbcli && chmod -R u+rwX .
sed -i 's/\r$//' *.py
chmod +x *.py
ls

Si ya subiste g214-materiales.zip (README principal), no necesitas este zip: entra con cd ~/g214-materiales/tema3/03.07-dynamodbcli y, si algún fichero da Permission denied, ejecuta allí chmod -R u+rwX . && chmod +x *.py.

sed quita los finales de línea de Windows (si no, bash falla con bad interpreter o $'\r': command not found) y chmod +x da permiso de ejecución (un zip creado en Windows no lo conserva; sin él, ./dynamodb-cli.py da Permission denied). Qué verás: ls muestra README.md y dynamodb-cli.py.

Alternativa para subir solo el script: Actions > Upload file y elige dynamodb-cli.py, y luego sed -i 's/\r$//' dynamodb-cli.py && chmod +x dynamodb-cli.py. Si cierras CloudShell, al volver entra con cd 03.07-dynamodbcli (si no encuentras la carpeta, vuelve a subir el zip).

Paso a paso

Paso 1. Crear la tabla Usuarios. En la presentación se crea desde la consola. El mismo resultado por CLI, en CloudShell:

aws dynamodb create-table --table-name Usuarios \
  --attribute-definitions AttributeName=UserID,AttributeType=S \
  --key-schema AttributeName=UserID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST --region eu-north-1
aws dynamodb wait table-exists --table-name Usuarios --region eu-north-1

Qué verás: TableStatus: CREATING y, tras wait (unos 25 s), la tabla ACTIVE en modo PAY_PER_REQUEST (on-demand). La consola, con Use default settings, puede elegir otro modo de capacidad; para el laboratorio da igual. Los tres ítems de la presentación (u001 a u003) se añaden con put-item o desde la consola. Modo de capacidad: aprovisionado (reservas lecturas y escrituras por segundo y las pagas aunque no las uses) o bajo demanda, PAY_PER_REQUEST (pagas solo por petición); para el laboratorio vale cualquiera.

Paso 2. Búsqueda en la consola. Resultado esperado del Scan con filtro UserID = u001 sobre los tres ítems: Items returned 1, Items scanned 3, RCUs consumed 2 y Efficiency 33,33 %; con Query solo se lee el ítem pedido.

Paso 3. Comandos aws dynamodb ... de la presentación. Resultados medidos: get-item de un ítem pequeño consume 0.5 unidades de lectura (1.0 con --consistent-read); query por clave, 0.5; scan de la tabla, 2.0 (también con 3 ó 7 ítems: cuesta 0,5 por cada partición de la tabla) y sin cambio con --projection-expression (la proyección reduce los datos devueltos, no el consumo). Límites que conviene saber: un ítem pesa como máximo 400 KB y batch-write-item admite 25 ítems por llamada. Dos consejos, porque esos comandos no llevan --region:

• Usan la región de tu CloudShell. Si tu tabla está en eu-north-1 y CloudShell en otra, list-tables saldrá vacío o dará tabla no encontrada: comprueba echo "$AWS_REGION" o añade --region eu-north-1.
• Para contar los ítems de una tabla no te fíes del contador del resumen de la consola (se actualiza cada varias horas; da 0 al principio). Cuenta con aws dynamodb scan --table-name Usuarios --select COUNT --region eu-north-1: el campo Count de la respuesta es el número de ítems.

Paso 4. Comprobar boto3.

python3 -c "import boto3; print(boto3.__version__)"

Qué verás: un número de versión. Si sale ModuleNotFoundError: No module named 'boto3', instálalo con pip3 install --user boto3. Si en una máquina Amazon Linux 2023 limpia el sistema responde pip3: command not found, instala pip primero (sudo dnf install -y python3-pip) y repite pip3 install --user boto3. Un aviso PythonDeprecationWarning sobre Python 3.9 es normal y no impide que el script funcione (dynamodb-cli.py ya lo silencia). La presentación solo dicen «sube el fichero, chmod +x y ejecuta»: si falla con Falta la libreria boto3, es esto. En CloudShell no suele hacer falta nada de esto (no se ha podido comprobar en un CloudShell real: si algo falla, avisa).

Opciones de dynamodb-cli.py:

Paso 5. Leer un ítem.

./dynamodb-cli.py --mode get --userid u001

Qué verás (en la salida real, las líneas de resultado llevan un icono delante y el orden de los atributos puede variar):

[INFO] Inicializando recurso DynamoDB en región eu-north-1…
[INFO] Consultando tabla 'Usuarios' con ConsistentRead=True…
[INFO] Key = {'UserID': 'u001'}
Se encontró el usuario con UserID='u001':
{
  "UserID": "u001",
  "Nombre": "Elena",
  ...
}

Si el UserID no existe: Conexión correcta, pero no existe UserID='...'. (código de salida 1). Si hay un error de AWS: Error al conectar o consultar DynamoDB: y el mensaje de AWS (código 2). Si no hay credenciales (por ejemplo, lo ejecutas en tu PC sin aws configure), el script dice No hay credenciales de AWS validas para este script y cómo arreglarlo (código 2). El código de salida se ve con echo $? justo después. Añade --quiet para ocultar las líneas [INFO].

Sin argumentos, ./dynamodb-cli.py pregunta: Seleccione modo: con 1) GET y 2) PUT (Opción [1/2, ENTER=1]); con GET pide UserID a consultar [ENTER = u001]. Con Enter en ambas preguntas lee u001.

Con una tabla de clave numérica (por ejemplo users con id numérica, la de la Práctica 2) hay que decírselo; si no, DynamoDB responde The provided key element does not match the schema:

./dynamodb-cli.py --mode get --userid 1002 --table users --key-name id --key-type Number

Qué verás: igual que arriba, con [INFO] Key = {'id': 1002} y Se encontró el usuario con id='1002': seguido del ítem. Si escribes algo que no es un número en --userid con --key-type Number, el script responde Clave no valida para el tipo Number: No es un número válido. (código de salida 2).

Paso 6. Escribir un ítem.

./dynamodb-cli.py --mode put

El script te guía: primero la clave (UserID por defecto; obligatoria y de tipo String, salvo que uses --key-type Number) y luego atributos, de uno en uno, con su nombre, su tipo (String, Number o Boolean) y su valor. Un Enter en Nombre atributo termina. Ejemplo con un usuario de prueba u900 (no es ninguno de los que te pide la presentación):

UserID (obligatorio, String): u900
Nombre atributo (ENTER para terminar): Nombre
Tipo [String/Number/Boolean]: String
Valor para 'Nombre' (String): Prueba
Nombre atributo (ENTER para terminar): Edad
Tipo [String/Number/Boolean]: Number
Valor para 'Edad' (Number): 30
Nombre atributo (ENTER para terminar):

Qué verás al terminar: Petición que se va a ejecutar (CLI): seguido del comando equivalente de la AWS CLI, por ejemplo:

aws dynamodb put-item --table-name Usuarios --region eu-north-1 --item '{"UserID": {"S": "u900"}, "Nombre": {"S": "Prueba"}, "Edad": {"N": "30"}}'

y después [INFO] con Enviando put_item a 'Usuarios'… y Item creado/actualizado correctamente. Fíjate en cómo viaja cada tipo (S, N, BOOL): es lo que explica la presentación.

Reglas del script:

• Cada ejecución crea o actualiza UN solo ítem. Para varios usuarios, ejecútalo varias veces.
• Si el UserID ya existe, put_item reemplaza el ítem entero: los atributos que no vuelvas a escribir se pierden (no se fusionan).
• El tipo hay que escribirlo tal cual: String, Number o Boolean (da igual mayúsculas o minúsculas). Number usa punto decimal (1.5, no 1,5). Boolean acepta true, false, 1, 0, si, sí, no, y, n. Un String no puede estar vacío. No se puede repetir el nombre de la clave como atributo.
• Otra tabla o región: ./dynamodb-cli.py --mode get --userid u001 --table <NombreTabla> --region eu-north-1. Si la clave de partición de esa tabla no es UserID de tipo String, añade --key-name <nombre> y --key-type String o Number según su tipo.

Paso 7. Comprobar con la AWS CLI y borrar la prueba.

aws dynamodb get-item --table-name Usuarios --key '{"UserID":{"S":"u900"}}' --region eu-north-1
aws dynamodb delete-item --table-name Usuarios --key '{"UserID":{"S":"u900"}}' --region eu-north-1

Qué verás: el primer comando devuelve un JSON con Item y cada valor con su tipo; el segundo no imprime nada. Si solo querías probar el script, borra así tu ítem de prueba. También puedes verlo en la consola de DynamoDB (tabla > Explore table items) o en el visor de 03.08.

Paso 8. Exportar e importar con S3 (ejercicio 3 de DynamoDB). Se hace en la consola (la presentación tiene el paso a paso); aquí tienes lo que no cuentan las diapositivas. En la presentación, el ejercicio 2 (visor web, actividad 03.08) va antes que este: si quieres seguir ese orden exacto, haz 03.08 antes de este paso (si no, el Count será 7 en vez de 8; ver «Comprobar»).

• Bucket: necesitas uno en la misma región que la tabla (eu-north-1). Si no lo tienes, créalo (por ejemplo aws s3 mb s3://<nombre-unico> --region eu-north-1).
• PITR: la exportación completa necesita Point-in-time recovery activado en la tabla (pestaña Backups); sin él, la consola o la CLI responden PointInTimeRecoveryUnavailableException. Activarlo tarda segundos, cuesta 0,21 USD por GB-mes y queda activo mientras exista la tabla (o hasta desactivarlo, ver Limpieza).
• Tiempos medidos: la exportación tarda unos 2,5 minutos y la importación unos 3, incluso con 7 ítems.
• Resultado: en el bucket aparece AWSDynamoDB/<código>/data/ con un fichero .json.gz por partición de la tabla (en una tabla pequeña son 4, y alguno está vacío; no es un error) más los ficheros manifest-*. La importación (carpeta data/, compresión GZIP, formato DynamoDB JSON, partition key UserID de tipo String) crea una tabla nueva con los mismos ítems; importar sobre una tabla existente da Table already exists.
• Comprobar: aws dynamodb scan --table-name <tabla-nueva> --select COUNT --region eu-north-1 debe dar el mismo Count que la original en ese momento: compáralo con aws dynamodb scan --table-name Usuarios --select COUNT --region eu-north-1. Si has seguido las diapositivas en orden son 8 ítems: 3 (u001 a u003) + 1 (u020) + 3 (u010 a u012) + 1 (el registro que añades en el ejercicio 2, con el visor de 03.08) = 8; serían 7 si no añadiste el del ejercicio 2. No es una pérdida de datos de la importación si coincide con el Count de Usuarios. No uses el ItemCount de la consola: tarda horas en actualizarse (da 0 al principio).
• Por CLI (si prefieres no usar la consola; sustituye <bucket> y <código>; el ARN de la tabla lo da aws dynamodb describe-table --table-name Usuarios --query Table.TableArn --output text --region eu-north-1):

aws dynamodb update-continuous-backups --table-name Usuarios --region eu-north-1   --point-in-time-recovery-specification PointInTimeRecoveryEnabled=true
aws dynamodb export-table-to-point-in-time --table-arn <ARN-de-Usuarios> --s3-bucket <bucket>   --export-format DYNAMODB_JSON --region eu-north-1
aws dynamodb list-exports --region eu-north-1        # ExportStatus COMPLETED al cabo de ~2,5 min
aws s3 ls s3://<bucket>/AWSDynamoDB/ --recursive      # el código de la carpeta
aws dynamodb import-table --region eu-north-1   --s3-bucket-source S3Bucket=<bucket>,S3KeyPrefix=AWSDynamoDB/<código>/data/   --input-format DYNAMODB_JSON --input-compression-type GZIP   --table-creation-parameters '{"TableName":"Usuarios-copia","AttributeDefinitions":[{"AttributeName":"UserID","AttributeType":"S"}],"KeySchema":[{"AttributeName":"UserID","KeyType":"HASH"}],"BillingMode":"PAY_PER_REQUEST"}'
aws dynamodb list-imports --region eu-north-1         # ImportStatus COMPLETED al cabo de ~3 min

Son los mismos pasos que la consola. import-table crea siempre una tabla nueva; si ImportStatus queda en FAILED, mira ItemValidationError y borra la tabla vacía que queda.

• Si la importación falla (por ejemplo, por escribir mal el nombre de la partition key): el estado queda en FAILED con ItemValidationError, el detalle está en CloudWatch Logs (grupo /aws-dynamodb/imports, Missing the key ... in the item) y la tabla nueva queda creada y vacía: bórrala.

Errores frecuentes

Limpieza

Hazla al terminar el ejercicio (y, en el caso de Usuarios, después de terminar 03.08, que la usa para el visor).

1. Tablas de DynamoDB: Usuarios y la tabla que creaste al importar desde S3 (Usuarios-copia si usaste la CLI).

aws dynamodb list-tables --region eu-north-1
aws dynamodb delete-table --table-name Usuarios --region eu-north-1

Repite delete-table con cada nombre. Si usas la consola y te ofrece crear una copia de seguridad antes de borrar, desmárcala. Si activaste PITR, se desactiva al borrar la tabla; si prefieres conservar la tabla, desactívalo antes: aws dynamodb update-continuous-backups --table-name Usuarios --point-in-time-recovery-specification PointInTimeRecoveryEnabled=false --region eu-north-1 (PITR cuesta 0,21 USD por GB-mes). Una importación fallida deja además una tabla nueva vacía: bórrala también.

2. Logs de la importación (la importación crea un grupo de logs que nadie borra):

aws logs delete-log-group --log-group-name /aws-dynamodb/imports --region eu-north-1

3. S3 de la exportación: en tu bucket, borra la carpeta AWSDynamoDB/ que creó la exportación (consola de S3 > marca la carpeta > Delete, o aws s3 rm s3://<tu-bucket>/AWSDynamoDB/ --recursive). Si creaste el bucket solo para esto, vacíalo y bórralo (aws s3 rb s3://<tu-bucket> --force).

4. Verificación:

aws dynamodb list-tables --region eu-north-1
aws logs describe-log-groups --log-group-name-prefix /aws-dynamodb --region eu-north-1 --query "logGroups[].logGroupName"

Qué debes ver: list-tables sin tus tablas de este tema y ningún grupo de logs /aws-dynamodb/imports.

Cómo sabes que has terminado

• [ ] La tabla Usuarios existe con clave UserID (String) y tiene tus ítems.
• [ ] dynamodb-cli.py lee (--mode get) y escribe (--mode put) ítems de Usuarios, y los has comprobado con aws dynamodb get-item.
• [ ] Has exportado la tabla a S3, importado en una tabla nueva y el Count de las dos coincide (8 ítems si seguiste las diapositivas en orden).
• [ ] Has hecho la limpieza: tablas, grupo de logs y carpeta AWSDynamoDB/ ya no existen (y PITR no queda activo).

Anterior: 03.06 · ACID y rigidez de esquema · Siguiente: 03.08 · Visor web de DynamoDB