PHPackages satur.io/duckdb - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. satur.io/duckdb ActiveLibrary[Database & ORM](/categories/database) satur.io/duckdb =============== DuckDB API for PHP v2.0.4(2mo ago)7856.3k↓12.6%9[1 issues](https://github.com/satur-io/duckdb-php/issues)[3 PRs](https://github.com/satur-io/duckdb-php/pulls)3MITCPHP >=8.3CI passing Since Apr 13Pushed 2mo ago1 watchersCompare [ Source](https://github.com/satur-io/duckdb-php)[ Packagist](https://packagist.org/packages/satur.io/duckdb)[ Fund](https://ko-fi.com/saturio)[ RSS](/packages/saturio-duckdb/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (3)Versions (34)Used By (3) [![DuckDB logo](docs/DuckDB-PHP-logo-noborders.svg)](docs/DuckDB-PHP-logo-noborders.svg) DuckDB API for PHP ------------------ [](#duckdb-api-for-php) [![Github Actions Badge](https://github.com/satur-io/duckdb-php/actions/workflows/php_test_main.yml/badge.svg?branch=main)](https://github.com/satur-io/duckdb-php/actions)[![Github Actions Badge](https://github.com/satur-io/duckdb-php/actions/workflows/php_test_nightly.yml/badge.svg?branch=main)](https://github.com/satur-io/duckdb-php/actions)[![Quality Gate Status](https://camo.githubusercontent.com/d1fd606027390b251e76753c0fb6f8f175b408e9e1970435d0a3badaff9e6781/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d73617475722d696f5f6475636b64622d706870266d65747269633d616c6572745f73746174757326746f6b656e3d34613462643832656666383433643262346139336266343535326236646237386535393865636661)](https://sonarcloud.io/summary/new_code?id=satur-io_duckdb-php)[![Coverage](https://camo.githubusercontent.com/457675581f8280d58f4e25a158beb9a5e8a0a404c670e7f800199635b90b01a1/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d73617475722d696f5f6475636b64622d706870266d65747269633d636f766572616765)](https://sonarcloud.io/summary/new_code?id=satur-io_duckdb-php)[![Packagist Version](https://camo.githubusercontent.com/98dca9aa1ccd544ad48d78277632383c57252c82fd6fcbb4b8343ac31394be0f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73617475722e696f2f6475636b64623f7374796c653d666c6174266c6f676f3d7061636b6167697374266c6f676f436f6c6f723d7768697465)](https://packagist.org/packages/satur.io/duckdb)[![DuckDB C API Version](https://camo.githubusercontent.com/c241766f1bff477f685488a7a7a4bbd460bb9559f3d312a5b5841c7c0ecd768c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4475636b44425f435f4150492d76312e342e332d2532334646463130303f6c6f676f3d6475636b6462)](https://camo.githubusercontent.com/c241766f1bff477f685488a7a7a4bbd460bb9559f3d312a5b5841c7c0ecd768c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4475636b44425f435f4150492d76312e342e332d2532334646463130303f6c6f676f3d6475636b6462) This package provides a [DuckDB](https://github.com/duckdb/duckdb) Client API for PHP. Focused on performance, it uses the official [C API](https://duckdb.org/docs/api/c/overview.html) internally through [FFI](https://www.php.net/manual/en/book.ffi.php), achieving good benchmarks. This library is more than just a wrapper for the C API; it introduces custom, PHP-friendly methods to simplify working with DuckDB. It is compatible with Linux, Windows, and macOS, requiring PHP version 8.3 or higher. Full documentation is available in . ### Automatic install (recommended for newcomers) [](#automatic-install-recommended-for-newcomers) ``` composer require satur.io/duckdb-auto ``` Note You will need to allow `satur.io/duckdb-auto` to execute code to use this installation method, check [installation](https://duckdb-php.readthedocs.io/en/latest/installation) for more details. ### Quick Start [](#quick-start) ``` DuckDB::sql("SELECT 'quack' as my_column")->print(); ``` ``` ------------------- | my_column | ------------------- | quack | ------------------- ``` > It's that simple! 🦆 The function we used here, `DuckDB::sql()`, performs the query in a new in-memory database which is destroyed after retrieving the result. This is not the most common use case, let's see how to get a persistent connection. #### Connection [](#connection) ``` $duckDB = DuckDB::create('duck.db'); // or DuckDB::create() for in-memory database $duckDB->query('CREATE TABLE test (i INTEGER, b BOOL, f FLOAT);'); $duckDB->query('INSERT INTO test VALUES (3, true, 1.1), (5, true, 1.2), (3, false, 1.1), (3, null, 1.2);'); $duckDB->query('SELECT * FROM test')->print(); ``` As you probably guessed, `DuckDB::create()` creates a new connection to the specified database, or create a new one if it doesn't exist yet and then establishes the connection. After that, we can use the function `query` to perform the requests. Warning Notice the difference between the static method `sql` and the non-static method `query`. While the first one always creates and destroys a new in-memory database, the second one uses a previously established connection and should be the preferred option in most cases. In addition, the library also provides prepared statements for binding parameters to our query. #### Prepared Statements [](#prepared-statements) ``` $duckDB = DuckDB::create(); $duckDB->query('CREATE TABLE test (i INTEGER, b BOOL, f FLOAT);'); $duckDB->query('INSERT INTO test VALUES (3, true, 1.1), (5, true, 1.2), (3, false, 1.1), (3, null, 1.2);'); $boolPreparedStatement = $duckDB->preparedStatement('SELECT * FROM test WHERE b = $1'); $boolPreparedStatement->bindParam(1, true); $result = $boolPreparedStatement->execute(); $result->print(); $intPreparedStatement = $duckDB->preparedStatement('SELECT * FROM test WHERE i = ?'); $intPreparedStatement->bindParam(1, 3); $result = $intPreparedStatement->execute(); $result->print(); ``` #### Appenders [](#appenders) Appenders are the preferred method to load data in DuckDB. See [DuckDB docs](https://duckdb.org/docs/stable/clients/c/appender.html)for more information. ``` $duckDB = DuckDB::create(); $result = $duckDB->query('CREATE TABLE people (id INTEGER, name VARCHAR);'); $appender = $duckDB->appender('people'); for ($i = 0; $i < 100; ++$i) { $appender->appendRow(rand(1, 100000), 'string-'.rand(1, 100)); } $appender->flush(); ``` ### Upgrading from 1.x to 2.x [](#upgrading-from-1x-to-2x) See [upgrade from 1.x to 2.x docs](https://duckdb-php.readthedocs.io/en/latest/upgrade-1-to-2). ### DuckDB power [](#duckdb-power) DuckDB provides some amazing features. For example, you can query remote files directly. Let's use an aggregate function to calculate the average of a column for a parquet remote file: ``` DuckDB::sql( 'SELECT "Reporting Year", avg("Gas Produced, MCF") as "AVG Gas Produced" FROM "https://github.com/plotly/datasets/raw/refs/heads/master/oil-and-gas.parquet" WHERE "Reporting Year" BETWEEN 1985 AND 1990 GROUP BY "Reporting Year";' )->print(); ``` ``` -------------------------------------- | Reporting Year | AVG Gas Produce | -------------------------------------- | 1985 | 2461.4047344111 | | 1986 | 6060.8575605681 | | 1987 | 5047.5813074014 | | 1988 | 4763.4090541633 | | 1989 | 4175.2989758837 | | 1990 | 3706.9404742437 | -------------------------------------- ``` Or summarize a remote csv: ``` DuckDB::sql('SUMMARIZE TABLE "https://blobs.duckdb.org/data/Star_Trek-Season_1.csv";')->print(); ``` ``` ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | column_name | column_type | min | max | approx_unique | avg | std | q25 | q50 | q75 | count | null_percentage | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | season_num | BIGINT | 1 | 1 | 1 | 1.0 | 0.0 | 1 | 1 | 1 | 30 | 0 | | episode_num | BIGINT | 0 | 29 | 29 | 14.5 | 8.8034084308295 | 7 | 14 | 22 | 30 | 0 | | aired_date | DATE | 1965-02-28 | 1967-04-13 | 35 | | | 1966-10-20 | 1966-12-22 | 1967-02-16 | 30 | 0 | | cnt_kirk_hookup | BIGINT | 0 | 2 | 3 | 0.3333333333333 | 0.6064784348631 | 0 | 0 | 1 | 30 | 0 | ... ``` I would recommend taking a look at the [DuckDB documentation](https://duckdb.org/docs/stable/sql/introduction) to figure out all possibilities. Tip Do you want more use cases? Check the [examples folder](examples). ### Requirements [](#requirements) - Linux, macOS, or Windows - x64 platform - PHP >= 8.3 - ext-ffi #### Recommended [](#recommended) - ext-bcmath - Needed for big integers (> PHP\_INT\_MAX) - ext-zend-opcache - For better performance ### Type Support [](#type-support) From version 1.2.0 on the library supports all DuckDB file types. DuckDB TypeSQL TypePHP TypeDUCKDB\_TYPE\_BOOLEANBOOLEANboolDUCKDB\_TYPE\_TINYINTTINYINTintDUCKDB\_TYPE\_SMALLINTSMALLINTintDUCKDB\_TYPE\_INTEGERINTEGERintDUCKDB\_TYPE\_BIGINTBIGINTintDUCKDB\_TYPE\_UTINYINTUTINYINTintDUCKDB\_TYPE\_USMALLINTUSMALLINTintDUCKDB\_TYPE\_UINTEGERUINTEGERintDUCKDB\_TYPE\_UBIGINTUBIGINTSaturio\\DuckDB\\Type\\Math\\LongIntegerDUCKDB\_TYPE\_FLOATFLOATfloatDUCKDB\_TYPE\_DOUBLEDOUBLEfloatDUCKDB\_TYPE\_TIMESTAMPTIMESTAMPSaturio\\DuckDB\\Type\\TimestampDUCKDB\_TYPE\_DATEDATESaturio\\DuckDB\\Type\\DateDUCKDB\_TYPE\_TIMETIMESaturio\\DuckDB\\Type\\TimeDUCKDB\_TYPE\_INTERVALINTERVALSaturio\\DuckDB\\Type\\IntervalDUCKDB\_TYPE\_HUGEINTHUGEINTSaturio\\DuckDB\\Type\\Math\\LongIntegerDUCKDB\_TYPE\_UHUGEINTUHUGEINTSaturio\\DuckDB\\Type\\Math\\LongIntegerDUCKDB\_TYPE\_VARCHARVARCHARstringDUCKDB\_TYPE\_BLOBBLOBSaturio\\DuckDB\\Type\\BlobDUCKDB\_TYPE\_TIMESTAMP\_STIMESTAMP\_SSaturio\\DuckDB\\Type\\TimestampDUCKDB\_TYPE\_TIMESTAMP\_MSTIMESTAMP\_MSSaturio\\DuckDB\\Type\\TimestampDUCKDB\_TYPE\_TIMESTAMP\_NSTIMESTAMP\_NSSaturio\\DuckDB\\Type\\TimestampDUCKDB\_TYPE\_UUIDUUIDSaturio\\DuckDB\\Type\\UUIDDUCKDB\_TYPE\_TIME\_TZTIMETZSaturio\\DuckDB\\Type\\TimeDUCKDB\_TYPE\_TIMESTAMP\_TZTIMESTAMPTZSaturio\\DuckDB\\Type\\TimestampDUCKDB\_TYPE\_DECIMALDECIMALfloatDUCKDB\_TYPE\_ENUMENUMstringDUCKDB\_TYPE\_LISTLISTarrayDUCKDB\_TYPE\_STRUCTSTRUCTarrayDUCKDB\_TYPE\_ARRAYARRAYarrayDUCKDB\_TYPE\_MAPMAParrayDUCKDB\_TYPE\_UNIONUNIONmixedDUCKDB\_TYPE\_BITBITstringDUCKDB\_TYPE\_BIGNUMBIGNUMstringDUCKDB\_TYPE\_SQLNULLNULLnull### Other PHP DuckDB Integrations [](#other-php-duckdb-integrations) This project takes inspiration from [thbley/php-duckdb-integration](https://github.com/thbley/php-duckdb-integration) and [kambo-1st/duckdb-php](https://github.com/kambo-1st/duckdb-php). Without these prior works, **satur-io/duckdb-php** might not exist. However, there are some key differences: - **satur-io/duckdb-php** leverages all modern C API methods, avoiding deprecated ones. - It supports all major platforms (Linux, macOS, and Windows) and automatically selects the appropriate C library. - Prioritizes performance. - Simple to install and use. - Bundles all necessary resources into a single Composer package. ### Contributions Are Welcome [](#contributions-are-welcome) There are several open issues you can contribute to. Feel free to create new issues for feature requests or bug reports. Contributions of any kind are highly appreciated! If you'd like to contribute, please follow these steps: 1. Fork the repository. 2. Create a new branch for your feature or bug fix. 3. Commit your changes with clear and concise messages. 4. Submit a pull request with a detailed description of your changes. Note Please include tests for any new functionality or bug fixing. Thank you for helping improve this project! [ ![Buy Me a Coffee at ko-fi.com](https://camo.githubusercontent.com/9c2954de9676569df368bd1d7a03280d99c41d796ba57fd8f18d014d5369340c/68747470733a2f2f73746f726167652e6b6f2d66692e636f6d2f63646e2f6b6f6669342e706e673f763d36) ](https://ko-fi.com/saturio/tip) ### Health Score 57 — FairBetter than 98% of packages Maintenance83 Actively maintained with recent releases Popularity46 Moderate usage in the ecosystem Community21 Small or concentrated contributor base Maturity63 Established project with proven stability Bus Factor1 Top contributor holds 98.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~11 days Recently: every ~26 days Total 30 Last Release 87d ago Major Versions v1.2.1 → v2.0.0-beta.52025-10-16 ### Community Maintainers ![](https://www.gravatar.com/avatar/d1a3722df02d2f5a1cd74f96084c0d2b5830e2dfd687622470aae64e142ad14f?d=identicon)[saturio](/maintainers/saturio) --- Top Contributors [![dhernandez](https://avatars.githubusercontent.com/u/1096670?v=4)](https://github.com/dhernandez "dhernandez (175 commits)")[![ankane](https://avatars.githubusercontent.com/u/220358?v=4)](https://github.com/ankane "ankane (1 commits)")[![aszenz](https://avatars.githubusercontent.com/u/25319264?v=4)](https://github.com/aszenz "aszenz (1 commits)")[![Donnype](https://avatars.githubusercontent.com/u/46660228?v=4)](https://github.com/Donnype "Donnype (1 commits)") --- Tags databaseduckdbffiffi-bindingsffi-wrapperperformancephpphp-libraryphp8databaseperformanceffiduckdb ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/saturio-duckdb/health.svg) ``` [![Health](https://phpackages.com/badges/saturio-duckdb/health.svg)](https://phpackages.com/packages/saturio-duckdb) ``` ### Alternatives [bvanhoekelen/performance PHP performance tool analyser your script on time, memory usage and db query. Support Laravel and Composer for web, web console and command line interfaces. 521774.3k4](/packages/bvanhoekelen-performance)[sarfraznawaz2005/meter laravel package to find performance bottlenecks in your laravel application. 2498.1k](/packages/sarfraznawaz2005-meter)[msafadi/laravel-eloquent-join-with Laravel Eloquent Join With Relationships 1646.0k](/packages/msafadi-laravel-eloquent-join-with)[tommyknocker/pdo-database-class Framework-agnostic PHP database library with unified API for MySQL, MariaDB, PostgreSQL, SQLite, MSSQL, and Oracle. Query Builder, caching, sharding, window functions, CTEs, JSON, migrations, ActiveRecord, CLI tools, AI-powered analysis. Zero external dependencies. 845.7k](/packages/tommyknocker-pdo-database-class)[olliejones/index-wp-mysql-for-speed Speed up your WordPress site by adding high-performance keys (database indexes) to your MySQL database tables. 1481.8k](/packages/olliejones-index-wp-mysql-for-speed) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)