Skip to Content
Cloud Engineering Academy
6. Databases & Data Architecture

Amazon DynamoDB fundamentals

Model Harbourline customers, accounts and transactions in a single DynamoDB table: choose partition and sort keys from access patterns, pick a capacity mode, add a global secondary index, and query it from .NET 10 with the AWS SDK v4 against DynamoDB Local.

intermediateโฑ 2 h 30 min๐ŸŸข FreeDVA-C03SAA-C03DEA-C01

Assumes: .NET 10 LTS ยท AWS SDK for .NET v4 (AWSSDK.DynamoDBv2 4.1.0.2) ยท DynamoDB Local (Docker) ยท AWS CLI v2 ยท Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Explain tables, items, attributes, partition keys, sort keys and item collections, and how DynamoDB spreads data across partitions.
  • Calculate read and write capacity units for a workload and choose between on-demand and provisioned capacity.
  • Design a single-table model for Harbourline customers, accounts and transactions, starting from a written list of access patterns.
  • Add a global secondary index (GSI) for an alternate lookup (by IBAN) and explain why local secondary indexes are rarely the right answer.
  • Write, query and paginate items from .NET 10 with the AWS SDK for .NET v4, against DynamoDB Local in Docker and then against AWS.

Prerequisites

Why this matters in banking

Harbourline's mobile app shows "your last 50 transactions" on its home screen. Fourteen million times a day. In the current SQL Server, that query joins Transactions to Accounts to Customers, sorts by date, and competes with month-end batch jobs for the same buffer pool. At 08:30 on payday the p99 latency hits two seconds.

The query itself is simple and predictable: one account, newest first, one page. That is exactly the shape DynamoDB was built for โ€” single-digit millisecond reads at any scale, with no connection pool to exhaust and no server to patch. But DynamoDB punishes the habits of relational design. Model it like SQL Server, with one table per entity and Scan with a filter in place of joins, and you get slow, expensive queries and a bill your FinOps team will notice. This lesson teaches the DynamoDB way of thinking so you can make the right call โ€” and so you know when to keep the workload relational.

The idea in plain language

DynamoDB is a key-value and document database. You store items (rows) in tables. Each item is a bag of attributes (columns) and can have different attributes from its neighbours. The only thing every item must have is its primary key:

  • Partition key (PK): DynamoDB hashes it to decide which physical partition stores the item. All lookups start with an exact partition key.
  • Sort key (SK, optional): orders items that share a partition key. You can ask for ranges: "SK between X and Y", "SK begins with Z", newest first.

Items that share a partition key form an item collection. Reading a whole collection, or a slice of it, is one fast Query.

You do not design tables around entities and then write queries. You list the questions the application will ask (access patterns), then design keys so each question is a single GetItem or Query.

Analogy: A SQL Server database is a library with a card catalogue: any question can be answered, but complex questions take the librarian a while. DynamoDB is a wall of labelled pigeonholes in a sorting office. If you know the label (partition key), you get your letters instantly and in date order (sort key). If you only know "letters from Manchester", you must open every pigeonhole (a Scan) โ€” unless you set up a second wall sorted by city (a GSI).

What problem DynamoDB solves

StrengthDetail
Predictable latency at any scaleSingle-digit milliseconds for key lookups, whether the table holds 1 GB or 100 TB
Fully serverlessNo instances, patching, connection limits or storage provisioning; Multi-AZ by default
Pay per request (on-demand)You pay for reads and writes you make; nothing for idle time except storage
IAM-native accessEvery call is a signed HTTPS request; permissions can go down to individual items with condition keys
Built-in featuresStreams, TTL, transactions, point-in-time recovery, global tables, export to S3

Limitations to know before you commit:

LimitValue (checked 2026-11-18)
Maximum item size400 KB, including attribute names
Partition key value length1 to 2,048 bytes
Sort key value length1 to 1,024 bytes
Throughput per partition3,000 read units and 1,000 write units per second
Query/Scan page sizeUp to 1 MB of data read per call; paginate with LastEvaluatedKey
BatchWriteItemUp to 25 put/delete requests
BatchGetItemUp to 100 items, 16 MB
GSIs per table20 (default quota, adjustable)
LSIs per table5, defined only when the table is created; item collection limited to 10 GB when an LSI exists

There are no joins, no ad hoc aggregation (SUM, GROUP BY) and no secondary lookups without an index. Reporting belongs in S3 + Athena or Redshift (lesson 14), fed by an export or by Streams.

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Azure Cosmos DB for NoSQLAmazon DynamoDBCosmos indexes every property by default; DynamoDB indexes only keys and the GSIs you define
Cosmos DB partition keyDynamoDB partition keySame idea; DynamoDB adds a sort key, so one partition can hold an ordered collection
Cosmos DB Request Units (RU/s)Read and write capacity units, or on-demand request unitsDynamoDB charges reads and writes separately and by item size
Cosmos DB serverless / autoscaleDynamoDB on-demand / provisioned with auto scalingOn-demand is the recommended default for new and spiky workloads
Azure Table StorageDynamoDBSimilar PartitionKey/RowKey model; DynamoDB adds GSIs, transactions, streams
SQL Server clustered index on (AccountId, BookingDate)Partition key ACC#โ€ฆ + sort key TX#date#idDynamoDB stores the collection physically together and sorted
SQL Server nonclustered indexGlobal secondary indexA GSI is a separately stored, asynchronously maintained copy with its own keys
EF Core DbContextAmazonDynamoDBClient (low-level) or DynamoDBContext (object persistence)There is no EF Core provider from AWS for DynamoDB; you use the SDK

Architecture

DynamoDB hashes the partition key and places the item on a partition. Each partition is replicated across three Availability Zones. As data or traffic grows, DynamoDB splits partitions automatically.

Security-boundary view: DynamoDB is a Regional public service endpoint. From private subnets, reach it through a gateway VPC endpoint (free) so traffic never needs a NAT gateway, and restrict the table with an IAM policy condition on aws:SourceVpce. Encryption at rest is always on (AWS owned key by default; choose an AWS managed key or a customer managed KMS key for audit control). Access is IAM only โ€” there are no database users or passwords.

Capacity: units, modes and cost

Units

  • 1 write unit = one write per second of an item up to 1 KB (round up). A 2.5 KB item costs 3 write units.
  • 1 read unit = one strongly consistent read per second of up to 4 KB, or two eventually consistent reads. A 6 KB item read eventually consistently costs 1 unit (6 KB โ†’ 2 ร— 4 KB blocks โ†’ halved).
  • Transactional reads and writes cost two units per item (prepare and commit).
  • Query charges by the total size of items read (summed, then rounded up to 4 KB), not per item โ€” another reason to keep items small and collections tight.

Modes

On-demandProvisioned
You pay forEach read/write request unitCapacity per hour, used or not
Price, us-east-1 (checked 2026-11-18)USD 0.625 per million write request units; USD 0.125 per million read request unitsPer WCU-hour and RCU-hour โš  VERIFY current hourly rates on the pricing page
ScalingInstant within limits; you can set a maximum throughput to cap costAuto scaling follows CloudWatch metrics with a delay
Best forNew, spiky or unpredictable workloads; most dev/testSteady, well-understood traffic where you can commit (reserved capacity available)
Free tierNot covered by the always-free 25 WCU/25 RCU25 WCU and 25 RCU per Region per month are free

Storage (Standard table class) is USD 0.25 per GB-month in us-east-1; the first 25 GB per Region are free. A Standard-Infrequent Access table class lowers storage price for tables where storage dominates (old transaction history), at a higher request price.

Worked example. Harbourline posts 3 million transactions a day (1 KB each, one write each) and serves 14 million "last 50 transactions" queries a day, each reading about 25 KB eventually consistently (25 KB rounds up to 7 blocks of 4 KB; eventual consistency halves it to 3.5 read units).

  • Writes: 3 M ร— 30 days = 90 M write units โ‰ˆ USD 56/month.
  • Reads: 14 M ร— 3.5 ร— 30 = 1,470 M read units โ‰ˆ USD 184/month.
  • Storage: 3 M ร— 1 KB ร— 365 days โ‰ˆ 1.1 TB/year โ†’ about USD 275/month by year end.

Storage overtakes request cost within a year. That is why history should move to S3 (lesson 14) and why TTL (lesson 11) matters.

Single-table design for Harbourline

Step 1 โ€” write the access patterns first

#Access patternFrequencyConsistency
AP1Get customer profile by customer_idHighEventual OK
AP2List a customer's accountsHighEventual OK
AP3Get account (balance, status) by account_idVery highStrong before moving money
AP4Latest N transactions for an account, newest firstVery highEventual OK
AP5Transactions for an account between two booking datesMediumEventual OK
AP6Find account by IBAN (incoming payment)HighEventual OK
AP7Sum of a day's transactions for all accountsDailyNot in DynamoDB โ€” export to S3 and use Athena

AP7 is deliberately rejected. Writing it down is as important as writing down the patterns you support.

Step 2 โ€” design keys

EntityPKSKOther attributesServes
CustomerCUS#CUS-00012345PROFILEfirst_name, last_name, kyc_status, risk_ratingAP1
Customer โ†’ account linkCUS#CUS-00012345ACC#ACC-0000000001product, currency, statusAP2
AccountACC#ACC-0000000001PROFILEiban, currency, balance, status, GSI1PK = IBAN#GBโ€ฆ, GSI1SK = ACC#โ€ฆAP3, AP6
TransactionACC#ACC-0000000001TX#2026-11-18#019a3c5e-โ€ฆamount, type, channel, counterparty, statusAP4, AP5

Notes on the choices:

  • Prefixes (CUS#, ACC#, TX#) make keys self-describing and let different entity types share a table without collisions.
  • The transaction sort key starts with the booking date (YYYY-MM-DD) so a BETWEEN on TX#2026-11-01 and TX#2026-11-30~ answers AP5; the UUID v7 suffix keeps keys unique and time-ordered within a day.
  • ScanIndexForward = false returns newest first for AP4.
  • The account PROFILE item and its transactions share a partition key. Sort keys compare as UTF-8 bytes, so PROFILE sorts before every TX#โ€ฆ key (P comes before T). A newest-first query on the whole collection therefore returns the transactions first and the profile last. If one screen needs "header plus latest 50" in a single call, give the profile a key that sorts after the transactions (for example ~PROFILE), so a newest-first query returns the profile first, then the latest transactions. Otherwise, issue a GetItem for the profile alongside a Query with begins_with(SK, "TX#"). This lesson keeps them as two calls for clarity.
  • The account link item under the customer duplicates product and currency. Denormalisation is normal in DynamoDB; you keep copies in sync with transactions or Streams.

Step 3 โ€” the GSI

GSI1 has partition key GSI1PK and sort key GSI1SK. Only account PROFILE items set these attributes, so the index is sparse: it contains only accounts. Querying GSI1PK = IBAN#GB33HRBLโ€ฆ returns the account in milliseconds.

GSIs are updated asynchronously and support only eventually consistent reads. That is fine for AP6: an IBAN does not change.

Step 4 โ€” check for hot partitions

A partition key serves at most 3,000 read and 1,000 write units per second. A normal current account will never get close. Harbourline's own settlement account โ€” which receives a ledger line for every card payment โ€” could. Options:

  • Write sharding: ACC#ACC-9000000001#07 with a suffix 00โ€“19 chosen at random or by hash; reads fan out across the shards.
  • Don't store per-transaction lines for the settlement account in DynamoDB; aggregate in a stream processor.

DynamoDB's adaptive capacity shifts throughput to busy partitions and can isolate a hot item onto its own partition, but it cannot exceed the per-partition limit for a single partition key value.

Step-by-step implementation

Run DynamoDB Local

docker run --name hl-m06-ddb -p 8000:8000 -d amazon/dynamodb-local:latest -jar DynamoDBLocal.jar -sharedDb -inMemory

-inMemory keeps data only while the container runs; -sharedDb makes all credentials and Regions see the same database.

Create the table with the CLI against Local

aws dynamodb create-table --endpoint-url http://localhost:8000 --region us-east-1 \
  --table-name hl-m06-banking \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
                          AttributeName=GSI1PK,AttributeType=S AttributeName=GSI1SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --global-secondary-indexes '[{"IndexName":"GSI1","KeySchema":[{"AttributeName":"GSI1PK","KeyType":"HASH"},{"AttributeName":"GSI1SK","KeyType":"RANGE"}],"Projection":{"ProjectionType":"ALL"}}]' \
  --billing-mode PAY_PER_REQUEST

DynamoDB Local ignores credentials, but the CLI still needs some โ€” your SSO profile or dummy environment variables work.

Seed and query with the .NET app

Create the console project from the Complete code section, then run dotnet run. It writes one customer, two accounts and 120 transactions, then answers AP1โ€“AP6.

Inspect the data

aws dynamodb query --endpoint-url http://localhost:8000 --region us-east-1 --table-name hl-m06-banking \
  --key-condition-expression "PK = :pk AND begins_with(SK, :tx)" \
  --expression-attribute-values '{":pk":{"S":"ACC#ACC-0000000001"},":tx":{"S":"TX#"}}' \
  --no-scan-index-forward --max-items 5

Optional: repeat in AWS

Point the app at the real service by removing the ServiceURL override (set DDB_LOCAL=false), create the table with the CDK or Terraform below, run the app, then delete the table.

AWS Console instructions

  1. Console โ†’ DynamoDB โ†’ Tables โ†’ Create table.
  2. Table name hl-m06-banking; partition key PK (String); sort key SK (String).
  3. Table settings โ†’ Customize settings. Capacity mode On-demand. Table class DynamoDB Standard.
  4. Secondary indexes โ†’ Create global index: partition key GSI1PK, sort key GSI1SK, projection All.
  5. Encryption at rest: choose AWS managed key for the lab, or a customer managed key in production.
  6. Deletion protection: turn it on for anything except throwaway labs.
  7. Add tags Project=cea-lab, Lab=m06-ddb, Environment=learn, Owner=<you>. Create table.
  8. Use Explore items to run a query on PK = ACC#ACC-0000000001 with sort key begins with TX#, then switch the Sort descending option.

AWS CLI

# Create the table in AWS (on-demand, point-in-time recovery enabled afterwards).
aws dynamodb create-table --table-name hl-m06-banking \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
                          AttributeName=GSI1PK,AttributeType=S AttributeName=GSI1SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --global-secondary-indexes '[{"IndexName":"GSI1","KeySchema":[{"AttributeName":"GSI1PK","KeyType":"HASH"},{"AttributeName":"GSI1SK","KeyType":"RANGE"}],"Projection":{"ProjectionType":"ALL"}}]' \
  --billing-mode PAY_PER_REQUEST \
  --tags Key=Project,Value=cea-lab Key=Lab,Value=m06-ddb Key=Environment,Value=learn \
  --profile learn-sandbox --region us-east-1

# Wait until ACTIVE.
aws dynamodb wait table-exists --table-name hl-m06-banking --profile learn-sandbox --region us-east-1

# Turn on point-in-time recovery (charged per GB-month; skip for a short lab if you prefer).
aws dynamodb update-continuous-backups --table-name hl-m06-banking \
  --point-in-time-recovery-specification PointInTimeRecoveryEnabled=true \
  --profile learn-sandbox --region us-east-1

# Find an account by IBAN through the GSI.
aws dynamodb query --table-name hl-m06-banking --index-name GSI1 \
  --key-condition-expression "GSI1PK = :iban" \
  --expression-attribute-values '{":iban":{"S":"IBAN#GB33HRBL20005512345678"}}' \
  --profile learn-sandbox --region us-east-1

# See consumed capacity for a query, to check your cost model.
aws dynamodb query --table-name hl-m06-banking \
  --key-condition-expression "PK = :pk AND begins_with(SK, :tx)" \
  --expression-attribute-values '{":pk":{"S":"ACC#ACC-0000000001"},":tx":{"S":"TX#"}}' \
  --no-scan-index-forward --limit 50 --return-consumed-capacity TOTAL \
  --profile learn-sandbox --region us-east-1

Infrastructure as Code

BankingTableStack.cs
using Amazon.CDK;
using Amazon.CDK.AWS.DynamoDB;
using Attribute = Amazon.CDK.AWS.DynamoDB.Attribute; // avoids CS0104 with System.Attribute when ImplicitUsings is on
using Amazon.CDK.AWS.KMS;
using Constructs;

namespace Harbourline.Infra;

public sealed class BankingTableStack : Stack
{
    public TableV2 Table { get; }

    public BankingTableStack(Construct scope, string id, IStackProps? props = null) : base(scope, id, props)
    {
        var key = new Key(this, "TableKey", new KeyProps
        {
            Alias = "alias/hl-m06-banking",
            EnableKeyRotation = true,
            RemovalPolicy = RemovalPolicy.DESTROY // lab only; RETAIN in production
        });

        Table = new TableV2(this, "BankingTable", new TablePropsV2
        {
            TableName = "hl-m06-banking",
            PartitionKey = new Attribute { Name = "PK", Type = AttributeType.STRING },
            SortKey = new Attribute { Name = "SK", Type = AttributeType.STRING },
            Billing = Billing.OnDemand(),
            Encryption = TableEncryptionV2.CustomerManagedKey(key),
            PointInTimeRecoverySpecification = new PointInTimeRecoverySpecification { PointInTimeRecoveryEnabled = true },
            DeletionProtection = false, // lab only; true in production
            RemovalPolicy = RemovalPolicy.DESTROY,
            GlobalSecondaryIndexes = new[]
            {
                new GlobalSecondaryIndexPropsV2
                {
                    IndexName = "GSI1",
                    PartitionKey = new Attribute { Name = "GSI1PK", Type = AttributeType.STRING },
                    SortKey = new Attribute { Name = "GSI1SK", Type = AttributeType.STRING },
                    ProjectionType = ProjectionType.ALL
                }
            }
        });

        Tags.SetTag("Project", "cea-lab");
        Tags.SetTag("Lab", "m06-ddb");
        Tags.SetTag("Environment", "learn");
    }
}

TableV2 is the current CDK construct for DynamoDB tables (it also supports global table replicas). Grant access with Table.GrantReadWriteData(role) rather than hand-writing dynamodb:*.

Complete code

Harbourline.Accounts.DynamoDb.csproj
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <RootNamespace>Harbourline.Accounts.DynamoDb</RootNamespace>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="AWSSDK.DynamoDBv2" Version="4.1.0.2" />
  </ItemGroup>
</Project>
BankingTable.cs
using System.Globalization;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;

namespace Harbourline.Accounts.DynamoDb;

public sealed record Account(string AccountId, string CustomerId, string Iban, string Currency, string Product, string Status, decimal Balance);
public sealed record Transaction(string TransactionId, string AccountId, DateOnly BookingDate, decimal Amount, string Currency, string Type, string Channel, string CounterpartyName, string Status);
public sealed record Page<T>(IReadOnlyList<T> Items, string? NextToken);

public sealed class BankingTable(IAmazonDynamoDB ddb, string tableName = "hl-m06-banking")
{
    private static readonly CultureInfo Inv = CultureInfo.InvariantCulture;

    // ---------- Writes ----------

    public Task PutCustomerAsync(string customerId, string firstName, string lastName, string kycStatus, CancellationToken ct) =>
        ddb.PutItemAsync(new PutItemRequest
        {
            TableName = tableName,
            Item = new Dictionary<string, AttributeValue>
            {
                ["PK"] = S($"CUS#{customerId}"),
                ["SK"] = S("PROFILE"),
                ["entity"] = S("customer"),
                ["customer_id"] = S(customerId),
                ["first_name"] = S(firstName),
                ["last_name"] = S(lastName),
                ["kyc_status"] = S(kycStatus),
                ["created_at"] = S(DateTimeOffset.UtcNow.ToString("O", Inv))
            }
        }, ct);

    public async Task PutAccountAsync(Account a, CancellationToken ct)
    {
        // Two items: the account itself, and a link item under the customer for AP2.
        await ddb.BatchWriteItemAsync(new BatchWriteItemRequest
        {
            RequestItems = new Dictionary<string, List<WriteRequest>>
            {
                [tableName] =
                [
                    new WriteRequest(new PutRequest(new Dictionary<string, AttributeValue>
                    {
                        ["PK"] = S($"ACC#{a.AccountId}"),
                        ["SK"] = S("PROFILE"),
                        ["GSI1PK"] = S($"IBAN#{a.Iban}"),
                        ["GSI1SK"] = S($"ACC#{a.AccountId}"),
                        ["entity"] = S("account"),
                        ["account_id"] = S(a.AccountId),
                        ["customer_id"] = S(a.CustomerId),
                        ["iban"] = S(a.Iban),
                        ["currency"] = S(a.Currency),
                        ["product"] = S(a.Product),
                        ["status"] = S(a.Status),
                        ["balance"] = N(a.Balance)
                    })),
                    new WriteRequest(new PutRequest(new Dictionary<string, AttributeValue>
                    {
                        ["PK"] = S($"CUS#{a.CustomerId}"),
                        ["SK"] = S($"ACC#{a.AccountId}"),
                        ["entity"] = S("customer_account"),
                        ["account_id"] = S(a.AccountId),
                        ["product"] = S(a.Product),
                        ["currency"] = S(a.Currency),
                        ["status"] = S(a.Status)
                    }))
                ]
            }
        }, ct);
    }

    public Task PutTransactionAsync(Transaction t, CancellationToken ct) =>
        ddb.PutItemAsync(new PutItemRequest
        {
            TableName = tableName,
            Item = new Dictionary<string, AttributeValue>
            {
                ["PK"] = S($"ACC#{t.AccountId}"),
                ["SK"] = S($"TX#{t.BookingDate:yyyy-MM-dd}#{t.TransactionId}"),
                ["entity"] = S("transaction"),
                ["transaction_id"] = S(t.TransactionId),
                ["booking_date"] = S(t.BookingDate.ToString("yyyy-MM-dd", Inv)),
                ["amount"] = N(t.Amount),
                ["currency"] = S(t.Currency),
                ["type"] = S(t.Type),
                ["channel"] = S(t.Channel),
                ["counterparty_name"] = S(t.CounterpartyName),
                ["status"] = S(t.Status)
            },
            // Never silently overwrite a posted transaction.
            ConditionExpression = "attribute_not_exists(PK)"
        }, ct);

    // ---------- Reads ----------

    // AP3: strongly consistent when the caller is about to move money.
    public async Task<Account?> GetAccountAsync(string accountId, bool consistent, CancellationToken ct)
    {
        var resp = await ddb.GetItemAsync(new GetItemRequest
        {
            TableName = tableName,
            Key = Key($"ACC#{accountId}", "PROFILE"),
            ConsistentRead = consistent
        }, ct);
        return resp.Item is { Count: > 0 } item ? ToAccount(item) : null;
    }

    // AP2: all accounts for a customer โ€” one Query on the customer's item collection.
    public async Task<IReadOnlyList<string>> ListAccountIdsAsync(string customerId, CancellationToken ct)
    {
        var resp = await ddb.QueryAsync(new QueryRequest
        {
            TableName = tableName,
            KeyConditionExpression = "PK = :pk AND begins_with(SK, :acc)",
            ExpressionAttributeValues = new Dictionary<string, AttributeValue>
            {
                [":pk"] = S($"CUS#{customerId}"),
                [":acc"] = S("ACC#")
            },
            ProjectionExpression = "account_id"
        }, ct);
        return (resp.Items ?? []).Select(i => i["account_id"].S).ToList();
    }

    // AP4 + AP5: newest-first page of transactions, optionally within a date range.
    public async Task<Page<Transaction>> GetTransactionsAsync(string accountId, DateOnly? from, DateOnly? to, int pageSize, string? nextToken, CancellationToken ct)
    {
        var values = new Dictionary<string, AttributeValue> { [":pk"] = S($"ACC#{accountId}") };
        string keyCondition;
        if (from is not null && to is not null)
        {
            keyCondition = "PK = :pk AND SK BETWEEN :lo AND :hi";
            values[":lo"] = S($"TX#{from:yyyy-MM-dd}");
            values[":hi"] = S($"TX#{to:yyyy-MM-dd}~"); // '~' sorts after any '#uuid' suffix
        }
        else
        {
            keyCondition = "PK = :pk AND begins_with(SK, :tx)";
            values[":tx"] = S("TX#");
        }

        var resp = await ddb.QueryAsync(new QueryRequest
        {
            TableName = tableName,
            KeyConditionExpression = keyCondition,
            ExpressionAttributeValues = values,
            ScanIndexForward = false, // newest first
            Limit = pageSize,
            ExclusiveStartKey = PageToken.Decode(nextToken)
        }, ct);

        var items = (resp.Items ?? []).Select(ToTransaction).ToList();
        return new Page<Transaction>(items, PageToken.Encode(resp.LastEvaluatedKey));
    }

    // AP6: find an account by IBAN through the sparse GSI (eventually consistent only).
    public async Task<string?> FindAccountIdByIbanAsync(string iban, CancellationToken ct)
    {
        var resp = await ddb.QueryAsync(new QueryRequest
        {
            TableName = tableName,
            IndexName = "GSI1",
            KeyConditionExpression = "GSI1PK = :iban",
            ExpressionAttributeValues = new Dictionary<string, AttributeValue> { [":iban"] = S($"IBAN#{iban}") },
            Limit = 1
        }, ct);
        return resp.Items?.FirstOrDefault()?["account_id"].S;
    }

    // ---------- Mapping helpers ----------

    private static AttributeValue S(string value) => new() { S = value };
    // Money is stored as a DynamoDB Number built from the decimal's invariant string: no double rounding.
    private static AttributeValue N(decimal value) => new() { N = value.ToString(Inv) };
    private static Dictionary<string, AttributeValue> Key(string pk, string sk) => new() { ["PK"] = S(pk), ["SK"] = S(sk) };

    private static Account ToAccount(Dictionary<string, AttributeValue> i) => new(
        i["account_id"].S, i["customer_id"].S, i["iban"].S, i["currency"].S, i["product"].S, i["status"].S,
        decimal.Parse(i["balance"].N, Inv));

    private static Transaction ToTransaction(Dictionary<string, AttributeValue> i) => new(
        i["transaction_id"].S, i["PK"].S["ACC#".Length..], DateOnly.ParseExact(i["booking_date"].S, "yyyy-MM-dd", Inv),
        decimal.Parse(i["amount"].N, Inv), i["currency"].S, i["type"].S, i["channel"].S, i["counterparty_name"].S, i["status"].S);
}
PageToken.cs
using System.Text;
using System.Text.Json;
using Amazon.DynamoDBv2.Model;

namespace Harbourline.Accounts.DynamoDb;

// Turns DynamoDB's LastEvaluatedKey into an opaque string for an API's "next" link, and back.
public static class PageToken
{
    public static string? Encode(Dictionary<string, AttributeValue>? lastKey)
    {
        if (lastKey is null || lastKey.Count == 0) return null;
        var flat = lastKey.ToDictionary(kv => kv.Key, kv => kv.Value.S); // all our key attributes are strings
        return Convert.ToBase64String(Encoding.UTF8.GetBytes(JsonSerializer.Serialize(flat)));
    }

    public static Dictionary<string, AttributeValue>? Decode(string? token)
    {
        if (string.IsNullOrEmpty(token)) return null;
        var flat = JsonSerializer.Deserialize<Dictionary<string, string>>(Encoding.UTF8.GetString(Convert.FromBase64String(token)))
                   ?? throw new FormatException("Invalid page token");
        return flat.ToDictionary(kv => kv.Key, kv => new AttributeValue { S = kv.Value });
    }
}
Program.cs
using Amazon;
using Amazon.DynamoDBv2;
using Amazon.Runtime;
using Harbourline.Accounts.DynamoDb;

var useLocal = !string.Equals(Environment.GetEnvironmentVariable("DDB_LOCAL"), "false", StringComparison.OrdinalIgnoreCase);

IAmazonDynamoDB ddb = useLocal
    // DynamoDB Local accepts any credentials; these are not secrets.
    ? new AmazonDynamoDBClient(new BasicAWSCredentials("local", "local"),
        new AmazonDynamoDBConfig { ServiceURL = "http://localhost:8000", AuthenticationRegion = "us-east-1" })
    // In AWS: default credential chain (SSO profile via AWS_PROFILE=learn-sandbox, or the task/function role).
    : new AmazonDynamoDBClient(RegionEndpoint.USEast1);

var table = new BankingTable(ddb);
var ct = CancellationToken.None;

// Seed: one customer, two accounts, 120 transactions over 60 days. All data is fictional.
await table.PutCustomerAsync("CUS-00012345", "Amelia", "Hart", "verified", ct);
await table.PutAccountAsync(new Account("ACC-0000000001", "CUS-00012345", "GB33HRBL20005512345678", "GBP", "current", "open", 1520.40m), ct);
await table.PutAccountAsync(new Account("ACC-0000000002", "CUS-00012345", "GB71HRBL20005587654321", "GBP", "savings", "open", 8200.00m), ct);

var rng = new Random(20261117);
var start = new DateOnly(2026, 9, 20);
for (var i = 0; i < 120; i++)
{
    var date = start.AddDays(i / 2);
    var amount = -Math.Round((decimal)rng.Next(150, 9000) / 100m, 2);
    await table.PutTransactionAsync(new Transaction(Guid.CreateVersion7().ToString(), "ACC-0000000001", date,
        amount, "GBP", "card_payment", "card", $"Merchant {rng.Next(1, 40):D2}", "booked"), ct);
}

// AP2
Console.WriteLine($"Accounts: {string.Join(", ", await table.ListAccountIdsAsync("CUS-00012345", ct))}");

// AP3 (strong read, as before a payment)
var acc = await table.GetAccountAsync("ACC-0000000001", consistent: true, ct);
Console.WriteLine($"Balance: {acc?.Balance:0.00} {acc?.Currency}");

// AP4 with pagination
var page1 = await table.GetTransactionsAsync("ACC-0000000001", null, null, pageSize: 5, nextToken: null, ct);
Console.WriteLine("Latest 5:");
foreach (var t in page1.Items) Console.WriteLine($"  {t.BookingDate} {t.Amount,9:0.00} {t.CounterpartyName}");
var page2 = await table.GetTransactionsAsync("ACC-0000000001", null, null, 5, page1.NextToken, ct);
Console.WriteLine($"Next page starts {page2.Items.FirstOrDefault()?.BookingDate}");

// AP5
var nov = await table.GetTransactionsAsync("ACC-0000000001", new DateOnly(2026, 11, 1), new DateOnly(2026, 11, 7), 100, null, ct);
Console.WriteLine($"1โ€“7 Nov: {nov.Items.Count} transactions, total {nov.Items.Sum(t => t.Amount):0.00}");

// AP6
Console.WriteLine($"IBAN lookup: {await table.FindAccountIdByIbanAsync("GB71HRBL20005587654321", ct)}");

Expected output (values vary only in merchant names):

Accounts: ACC-0000000001, ACC-0000000002
Balance: 1520.40 GBP
Latest 5:
  2026-11-18    -43.17 Merchant 12
  ...
Next page starts 2026-11-16
1โ€“7 Nov: 14 transactions, total -641.92
IBAN lookup: ACC-0000000002

In an ASP.NET Core API you would register the client with builder.Services.AddAWSService<IAmazonDynamoDB>() (package AWSSDK.Extensions.NETCore.Setup) and inject BankingTable as a singleton.

Code explained line by line

  1. IAmazonDynamoDB ddb โ€” the low-level client interface. Injecting the interface makes unit tests easy (mock it, or point at DynamoDB Local).
  2. ServiceURL = "http://localhost:8000" with AuthenticationRegion โ€” redirects the client to DynamoDB Local; the region is still needed to sign requests.
  3. S(...) and N(...) โ€” DynamoDB's wire format is typed: S string, N number (sent as a string), BOOL, M map, L list and so on.
  4. N(decimal) uses ToString(CultureInfo.InvariantCulture) โ€” DynamoDB numbers keep up to 38 significant digits exactly, so decimal round-trips without the floating-point errors you would get from double. On a UK machine the invariant culture also prevents a comma decimal separator sneaking in on another locale.
  5. BatchWriteItemAsync with two PutRequests โ€” one network call for the account and its customer link item. A batch is not atomic; the next lesson uses TransactWriteItems when both must succeed together.
  6. ConditionExpression = "attribute_not_exists(PK)" โ€” the put fails if an item with this exact key already exists. For transactions that prevents accidental overwrite.
  7. ConsistentRead = consistent โ€” strong read for AP3 when money is about to move; eventual elsewhere.
  8. resp.Item is { Count: > 0 } โ€” when no item exists, SDK v4 may return null (v3 returned an empty dictionary); this pattern handles both.
  9. begins_with(SK, :acc) โ€” key condition on the sort key. Only =, <, <=, >, >=, BETWEEN and begins_with are allowed on sort keys.
  10. ProjectionExpression = "account_id" โ€” returns fewer bytes over the wire, but does not reduce read units: capacity is charged on the full item size read.
  11. SK BETWEEN :lo AND :hi with ~ appended to the upper bound โ€” ~ sorts after # and alphanumerics in ASCII, so every key on the last day is included.
  12. ScanIndexForward = false and Limit = pageSize โ€” newest first, one page. Limit caps items evaluated, not items returned after a filter.
  13. ExclusiveStartKey / LastEvaluatedKey โ€” DynamoDB's cursor. PageToken turns it into an opaque string for a REST API; in production, sign or encrypt it so clients cannot tamper with keys.
  14. IndexName = "GSI1" โ€” queries the sparse index. No ConsistentRead here: GSIs do not support it.
  15. Guid.CreateVersion7() โ€” .NET 9+ creates time-ordered UUID v7 values, matching the transaction_id convention.

Security considerations

โš  Learning shortcut โ€” not for production

The lab uses DynamoDB Local with dummy credentials and an AWS managed or lab KMS key with RemovalPolicy.DESTROY and no deletion protection. In production: a customer managed KMS key with a key policy restricted to the table's service and roles, deletion protection on, point-in-time recovery on, a gateway VPC endpoint, and an IAM policy scoped to the table ARN and its indexes.

A least-privilege policy for the Accounts API task role:

hl-m06-accounts-api-ddb-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadWriteBankingTable",
      "Effect": "Allow",
      "Action": ["dynamodb:GetItem", "dynamodb:Query", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:BatchWriteItem", "dynamodb:ConditionCheckItem"],
      "Resource": [
        "arn:aws:dynamodb:us-east-1:111122223333:table/hl-m06-banking",
        "arn:aws:dynamodb:us-east-1:111122223333:table/hl-m06-banking/index/GSI1"
      ],
      "Condition": { "StringEquals": { "aws:SourceVpce": "vpce-0a1b2c3d4e5f67890" } }
    }
  ]
}
  • No dynamodb:Scan, DeleteItem, DeleteTable or UpdateTable: the API never needs them. A missing Scan permission also stops an accidental full-table read in code review.
  • dynamodb:LeadingKeys can restrict a principal to items whose partition key matches a value โ€” for example, a per-customer role in a multi-tenant design.
  • Personal data (names, IBANs) in DynamoDB is still personal data under UK GDPR. Plan for erasure requests: with a single-table design, deleting a customer means deleting every item in several collections โ€” keep a documented procedure.
  • Keep personal data out of keys where you can (CUS#CUS-00012345, not CUS#amelia.hart@example.com): keys appear in CloudTrail data events, logs and metrics.

Banking use case

Harbourline moves the read side of the mobile home screen to DynamoDB while the ledger of record stays in Aurora PostgreSQL:

  • The Payments Service writes the ledger in Aurora. A change-data-capture feed (via the outbox table and an event) writes each booked transaction into hl-m06-banking as a TX# item.
  • The mobile API serves AP1โ€“AP6 from DynamoDB with p99 under 20 ms during payday peaks, and no longer competes with batch jobs.
  • Balances shown in the app carry an "as at" timestamp; the authoritative balance check before a payment still happens in Aurora (or with a strongly consistent DynamoDB read if DynamoDB becomes the system of record).
  • Old TX# items expire through TTL after 13 months; full history lives in the S3 data lake.

This is a CQRS read model โ€” a pattern you may know from .NET microservices โ€” with DynamoDB as the query store.

Common mistakes

  • One table per entity, then Scan with filters โ†’ it mirrors SQL Server โ†’ design from access patterns; use Query on keys; reserve Scan for exports and admin.
  • Using double for money โ†’ AttributeValue.N takes a string, so double.ToString() silently rounds โ†’ always format decimal with the invariant culture.
  • Expecting a FilterExpression to save capacity โ†’ filters run after items are read โ†’ put the selective condition in the key.
  • Low-cardinality partition keys (status=open, currency=GBP) โ†’ all items land on a few partitions โ†’ use high-cardinality keys; add write sharding for genuinely hot keys.
  • Forgetting pagination โ†’ code reads only the first 1 MB page โ†’ loop until LastEvaluatedKey is null, or expose a cursor.
  • Adding an LSI "just in case" โ†’ it can only be created with the table and caps each item collection at 10 GB โ†’ prefer GSIs.
  • Storing large blobs (statements PDFs) โ†’ items max 400 KB and you pay per KB on every read โ†’ store the file in S3 and the S3 key in DynamoDB.

Troubleshooting

SymptomLikely causeFix
ResourceNotFoundExceptionWrong table name, wrong Region, or Local vs AWS mix-upCheck ServiceURL, Region and the table name
ValidationException: One or more parameter values were invalid: Missing the key SKItem lacks the sort keyEvery item needs both key attributes
ValidationException: Query condition missed key schema elementKey condition does not use the partition key with =Every Query needs PK = :value
ProvisionedThroughputExceededException or ThrottlingExceptionHot partition, or provisioned capacity too low, or on-demand max throughput reachedCheck CloudWatch contributor insights for hot keys; shard the key; raise limits
Query returns fewer items than Limit with a filterLimit applies before the filterPaginate, or redesign the key
GSI query misses an item you just wroteGSI updates are asynchronousExpected; read the base table for read-after-write
ConditionalCheckFailedException on seed rerunattribute_not_exists(PK) prevented overwrite of existing transactionExpected on rerun with the same IDs; restart DynamoDB Local (-inMemory)
Unable to connect to localhost:8000Container not running or port in usedocker ps; change the host port and ServiceURL

Cost and cleanup

DynamoDB Local is free. In AWS, this lesson's table holds a few kilobytes; on-demand requests for the seed and queries cost a fraction of a cent, and storage is within the 25 GB always-free allowance. PITR is charged per GB-month (USD 0.20 per GB-month in us-east-1) โ€” negligible for kilobytes, but turn it off or delete the table afterwards. A customer managed KMS key costs about USD 1 per month (prorated) โ€” schedule its deletion.

# Local
docker rm -f hl-m06-ddb

# AWS
aws dynamodb delete-table --table-name hl-m06-banking --profile learn-sandbox --region us-east-1
aws dynamodb wait table-not-exists --table-name hl-m06-banking --profile learn-sandbox --region us-east-1
# If you created a CMK with CDK/Terraform, destroy the stack (cdk destroy / terraform destroy),
# which schedules the key for deletion after the waiting period.
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab \
  --query "ResourceTagMappingList[].ResourceARN" --profile learn-sandbox --region us-east-1

Exercises

  • ๐ŸŸข Guided: Run the app against DynamoDB Local. Then add AP8 "get a single transaction by transaction_id" without a Scan. Hint: you know the account in the API route.
  • ๐ŸŸก Challenge: Add AP9 "list all frozen accounts for the operations dashboard" with a sparse GSI that only contains frozen accounts. Show the item changes when an account is frozen and unfrozen.
  • ๐Ÿ”ด Live problem: The product owner wants "search transactions by merchant name, any account, any date" for the customer service team, and suggests adding a GSI on counterparty_name. Evaluate the request and propose a design.

Assignment

Write docs/dynamodb-access-patterns.md for your portfolio: the access-pattern table, the key design table, one rejected pattern with the reason, the capacity estimate for your numbers, and the IAM policy. Include the console app and a short README for running it against DynamoDB Local.

Solutions

Knowledge check

Interview questions

  • "How do you design a DynamoDB table?" โ€” Start from access patterns with frequency and consistency needs; design partition and sort keys so each pattern is a GetItem or Query; add sparse GSIs for alternates; check for hot keys; write down rejected patterns and where they go instead.
  • "Single-table or multiple tables?" โ€” Single-table when entities are queried together (account plus its transactions) and you want one item collection per query. Multiple tables when entities have different lifecycles, access controls, streams or backup needs. It is a trade-off, not a rule.
  • "How do you store money in DynamoDB?" โ€” As a Number attribute serialised from decimal with the invariant culture, or as integer minor units (pence). Never double.
  • "What causes throttling on on-demand tables?" โ€” Hot partition keys exceeding per-partition limits, sudden traffic far above previous peaks, or a configured maximum throughput.

Certification practice

Completion checklist

  • I can list access patterns before designing keys
  • I can calculate read and write units for an item size and consistency choice
  • I ran the console app against DynamoDB Local and understood each query
  • I can explain when on-demand vs provisioned is the better choice
  • I removed the local container and any AWS table and key I created

Key takeaways

  • DynamoDB is fast because every query starts with an exact partition key; design keys from written access patterns.
  • Single-table design groups related items into item collections so one Query answers one screen.
  • Use sparse GSIs for alternate lookups; GSIs are eventually consistent; avoid LSIs unless you need strong reads on an alternate sort key.
  • On-demand is the sensible default; storage cost grows quietly โ€” plan TTL and archiving early.
  • Store money as decimal serialised to a DynamoDB Number, never double; keep personal data out of keys.

Further reading

Independent learning resource โ€” not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page