Laravel Electricsql Laravel Package

Getting Started

Start by reading the package README and checking the v0.0.1 tag, since this is an initial release with likely minimal documentation. Install with composer require matfire/laravel-electricsql and look for a publishable config/service provider (php artisan vendor:publish --provider="Matfire\\ElectricSql\\ElectricSqlServiceProvider" or similar). Your first use case should be small: expose one Laravel-managed Postgres table to ElectricSQL so a client can sync it locally. Confirm your app uses Postgres with logical replication enabled (wal_level=logical), because ElectricSQL depends on it; this package will not work against MySQL/SQLite. Publish any migrations or config, define a single "shape" (ElectricSQL's term for a sync subscription), and verify end-to-end with a local ElectricSQL client before expanding.

Implementation Patterns

Treat the package as the Laravel-side bridge for defining and managing ElectricSQL shapes. A typical workflow: add a model/migration in Laravel, define a shape for that table (often in config or via a package-provided builder), run any package setup/artisan command, then point your client at the ElectricSQL sync service. Day-to-day, add shapes incrementally as features need offline/local-first data rather than syncing entire schemas. Use tenant-filtered shapes for multi-tenant apps, and keep shape definitions close to the models they expose. Integration tip: run ElectricSQL locally via Docker alongside your Laravel app early, so schema changes and replication behavior are tested before deployment. In CI, include a Postgres service with logical replication enabled and run package setup commands to catch config drift.

Gotchas and Tips

At v0.0.1, expect unstable APIs and incomplete docs: pin the exact version and re-test after every upgrade. ElectricSQL requires Postgres logical replication; missing wal_level=logical, insufficient replication slots, or long-running transactions will cause sync failures that look like application bugs. Watch replication slot disk usage and clean up unused slots. Config caching can hide package config changes, so clear config after publishing. Schema changes are the main operational risk: add columns carefully and verify shapes after migrations. For debugging, start with package artisan commands (status/setup commands if present), Postgres logs, and replication slot state before touching client code. Extension points are likely limited in this release; prefer publishing config and wrapping package calls in your own service classes so you can adapt when the API changes.