Laravel Aws Timestream Laravel Package

Getting Started

The package is a thin, Eloquent-flavoured wrapper around the AWS Timestream SDK. You get a Model base class, a query builder, and a config-driven connection to a single Timestream database. It is not a full Eloquent replacement — treat it as a structured client, not an ORM.

Minimal setup:

1. composer require norbybaru/laravel-aws-timestream (v1.0.0 requires Laravel 10/11/12 and PHP 8.2+).
2. Publish the config: php artisan vendor:publish --tag=timestream-config (or the service-provider tag — check the README for the exact tag). This drops config/timestream.php.
3. Set the environment: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, plus the Timestream database name (AWS_TIMESTREAM_DATABASE / the key in the published config). If you're on IAM roles / ECS / Lambda, omit the key pair and let the SDK resolve credentials.
4. Ensure the target database and table exist in Timestream. The package can create tables via its artisan command (timestream:create-table, see the README), but the database itself is usually provisioned via console/CLI/IaC.
5. Define a model:

namespace App\Models;

use NorbyBaru\AwsTimestream\Models\Model;

class PageView extends Model
{
    protected $table = 'page_views';
}

6. Write and read your first record through the model, e.g. PageView::create([...]) and PageView::query()->where(...)->get(). Confirm the exact dimension/measure keys against the README — the shape is Timestream-native (dimensions, measures, time, version), not your usual Eloquent columns.

First useful use case: application telemetry — page views, request durations, queue job timings, or IoT-style metrics — where you want an Eloquent-ish API without paying for a separate time-series service.

Implementation Patterns

Model = table. Each model maps to one Timestream table via $table. Keep models small; don't try to share a model across tables.

Respect the dimensions/measures split. Dimensions are indexed and filterable (low cardinality: user_id, route, status); measures are the payload (duration_ms, bytes). Put anything you'll WHERE on into dimensions, and anything you'll SELECT/aggregate into measures.

Write paths.

• Single writes are fine for low-throughput or event-driven code.
• For anything sustained, batch writes and stay under Timestream's 100 records per WriteRecords call limit. Chunk with collect($rows)->chunk(100) and dispatch to a queue.
• Prefer queue jobs for writes so request latency isn't coupled to AWS. Use retryUntil / tries and handle ThrottlingException with backoff.

Query patterns.

• Always constrain by time window (->where('time', '>=', ...)) — Timestream bills on bytes scanned, and unbounded scans get expensive fast.
• Use the builder's first() / get() for reads; use raw Timestream SQL only through the underlying client when the builder can't express an aggregation.
• For dashboards, run aggregate queries on a schedule and cache results; never issue ad-hoc Timestream queries from a web request path.

Testing.

• Bind a fake/mock Timestream client in the container in your test suite and assert on the calls your model makes. Don't hit AWS in CI.
• Because the API is thin, most of your logic (what to write, when to query) should live in services/jobs that are testable independently of the package.

Integration tips.

• Register models under a dedicated namespace (App\Models\Timestream\...) so they're visually distinct from Eloquent models.
• Use a single connection for all models; multiple databases are better handled with explicit client construction than with config gymnastics.
• Wrap multi-step writes in idempotent jobs (Timestream doesn't enforce uniqueness) — include a client-generated id dimension if you need dedup.

Gotchas and Tips

• Laravel 9 is dropped in v1.0.0. If you're still on L9, pin to ^0.4. If you're upgrading to v1.0.0, audit for anything relying on illuminate/* ^9 constraints across your dependency tree, not just this package.
• v1.0.0 is the first stable tag. The major bump aligns with the L9 drop and Laravel 12 support; there's no documented API breakage beyond that, but pin ^1.0 and read the changelog on each minor.
• IAM is the #1 source of "it doesn't work". You need timestream:DescribeEndpoints (easy to forget — it's called on every client init), timestream:WriteRecords, timestream:Select, and timestream:CreateTable if you use the artisan command. A minimal timestream:* policy is tempting but too broad; scope it.
• Region and endpoint discovery. Timestream uses per-region endpoints resolved via DescribeEndpoints. If AWS_DEFAULT_REGION is unset or wrong, you get confusing "endpoint not found" errors rather than auth errors.
• Query limitations. Timestream SQL has no joins, no subqueries in some contexts, no OR in dimension predicates, and hard limits on dimensions per record (~20) and result size. If you need relational behaviour, aggregate in Timestream and join in your app.
• Cost model. Billing is on bytes scanned, not rows returned. Narrow SELECT lists, filter aggressively on dimensions and time, and avoid SELECT * on wide tables. A runaway dashboard can cost real money.
• Eventual consistency. Writes land in the memory store; reads may briefly lag. Don't write-then-immediately-read in the same request and assume you'll see the row — assert via the write result or a short retry.
• Config caching. php artisan config:cache will freeze your env values. If you rotate AWS credentials or change the database name, run config:clear and redeploy.
• Larastan. v1.0.0 widens the nunomaduro/larastan constraint to ^1|^2|^3, so static analysis should work across Laravel 10/11/12 — if you were suppressing errors because of the old constraint, re-run PHPStan and drop the ignores.
• Extension points. The base model and builder are the seams to lean on: override the query builder or add traits for common write shapes (e.g. WritesMetrics) rather than copy-pasting dimension/measure arrays around. If you need multi-database or a non-default client, bind your own client instance in a service provider and inject it.
• Upgrade checklist from v0.4.0: confirm PHP 8.2+, confirm Laravel 10+, re-run vendor:publish diff on config/timestream.php, run your test suite against the mocked client, and validate a single write + read against a staging Timestream database before rolling to production.