README

A DuckDB driver for Laravel Eloquent ORM, allowing you to use DuckDB as your database in Laravel applications.

Requirements

PHP >= 8.2
Laravel >= 11.0
php-duckdb extension

Installation

Install the php-duckdb extension:

# Install the extension following the instructions from https://github.com/fnvoid64/php-duckdb

Install the package:

composer require gumphp/duckdb

Publish the configuration file:

php artisan vendor:publish --provider="GumPHP\\DuckDB\\DuckDBServiceProvider"

Add the service provider to your config/app.php:

'providers' => [
    // ...
    GumPHP\\DuckDB\\DuckDBServiceProvider::class,
],

Configuration

Add the following to your .env file:

DB_CONNECTION=duckdb
DB_DATABASE=/path/to/your/database.duckdb
DB_FOREIGN_KEYS=true
DB_THREADS=4
DB_MEMORY_LIMIT=1GB

Or update your config/database.php:

'connections' => [
    'duckdb' => [
        'driver' => 'duckdb',
        'url' => env('DB_URL'),
        'database' => env('DB_DATABASE', database_path('database.duckdb')),
        'prefix' => '',
        'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
        'threads' => env('DB_THREADS', null),
        'memory_limit' => env('DB_MEMORY_LIMIT', null),
    ],
],

Usage

Once configured, you can use DuckDB just like any other Laravel database:

Eloquent Models

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $table = 'users';
}

// Create a new user
$user = new User();
$user->name = 'John Doe';
$user->email = 'john@example.com';
$user->save();

// Find a user
$user = User::find(1);

// Query users
$users = User::where('active', true)->orderBy('name')->get();

Query Builder

// Using the DB facade
$users = DB::connection('duckdb')
    ->table('users')
    ->where('active', true)
    ->orderBy('name')
    ->get();

// Insert data
DB::connection('duckdb')
    ->table('users')
    ->insert([
        'name' => 'Jane Doe',
        'email' => 'jane@example.com',
        'created_at' => now(),
        'updated_at' => now(),
    ]);

// Update data
DB::connection('duckdb')
    ->table('users')
    ->where('id', 1)
    ->update(['name' => 'John Smith']);

Migrations

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

return new class extends Migration
{
    public function up()
    {
        Schema::connection('duckdb')->create('users', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('email')->unique();
            $table->boolean('active')->default(true);
            $table->timestamps();
        });
    }

    public function down()
    {
        Schema::connection('duckdb')->dropIfExists('users');
    }
};

DuckDB Manager

You can also use the DuckDB manager for a more convenient API:

use GumPHP\DuckDB\DuckDBManager;

// Get the manager instance
$duckdb = app(DuckDBManager::class);

// Execute a query
$results = $duckdb->query('SELECT * FROM users WHERE active = ?', [true]);

// Execute a raw query
$results = $duckdb->raw('SELECT COUNT(*) FROM users');

// Begin a transaction
$duckdb->transaction(function () {
    // Your transaction logic here
});

DuckDB Specific Features

Memory Configuration

You can configure DuckDB's memory usage:

DB_MEMORY_LIMIT=1GB

Thread Configuration

Configure the number of threads DuckDB should use:

DB_THREADS=4

Limitations

Some advanced Laravel features may not be fully supported due to DuckDB's limitations
Full-text search features are not available
Some complex query optimizations may not work as expected

Contributing

Please feel free to submit pull requests or create issues for bugs and feature requests.

License

This project is open-sourced software licensed under the MIT license.

gumphp / duckdb

Maintainers

Details