DynamoDB database tools
This package provides a small set of aux4 commands to interact with AWS DynamoDB. It exposes commonly used operations (scan, query, get, put, update, delete), batch stream helpers (stream-write, stream-read) and simple table management commands intended for testing with local DynamoDB instances. Use it for quick CLI-driven DynamoDB tasks, test setups, or to power automation scripts inside the aux4 ecosystem.
It integrates with aux4 variable interpolation and supports streaming JSON/NJSON input for batch operations. The package is focused on developer convenience (local testing, batch imports/exports) while remaining usable with standard AWS credentials and regions.
aux4 aux4 pkger install aux4/db-dynamodbThe most common operation is scanning a table. This example runs a scan against "my-table" using the default region:
aux4 db dynamodb scan my-table --region us-east-1This runs a DynamoDB scan and prints matched items as JSON to stdout. Omit --region to use the default region (us-east-1), or provide --profile to use a named AWS CLI profile.
Note: to target a local DynamoDB instance use --endpointUrl <URL> (for example: http://127.0.0.1:8000).
Overview
Put an item by piping JSON into the command:
echo '{"id":"user1","name":"John","age":28,"email":"john@example.com"}' \
| aux4 db dynamodb put test-users --region us-east-1Retrieve the item by primary key (single key "id"):
aux4 db dynamodb get test-users --key id --id user1 --region us-east-1 | jq .Delete the item by key:
aux4 db dynamodb delete test-users --key id --id user1 --region us-east-1For composite keys, pass multiple key field names to --key and supply the matching values as flags (one per key name).
Update specific attributes of an item without replacing the whole item, using a DynamoDB update expression. Unlike put (which overwrites the entire item), update performs an atomic partial modification and prints the updated item (ALL_NEW):
aux4 db dynamodb update test-users --key id --id user1 \
--updateExpression "SET age = :a" \
--attributeValues '{":a": 29}' --region us-east-1Use --attributeNames for reserved keywords, and combine SET/REMOVE/ADD clauses in one expression:
aux4 db dynamodb update test-users --key id --id user1 \
--updateExpression "SET #n = :n REMOVE obsolete" \
--attributeNames '{"#n": "name"}' \
--attributeValues '{":n": "Jane"}' --region us-east-1For command reference see:
Overview
Write a JSON array of items into a table:
echo '[{"id":"array1","name":"Array User 1","age":25},{"id":"array2","name":"Array User 2","age":30}]' \
| aux4 db dynamodb stream-write test-stream-array --region us-east-1Write newline-delimited JSON (NJSON) into a table (use --stream true):
echo '{"id":"njson1","name":"NJSON User 1","age":28}
{"id":"njson2","name":"NJSON User 2","age":32}' \
| aux4 db dynamodb stream-write test-stream-njson --stream true --region us-east-1Batch-read multiple keys supplied as a JSON array:
echo '[{"id":"array1"},{"id":"array2"}]' | aux4 db dynamodb stream-read test-stream-array --region us-east-1 | jq .Batch-read using NJSON keys:
echo '{"id":"njson1"}
{"id":"njson2"}' | aux4 db dynamodb stream-read test-stream-njson --stream true --region us-east-1 | jq .For stream-write, default batchSize is 25 (DynamoDB batch-write-item max 25). For stream-read, default batchSize is 100 (DynamoDB batch-get-item max 100).
For command reference see:
Overview
Create a simple table (example with a single-string primary key):
aux4 db dynamodb create-table test-users \
--keySchema '[{"AttributeName":"id","KeyType":"HASH"}]' \
--attributeDefinitions '[{"AttributeName":"id","AttributeType":"S"}]' \
--billingMode PAY_PER_REQUEST \
--region us-east-1Delete the table:
aux4 db dynamodb delete-table test-users --region us-east-1These commands are convenient when running local DynamoDB instances during tests. Use the --endpointUrl flag to point to a local endpoint if needed.
For command reference see:
Common variables (available across subcommands)
SET latest = :v (update) (default: "")Required vs optional: table is positional and required for most commands. Most other flags are optional; region defaults to us-east-1. Use --key for get/delete when the primary key has multiple attributes.
Create a table, put an item, get it back, then clean up. These commands run against your configured AWS environment unless an endpoint is supplied.
aux4 db dynamodb create-table test-users --region us-east-1
echo '{"id":"user1","name":"John","age":28}' | aux4 db dynamodb put test-users --region us-east-1
aux4 db dynamodb get test-users --key id --id user1 --region us-east-1 | jq .
aux4 db dynamodb delete test-users --region us-east-1This sequence creates test-users, inserts a single item, retrieves it as JSON, and removes the table.
Write multiple items in one JSON array and then read them back by keys.
echo '[{"id":"array1","name":"Array User 1","age":25},{"id":"array2","name":"Array User 2","age":30}]' \
| aux4 db dynamodb stream-write test-stream-array --region us-east-1
echo '[{"id":"array1"},{"id":"array2"}]' \
| aux4 db dynamodb stream-read test-stream-array --region us-east-1 | jq .The stream-read command returns the full items found in the table.
Use newline-delimited JSON to write and read when working with streaming workflows.
echo '{"id":"njson1","name":"NJSON User 1","age":28}
{"id":"njson2","name":"NJSON User 2","age":32}' \
| aux4 db dynamodb stream-write test-stream-njson --stream true --region us-east-1
echo '{"id":"njson1"}
{"id":"njson2"}' | aux4 db dynamodb stream-read test-stream-njson --stream true --region us-east-1 | jq .This writes two NJSON items and then retrieves them; stream-read emits each item as JSON (newline-separated when --stream true).
This package is licensed under the Apache License, Version 2.0.
See LICENSE for details.