Laravel Dynamodb Laravel Package

Product Decisions This Supports

Persistence-layer selection for new services. This package removes "we'd lose Eloquent and rewrite our data layer" from the DynamoDB column of the decision matrix. That reframes the choice as cost/latency/access-pattern trade-offs instead of a framework-ergonomics penalty — which is exactly the comparison a PM wants the team making.

Build vs. buy for the adapter layer. Attribute marshalling, GSI query construction, pagination, conditional writes, and batch operations are weeks of undifferentiated work plus permanent maintenance. Buying an MIT-licensed adapter is defensible if the abstraction is thin enough that we can fork or replace it.

Serverless / Vapor roadmap. DynamoDB is a Lambda-native datastore: no VPC-attached connection pool, no connection-limit cliff under burst scaling. If the roadmap includes per-request autoscaling or scale-to-zero, this package keeps the application layer unchanged while the infrastructure changes underneath.

Use cases this unlocks without a re-platform:

• Read-heavy catalogs, product/content lookups, and configuration/feature-flag stores.
• Session, cache, and queue backends for stateless app tiers.
• Append-only activity feeds, audit logs, and event/telemetry tables (high write volume, cheap retention).
• Multi-tenant SaaS with per-tenant partitioning — on-demand capacity keeps idle tenants near-zero cost.
• Prototypes expected to hit unpredictable spikes, where provisioned DB instances would be over- or under-sized.

Unit-economics and packaging decisions. On-demand capacity replaces instance-hours with request units, which changes COGS from a step function to a variable cost. That materially affects free-tier design, per-seat vs. usage-based pricing, and gross-margin modeling for a SaaS launch.

Incremental migration sequencing. Because the API stays Eloquent-shaped, one bounded context (e.g., the activity feed) can move to DynamoDB while the transactional core stays on Postgres. This makes "strangler-fig the monolith" a sequencing option rather than a rewrite project.

Time-to-market de-risking. Teams already fluent in Eloquent ship a DynamoDB-backed MVP without waiting on a DBA or a data-modeling specialist, which compresses the gap between "we need a database decision" and "we have a working service."

When to Consider This Package

Adopt when:

• Access patterns are known and enumerable before schema design. DynamoDB is query-by-design; this package does not (and cannot) fix a bad key design, so the prerequisite is a documented list of the top 5–10 queries.
• The team is Laravel-fluent and Eloquent is the actual productivity lever — model events, collections, factories, and the query builder all carry over.
• Deployment is serverless-first or highly elastic (Vapor, Lambda, container autoscaling), where a connection-pooled RDBMS is the scaling bottleneck.
• The workload is high-volume and low-complexity: point lookups, range scans on a partition key, a handful of GSIs, no joins.
• Volume is spiky or unpredictable, so pay-per-request beats provisioned instances on both cost and operational burden.
• You want a bounded-context escape hatch from a saturated monolith database without rewriting application code.
• You are willing to own a thin dependency: MIT, ~193 stars, a small maintainer base, and a release cadence that is current but not enterprise-backed. Audit it, pin versions, and wrap it behind your own repository interfaces.

Look elsewhere when:

• The query surface is unknown or evolving — ad-hoc reporting, flexible filtering, aggregations, joins. You will fight both the package and DynamoDB's item-size and scan-cost limits, and the workarounds get expensive fast.
• You need relational guarantees across entities: foreign keys, rich constraints, multi-table transactions.
• The team has no DynamoDB modeling experience. The Eloquent facade invites relational thinking, and the failure mode is a table redesign plus data migration — the most expensive class of mistake in this stack.
• Compliance or uptime obligations require a vendor with a support contract and SLA. AWS supports DynamoDB; nobody supports this adapter.
• You depend on ecosystem tooling that assumes SQL — admin panels (Nova, Filament), analytics/BI connectors, third-party packages with query builders. Verify each one before committing.
• Volume is low and steady. Managed Postgres or Aurora Serverless v2 will likely be cheaper, simpler, and better supported; DynamoDB's operational simplicity does not offset its modeling constraints at small scale.

Reasonable alternatives: raw AWS SDK calls behind a repository layer (more code, more control, no bus factor), or staying on Postgres/Aurora Serverless v2 with Laravel's first-party support.

How to Pitch It (Stakeholders)

For executives (30 seconds): "We can use DynamoDB — AWS's fully managed, serverless database — without giving up the Laravel codebase our team is already fast in. That removes the main reason we kept defaulting to managed SQL. It means we can choose the database on cost and scaling behavior rather than on framework familiarity, and we can do it one service at a time instead of a rewrite."

Business framing: variable cost instead of capacity planning; no DBA hire for the new service; faster time-to-market on the next launch; lower lock-in risk than a replatform, because the application code stays standard Laravel and the data layer is swappable per bounded context.

For engineering: you keep Eloquent models, the query builder, collections, and model events; the package handles attribute marshalling, GSI queries, and pagination. Caveats stated plainly: it is an adapter, not a relational emulator — access patterns must be designed up front, relationships and joins are limited, and the library is small (~193 stars, single-maintainer risk). Mitigations: pin versions, hide it behind internal repository interfaces, and validate the top access patterns in a spike before committing.

The ask: a 1–2 week spike putting one non-critical bounded context — an activity feed or session store — on DynamoDB via this package, benchmarked against the Postgres baseline on p99 latency, projected monthly cost at expected volume, and developer hours to first working feature. Decision gate at the end: proceed, expand scope, or revert with the abstraction intact.

Risks to name out loud: bus factor on a small OSS dependency; an AWS-specific skills gap on the team; and the cost of reversing a bad key design. Each has a concrete mitigation — repository abstraction, version pinning, an internal modeling review, and a raw-SDK exit plan — which is what makes this a reversible bet rather than a commitment.