dynamodb

Laravel DynamoDB

Scope

Apply these rules whenever the project integrates with DynamoDB — via the baopham/laravel-dynamodb package, a DynamoDB-backed Eloquent model, a custom DynamoDB query builder, or the AWS SDK called directly from PHP.

Core Principle

• Every read must target a key. Scan is the slow, expensive default and must never be the access pattern for production code paths.
• Treat every change to a DynamoDB query builder, repository, or any code that issues DynamoDB requests as a place that may silently introduce a Scan.
• A missing partition key turns the call into a Scan even when a FilterExpression is present — filters run after the read and do not replace a key condition.

Required Access Patterns

• GetItem / BatchGetItem — single-item or known-keys reads.
• Query with a partition key (and optionally a sort key) — collection reads inside one partition.
• Query against a Global Secondary Index (GSI) — non-primary-key access patterns. Pass the index name to the query (->index('status-createdAt-index') with baopham/laravel-dynamodb; IndexName in QueryInput when calling the AWS SDK directly).
• Scan is allowed only for explicit, documented offline/admin tasks (one-off backfills, maintenance scripts) — see the Review Checklist below for the justification requirement.

Reject patterns that omit a key:

Model::all();                                  // full scan
Model::where('status', 'active')->get();      // scan if `status` is not the PK / GSI hash
Model::whereNotNull('email')->first();        // scan

Prefer patterns that target a key:

Model::find($id);                                                       // GetItem
Model::where('userId', $userId)->get();                                 // Query on PK
Model::index('status-createdAt-index')                                  // Query on GSI
    ->where('status', 'active')
    ->get();

Review Checklist

For every PR that touches DynamoDB code, reviewers must verify: