Laravel Dsql Laravel Package

Getting Started

laravel-dsql wires AWS Aurora DSQL into Laravel's database layer so you can use Eloquent, migrations, and query builder against a serverless, distributed Postgres-compatible cluster without hand-rolling connection logic.

Minimal steps:

1. composer require ayup-creative/laravel-dsql
2. Publish the config: php artisan vendor:publish --tag=dsql-config
3. Set the environment variables the package reads (typically DSQL_ENDPOINT, DSQL_REGION, and either DSQL_USER/DSQL_PASSWORD or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY for IAM auth).
4. Add a connection in config/database.php:

   'dsql' => [
       'driver' => 'dsql',
       'host'     => env('DSQL_ENDPOINT'),
       'region'   => env('DSQL_REGION', 'us-east-1'),
       'database' => env('DSQL_DATABASE', 'postgres'),
       'username' => env('DSQL_USER', 'admin'),
       // password resolved automatically via IAM if omitted
   ],
   

5. php artisan migrate --database=dsql

First use case: point a single read/write workload (e.g. a queue-backed job table, or a small Eloquent model like Order) at the dsql connection and run Order::create([...]). That validates auth, connection pooling, and DSQL's SQL dialect in one go before you commit anything larger to it.

Where to look first:

• config/dsql.php after publishing — it exposes the token provider and retry settings.
• The service provider — this is where the recursion guard added in v1.0.2 lives, and where the connection is registered.
• The driver class — it extends Laravel's Postgres connector, so any Postgres-specific behaviour you rely on flows through here.

Implementation Patterns

Explicit connection scoping. Don't override the default pgsql name. Keep dsql as a named connection and set protected $connection = 'dsql'; on the models that need it. This makes the DSQL surface auditable and lets you keep a local Postgres connection for tests.

Token-based IAM auth. Leave the password key unset and let the package generate a short-lived IAM auth token per connection. For long-lived processes, rely on the package's retry logic rather than caching tokens in your own code:

DB::connection('dsql')->reconnect();

Prefer this over manually re-instantiating PDO — the driver resets the token cleanly.

Migrations split. DSQL does not support everything schema: produces (notably foreign key constraints and some ALTER forms). Keep a database/migrations/dsql directory and run it with --path. In CI, run the same migrations against a local Postgres to catch anything DSQL will silently reject.

Read/write routing. For read-heavy endpoints, register a second connection (dsql_read) pointing at the same cluster; the package honours Laravel's read/write split in the connection config, so you can declare read hosts inside the single dsql entry and get query-level routing for free.

Queue and job tables. Because DSQL is serverless-friendly, pairing it with database cache or queue drivers is attractive — but do it explicitly with DB::connection('dsql') inside a custom cache store or queue connector class, so you don't globally change the connection.

Testing. Point your test suite at an in-memory SQLite or local Postgres via RefreshDatabase. Do not hit the real cluster in unit tests — DSQL's latency and IAM handshake will make the suite unusable.

Gotchas and Tips

Recursion guard (v1.0.2). The service provider now guards against recursive bootstrapping — this was a real footgun when something in the connection resolution path triggered another DSQL connection resolution (e.g. logging to a DSQL-backed cache store while connecting). If you were working around this with app()->resolving(...) tricks or by deferring bindings in a custom provider, remove those now — you likely don't need them.

Short-lived tokens. IAM auth tokens expire (typically ~15 minutes). Anything long-running — queue workers, Octane, scheduler loops — will eventually hit an expired token. The package handles reconnection, but only on the next query, so wrap jobs that idle for a long time so the failure surfaces early rather than mid-transaction.

Postgres dialect quirks. DSQL is Postgres-compatible but not Postgres. Foreign keys, SERIAL/auto-increment in some shapes, and CREATE INDEX CONCURRENTLY do not behave the same way. Test schema changes against a real cluster in staging, not just local Postgres.

No traditional sequences. Use UUIDs (HasUuids or HasUniqueStringIds on models) rather than auto-incrementing IDs. If a package you depend on assumes bigIncrements, it will break silently. Audit your dependencies' migration stubs.

Transaction limits. DSQL has stricter transaction size/time limits than a self-hosted Postgres. Bulk inserts (Model::insert() with thousands of rows) and long-running transactions should be chunked.

Pre-commit hooks (v1.0.2). The package moved to pre-commit for its own development. If you're contributing back, install pre-commit locally; if you're consuming, this has no runtime impact.

Config caching. The connection config includes a closure for the token provider in some setups — closures don't survive php artisan config:cache. If things work in local but fail after deploy, config:cache is the first suspect.

Extension points. The dsql connection is a standard Laravel connection underneath, so DB::connection('dsql')->listen(...) and custom QueryExecuted listeners work as expected. Use DB::listen() scoped to the connection to profile DSQL latency separately from other databases — it's the fastest way to notice if connection churn has crept in.