Download the PHP package thomas-0816/laravel-duckdb without Composer

Laravel Eloquent driver for DuckDB

A DuckDB database driver for Laravel Eloquent powered by the DuckDB PDO Driver.

Integrates DuckDB's analytical database engine into Laravel's Eloquent ORM and Schema Builder, enabling fast analytical queries directly from your Laravel application.

Requirements

• PHP 8.2+
• Laravel 12+
• pdo_duckdb PHP extension

Install and setup

Install and setup pdo_duckdb database driver with PIE:

Install and setup Laravel Eloquent driver for DuckDB:

pdo_duckdb is a native DuckDB database driver for the PHP Data Objects (PDO) interface.\ As a native PHP extension, it is implemented in C/C++ and does not require PHP FFI or preloading.\ It is also thread safe and fully tested with FrankenPHP (PHP-ZTS) and Swoole.\ The release packages contain pre-compiled binaries for all supported platforms and DuckDB is directly included.\ DuckDB extensions work the same way as they do in DuckDB CLI.

Configuration

Add a duckdb connection to your config/database.php:

In-Memory Database

For testing or reading external files, use the special in-memory database in config/database.php:

Schema Builder

Query Builder Insert

Query Builder Select

Eloquent Models

Models can be directly used by specifying the connection "duckdb":

Read CSV files with SQL Query Builder

Read CSV files with Eloquent Models

CSV data import with SQL Query Builder

Read JSON files with SQL Query Builder

Read JSON files with Eloquent Models

Read Parquet files with Eloquent Models

Apache Parquet: very fast and efficient column based storage file format containing one table of data.\ Each column is split into several column groups. Depending on the query, the file can be read partially by certain columns groups.\ Different compression or dictionary algorithms can be applied to each column. Also supports encryption.

Note: You can read and save Parquet files on local file systems or directly on S3 object storage.

Read and write Parquet files with SQL Query Builder

Read and write Excel files

Read public data using HTTPs, JSON, CSV and Parquet

Query weather data:

Download and query historical data from Deutsche Bahn:

Copy data from MariaDB to a Parquet file

Start a MariaDB container, create and fill "orders" table:

Use DuckDB MySQL extension to copy "orders" table from MariaDB to a Parquet file:

Copy data from PostgreSQL to a parquet file

Start PostgreSQL container, create and fill "orders" table:

Use DuckDB PostgreSQL extension to copy "orders" table from PostgreSQL to a Parquet file:

Schema and Query Builder for special types

Special types can be defined by using rawColumn():

Eloquent Models for special types

Special types can be defined by using rawColumn():

Vector Similarity Search (HNSW)

Views

Transactions

Community extensions

open_prompt integrates LLMs into your SQL queries:

More extensions: List of Core Extensions, List of Community Extensions

Note: Community extensions are third party projects, NOT maintained or reviewed by the DuckDB team.

Schema Dump

The package supports schema:dump Artisan command using DuckDB's EXPORT DATABASE SQL statement via PDO:

Query Debugging

You can add this line at the beginning of your script for local query debugging:

Performance

DuckDB is extremely fast when it comes to analytic queries.\ Here is an example with 10M rows, performing in 170ms on 4 threads with 128M ram:

Security

Use SQL SET variable = value; or put the settings inside the PDO::DUCKDB_ATTR_CONFIG connection options array:

A complete list is available in the DuckDB documentation: Securing DuckDB.

Laravel Octane and Swoole

Run queries concurrently:

Run queries every x seconds:

DuckDB only allows a single writer. So you can use multiple in-memory databases or\ open an existing database multiple times with read-only access mode in config/database.php:

Disconnect from databases after each request in config/octane.php to avoid side effects between requests:

Why DuckDB?

https://duckdb.org/why_duckdb

Like SQLite, DuckDB embeds directly into host applications as a library, eliminating the need for network serialization and separate server setups. It uses columnar storage and vectorized processing, running analytics 10–100x faster than traditional row-oriented databases. DuckDB spills data to disk if needed, allowing to process datasets much larger than available system RAM. It includes an advanced query optimizer that handles joins, subqueries, expressions and filters.\ DuckDB can directly query flat files (JSON, CSV, and Parquet) directly via SQL without needing to import the data first. Flat files can be read directly from disk, network attached storage or S3 comatible cloud storage.\ Data is processed in cache-friendly batches on a multi-core architecture, allowing modern hardware to operate on arrays of data simultaneously. For analytical queries that only require a few metrics, DuckDB reads only the relevant columns from disk/memory, saving I/O and CPU cycles. This brings data warehouse-level performance to any laptop or server.

FAQ

Do I need an extra server for DuckDB?

No. DuckDB runs completely embedded inside of PHP as an extension, just like SQLite.

How much RAM and CPU do I need for DuckDB?

DuckDB normally runs good with 1-4 GB RAM and 2-4 CPU cores.

How good is the compression with Parquet and zstd?

For logs you normally achieve compression rates of 50-100x.

Who is maintaining DuckDB?

The DuckDB project is owned and maintained by the DuckDB Foundation, a non-profit organization from Amsterdam.

Can I get support for DuckDB?

Yes. Support is available on GitHub, see the community support page for details.

Is the Laravel Eloquent driver for DuckDB developed by the DuckDB project?

No. This is a third-party open-source community project.

Is DuckDB fully open-source?

Yes. DuckDB and all components are fully open-source under the MIT license.

Development

AI Disclosure

The code is written by AI, reviewed and tested without AI.

License

MIT License