Download the PHP package filipefernandes/laravel-duckdb without Composer

Laravel DuckDB Driver

A production-ready Laravel database driver for DuckDB, powered by satur/duckdb-auto. This package allows you to query DuckDB databases using Laravel's powerful Query Builder for analytical (OLAP) workloads.

Requirements

• PHP 8.2+
• Laravel 10.0+ or 11.0+
• FFI Extension Enabled (ffi.enable=true or preload in php.ini)

[!WARNING] Production Notice: Enabling FFI globally (ffi.enable=true) can have security implications. It is recommended to use ffi.enable=preload in production environments and preload the necessary scripts if possible, or strictly control access to the server.

Installation

1. Install via Composer:

2. Configuration

Add the connection configuration to your config/database.php file:

Auto-Installer

This package automatically downloads and installs the DuckDB native binary and FFI header when your application boots — no manual setup required.

On first boot it will:

1. Create storage/duckdb/ (if it doesn't exist)
2. Download the correct native library for your OS from the DuckDB GitHub Releases
3. Download the duckdb.h FFI header
4. Set the required environment variables (DUCKDB_LIB_PATH, DUCKDB_HEADER_PATH) at runtime

Subsequent boots detect the files are already present and skip the download (idempotent).

Supported platforms

Configuration

Publish the config file to override defaults:

Available .env variables:

[!NOTE] ext-zip must be enabled in your php.ini (it is bundled with PHP by default on most platforms). If the installer fails (e.g. no internet access), it logs the error and does not crash the application — allowing you to manage binaries manually.

Usage

You can use the DB facade to interact with DuckDB.

Querying Files

You can query files directly (Parquet, CSV, JSON) without pre-configuring tables using the file() helper:

Basic Queries

Analytical Queries (OLAP)

DuckDB shines at analytics. You can query Parquet, CSV, or JSON files directly.

php use Illuminate\Support\Facades\DB;

// 1. Get all users $users = DB::connection('duckdb')->table('users')->get();

// 2. Aggregate count $count = DB::connection('duckdb')->table('users')->count();

// 3. Conditional Fetch with Bindings $user = DB::connection('duckdb') ->table('users') ->where('id', 1) ->first();

// 4. Raw SQL Select $results = DB::connection('duckdb')->select("SELECT * FROM users WHERE email LIKE ?", ['%example.com']);

// 5. Analytical Query (DuckDB syntax) // e.g. Extract hour from timestamp $hourly = DB::connection('duckdb') ->select("SELECT date_part('hour', created_at) as hour, count(*) as count FROM users GROUP BY 1"); ini [ffi] ffi.enable=true bash composer install bash vendor/bin/phpunit