Announcing Laravel Support and PHP PDO Interface

Laravel continues to grow rapidly in popularity, is the de-facto framework for PHP, and many people have been keen to use it with Turso. While it has technically already been available to use with Turso through community drivers, we’re excited to launch official Laravel support with libsql-laravel, our new open-source SDK.

Until now, the most popular community drivers used PHP extensions to support Laravel. Many developers told us that dealing with custom PHP extensions was creating unnecessary setup complexity, both locally and in production.

Our new Laravel adapter builds on our PHP SDK released in late 2024, eliminating these friction points.

Both the Laravel and PHP SDKs are in technical preview. Please try them out and share your feedback, or report issues in our Discord community.

#What This Means for Laravel Developers

The new libsql-laravel adapter seamlessly integrates with Laravel's database layer with:

• Drop-in SQLite Compatibility

  • The new Laravel adapter leverages Laravel’s existing SQLite connection, meaning your existing SQLite-compatible code and migrations will work with Turso without modification.

• Simple Configuration

  • You only need to update your database.php config with your Turso database URL and auth token. No need to manage complex PHP extension configuration.

• Native Laravel Connections

  • The adapter integrates directly with Laravel’s connection factory and database manager, ensuring proper connection pooling and management.

#Getting Started with Laravel

Begin by installing the turso/libsql-laravel package using Composer:

composer require turso/libsql-laravel

Now inside your Laravel application’s config/database.php:

<?php

use Illuminate\Support\Str;

return [
    "default" => env("DB_CONNECTION", "libsql"),

    "connections" => [
        "libsql" => [
            "driver" => env("DB_CONNECTION", "libsql"),
            "database" => database_path("dev.db"),
        ],

        // ...
    ],
];

Inside .env set the DB_CONNECTION to libsql:

DB_CONNECTION=libsql

The configuration above uses a local SQLite file with the libSQL adapter. To use Turso, update your config/database.php and replace database with url and password properties:

"connections" => [
  "libsql" => [
    "driver" => env("DB_CONNECTION", "libsql"),
    "url" => env("TURSO_DATABASE_URL"),
    "password" => env("TURSO_AUTH_TOKEN"),
  ],

  // ...
]

Then update .env with your credentials:

TURSO_DATABASE_URL=libsql://...
TURSO_AUTH_TOKEN=...

Embedded Replicas are NOT yet supported on AWS — make sure to use either database, or url and password properties, but not all three.

The libsql-laravel adapter extends Laravel’s SQLiteConnection to ensure compatibility with Laravel’s query builder, Eloquent ORM, and database migrations. This means you can use familiar Laravel database features like:

• Eloquent models and relationships
• Database migrations and seeders
• Query builder operations
• Database transactions

The technical preview focuses on providing a native Laravel experience while leveraging Turso. We encourage developers to test it with their existing Laravel applications, and share feedback on Discord.

Make sure to enable FFI in your PHP configuration to use the new Laravel adapter.

#Working with Vector Embeddings

Let's walk through creating a simple movie recommendation system using Turso's vector embedding support.

#Step 1: Create the Model and Migration

First, let's create our Movie model and corresponding migration:

php artisan make:model Movie -m

This command creates both the Movie model and a migration file for the movies table.

#Step 2: Define the Movie Model

Edit the newly created app/Models/Movie.php:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Libsql\Laravel\VectorCast;

class Movie extends Model
{
    protected $fillable = ["title", "genre", "release_year", "plot_embedding"];

    protected $casts = [
        "release_year" => "integer",
        "plot_embedding" => VectorCast::class,
    ];
}

#Step 3: Set Up the Migration

Edit the migrations file xxxx_xx_xx_create_movies_table.php:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create("movies", function (Blueprint $table) {
            $table->id();
            $table->string("title");
            $table->string("genre");
            $table->integer("release_year");
            $table->vector("plot_embedding", 5); // 5-dimensional vector
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists("movies");
    }
};

#Step 4: Create a Vector Index

Now, let's create a new migration for the vector index:

php artisan make:migration add_vector_index_to_movies_table

Edit the newly created migration file:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::table("movies", function (Blueprint $table) {
            $table->vectorIndex("plot_embedding", "movies_plot_embedding_idx");
        });
    }

    public function down(): void
    {
        Schema::table("movies", function (Blueprint $table) {
            $table->dropIndex("movies_plot_embedding_idx");
        });
    }
};

#Step 5: Run Migrations

Apply these changes to your database:

php artisan migrate

#Using the Model

Now you can use the Movie model in your application.

For example, to create a new movie:

$movie = Movie::create([
    "title" => "The Matrix",
    "genre" => "Sci-Fi",
    "release_year" => 1999,
    "plot_embedding" => [0.1, 0.2, 0.3, 0.4, 0.5],
]);

And to find similar movies:

$queryVector = [0.15, 0.25, 0.35, 0.45, 0.55];

$similarMovies = Movie::query()
    ->nearest('movies_plot_embedding_idx', $queryVector, 5)
    ->get();

foreach ($similarMovies as $movie) {
    echo "{$movie->title} ({$movie->release_year})\n";
}

This setup allows you to store movie data along with plot embeddings and perform similarity searches using Turso's vector capabilities, all seamlessly integrated with Laravel's Eloquent ORM.

#PHP PDO Interface

We’re excited to announce the release of the PHP PDO interface for Turso. This new interface allows you to use Turso with any PHP application that supports PDO, including Laravel.

#Feedback

Our SDK roadmap, fixes and features are driven by your feedback. Join us on Discord in the #libsql-php channel to share any thoughts and feedback.