Laravel Surrealdb Laravel Package

Getting Started

1. Install the package (pre-release only at v0.3.0):

   composer require boone-studios/laravel-surrealdb:^0.3.0
   

   Pin the exact pre-release version in composer.json — this is explicitly a testing pre-release with no stability guarantees.

2. Publish the config (if the package provides one):

   php artisan vendor:publish --provider="BooneStudios\SurrealDB\SurrealDBServiceProvider"
   

   Review config/surrealdb.php first. The important values are the SurrealDB endpoint (HTTP or WebSocket URL), namespace, database, and credentials.

3. Add the connection to config/database.php and environment variables:

   'surrealdb' => [
       'driver' => 'surrealdb',
       'url' => env('SURREALDB_URL', 'http://127.0.0.1:8000'),
       'namespace' => env('SURREALDB_NAMESPACE', 'laravel'),
       'database' => env('SURREALDB_DATABASE', 'app'),
       'username' => env('SURREALDB_USERNAME', 'root'),
       'password' => env('SURREALDB_PASSWORD', 'root'),
   ],
   

4. First use case — smoke test the connection:

   use Illuminate\Support\Facades\DB;
   
   $result = DB::connection('surrealdb')->select('SELECT * FROM user LIMIT 10;');
   

   If DB::connection('surrealdb') fails, check that the service provider is auto-discovered and that the driver name matches the package’s expected key.

5. Where to look next: the package README, the service provider, and any facade or model base class shipped in src/. Since v0.3.0 is a pre-release, the README is the most reliable source for the current API surface.

Implementation Patterns

• Use Laravel’s database manager, not ad-hoc clients. Register SurrealDB as a normal connection so DB::connection('surrealdb'), DB::transaction(), and connection switching work consistently across the app.
• Prefer the package’s query builder / facade over raw DB::select. If the package exposes a builder or model abstraction, use it — particularly for parameter binding, since SurrealQL parameter syntax differs from SQL.
• Model pattern (if supported): extend the package’s model base class or apply its trait, then declare the table/collection name. Keep SurrealDB-specific logic in dedicated repositories or model methods rather than scattering raw SurrealQL through controllers.
• Connection per environment: define separate surrealdb connections for local, testing, and production, each pointing at different namespaces/databases. This aligns well with SurrealDB’s namespace/database isolation.
• Testing: use a dedicated test database and reset it in setUp() (or use RefreshDatabase if the package supports it). Avoid hitting a shared dev instance — SurrealDB namespaces make it cheap to create an isolated test one.
• Queues and jobs: because SurrealDB is not the default Laravel SQL driver, avoid assuming Eloquent relationships work across SQL and SurrealDB connections. Use explicit queries or the package’s abstraction inside jobs.
• Migrations: SurrealDB is schemaless. If the package provides migration commands, treat them as schema definitions (indexes, tables, permissions) rather than traditional SQL migrations. Otherwise keep SurrealQL schema files under version control and run them via artisan commands.
• Integration tip: wrap SurrealDB calls in a small service class so you can swap implementations and mock them in tests without touching the DB facade everywhere.

Gotchas and Tips

• v0.3.0 is a pre-release. The release notes state it is meant for testing. Do not ship it to production without a fallback plan, and expect breaking changes between 0.x releases. Pin the version and review the changelog on every bump.
• Laravel 11 support is new in v0.3.0. If you are on Laravel 10, verify the composer constraints still resolve; the dependency upgrade may have raised minimum PHP/Laravel versions.
• SurrealQL is not SQL. Query syntax, parameter placeholders, and result shapes differ. Check the package’s expected binding style before assuming ? placeholders work.
• Connection driver naming matters. A common failure is registering the config under one key (surrealdb) while the package expects another. Confirm the driver name in the package’s service provider.
• HTTP vs WebSocket transport. If the package supports both, HTTP is simpler for request/response; WebSocket may be needed for live queries. Match the transport to your use case and confirm both are configured correctly.
• Debugging: enable Laravel’s query log where the package supports it, and log the raw SurrealQL plus bound parameters. Connection-level errors (auth, namespace, database) often look like query errors.
• Extension points: look for a custom connection resolver or a SurrealDB facade binding in the service provider. Binding your own client or repository implementation there is the cleanest way to customize behavior without forking.
• No Eloquent guarantees. If the package does not provide an Eloquent-compatible model, do not assume hasMany, where, or relationship methods behave like SQL Eloquent. Use the package’s documented query interface instead.